gloomberb 0.13.2 → 0.14.0

package/src/plugins/builtin/research/events-headless.ts

@@ -8,17 +8,16 @@ import type {
   HeadlessPaneDefinition,
   HeadlessPaneLoadArgs,
 } from "../../../types/plugin";
-import { formatCompact, formatNumber } from "../../../utils/format";
-import { buildEventRows } from "./event-model";
+import { formatEventMetric, buildEventRows, eventSourceNotice, CORPORATE_ACTION_COVERAGE } from "./event-model";
 
 const COLUMNS = [
   { key: "date", header: "Date" },
   { key: "status", header: "Event" },
   { key: "period", header: "Period" },
-  { key: "qEps", header: "Q EPS", align: "right" as const, format: (value: unknown) => value == null ? "-" : formatNumber(Number(value), 2) },
-  { key: "qRevenue", header: "Q revenue", align: "right" as const, format: (value: unknown) => value == null ? "-" : formatCompact(Number(value)) },
-  { key: "annualEps", header: "Annual EPS", align: "right" as const, format: (value: unknown) => value == null ? "-" : formatNumber(Number(value), 2) },
-  { key: "annualRevenue", header: "Annual revenue", align: "right" as const, format: (value: unknown) => value == null ? "-" : formatCompact(Number(value)) },
+  { key: "qEps", header: "Q EPS", align: "right" as const, format: (value: unknown, row: Record<string, unknown>) => formatEventMetric(value == null ? undefined : Number(value), typeof row.epsCurrency === "string" ? row.epsCurrency : undefined, "eps") },
+  { key: "qRevenue", header: "Q revenue", align: "right" as const, format: (value: unknown, row: Record<string, unknown>) => formatEventMetric(value == null ? undefined : Number(value), typeof row.revenueCurrency === "string" ? row.revenueCurrency : undefined, "revenue") },
+  { key: "annualEps", header: "Annual EPS", align: "right" as const, format: (value: unknown, row: Record<string, unknown>) => formatEventMetric(value == null ? undefined : Number(value), typeof row.epsCurrency === "string" ? row.epsCurrency : undefined, "eps") },
+  { key: "annualRevenue", header: "Annual revenue", align: "right" as const, format: (value: unknown, row: Record<string, unknown>) => formatEventMetric(value == null ? undefined : Number(value), typeof row.revenueCurrency === "string" ? row.revenueCurrency : undefined, "revenue") },
   { key: "value", header: "Value", align: "right" as const },
   { key: "detail", header: "Detail" },
 ];
@@ -28,6 +27,9 @@ export interface EventHeadlessData {
   estimates: AnalystResearchData | null;
   financials: TickerFinancials | null;
   currency: string;
+  actionsError?: string | null;
+  estimatesError?: string | null;
+  financialsError?: string | null;
 }
 
 export interface EventsHeadlessDependencies {
@@ -40,21 +42,25 @@ export interface EventsHeadlessDependencies {
 
 const defaultDependencies: EventsHeadlessDependencies = {
   async load(_args, symbol, provider) {
-    if (!provider.getCorporateActions) {
-      throw new Error("Corporate actions source unavailable");
-    }
-    const [actions, estimates, financials] = await Promise.all([
-      provider.getCorporateActions(symbol, ""),
+    const [actions, estimates, financials] = await Promise.allSettled([
+      provider.getCorporateActions ? provider.getCorporateActions(symbol, "") : Promise.reject(new Error("Corporate actions source unavailable")),
       provider.getAnalystResearch
-        ? provider.getAnalystResearch(symbol, "").catch(() => null)
-        : null,
-      provider.getTickerFinancials(symbol, "").catch(() => null),
+        ? provider.getAnalystResearch(symbol, "")
+        : Promise.reject(new Error("Analyst estimates source unavailable")),
+      provider.getTickerFinancials(symbol, ""),
     ]);
+    const actionsData = actions.status === "fulfilled" ? actions.value : null;
+    const estimatesData = estimates.status === "fulfilled" ? estimates.value : null;
+    const financialsData = financials.status === "fulfilled" ? financials.value : null;
+    const error = (result: PromiseSettledResult<unknown>) => result.status === "rejected" ? String(result.reason instanceof Error ? result.reason.message : result.reason) : null;
     return {
-      actions,
-      estimates,
-      financials,
-      currency: actions.currency ?? estimates?.currency ?? financials?.quote?.currency ?? "USD",
+      actions: actionsData,
+      estimates: estimatesData,
+      financials: financialsData,
+      actionsError: error(actions),
+      estimatesError: error(estimates),
+      financialsError: error(financials),
+      currency: actionsData?.currency ?? estimatesData?.currency ?? financialsData?.quote?.currency ?? "USD",
     };
   },
 };
@@ -75,10 +81,21 @@ export function createEventsHeadless(
     async load(args, ctx) {
       const symbol = args.symbols[0]!;
       const data = await dependencies.load(args, symbol, ctx.marketData);
+      const notice = eventSourceNotice({ variant: "corporate-actions", symbol,
+        actions: data.actions, actionsError: data.actionsError ?? null,
+        estimates: data.estimates, estimatesError: data.estimatesError ?? null });
+      const errors = [notice?.failed ? notice.text : null,
+        data.financialsError ? `Financial statements unavailable: ${data.financialsError}` : null,
+      ].filter((error): error is string => !!error);
       return {
         rows: buildEventRows(data.actions, data.estimates, data.financials, data.currency)
           .map((row) => ({ ...row })),
-        metadata: { symbol, currency: data.currency },
+        errors: errors.length > 0 ? errors : undefined,
+        metadata: { symbol, currency: data.currency, coverage: data.actions?.coverage,
+          coverageNote: CORPORATE_ACTION_COVERAGE,
+          actionsFetchedAt: data.actions?.fetchedAt, estimatesFetchedAt: data.estimates?.fetchedAt,
+          ...(notice ? { notice: notice.text } : {}),
+        },
       };
     },
   };

package/src/plugins/builtin/research/headless-schema.ts

@@ -0,0 +1,16 @@
+import type { HeadlessPaneDefinition } from "../../../types/headless";
+
+type PaneSchema = Pick<HeadlessPaneDefinition, "argument" | "options" | "discovery">;
+
+export const paneSchemas = {
+  "relative-valuation-pane": {
+    argument: { kind: "tickers" },
+    options: [],
+    discovery: {
+      id: "relative-valuation",
+      aliases: ["relative valuation", "peer valuation", "valuation comps", "compare multiples"],
+      limitations: ["Uses current provider fundamentals rather than a historical series."],
+      screenshotReadiness: "partial",
+    },
+  },
+} satisfies Record<string, PaneSchema>;

package/src/plugins/builtin/research/headless.test.ts

@@ -53,6 +53,24 @@ function args(options: Record<string, string | number | boolean>): HeadlessPaneL
 const context = {} as HeadlessPaneContext;
 
 describe("earnings estimates headless", () => {
+  test("all excludes cash actions and reported excludes pending announcements and statement TTM", async () => {
+    const definition = createEarningsEstimatesHeadless({ loadSources: async () => ({ ...sources, actions: { ...sources.actions!,
+      dividends: [{ exDate: "2026-07-01", amount: 1 }],
+      earnings: [...sources.actions!.earnings, { date: "2026-10-01", epsEstimate: 1 }],
+    } }) });
+    const all = await definition.load(args({ kind: "all" }), context);
+    expect(all.rows.some((row) => row.status === "Dividend")).toBe(false);
+    const reported = await definition.load(args({ kind: "reported" }), context);
+    expect(reported.rows).toHaveLength(1);
+    expect(reported.rows[0]).toMatchObject({ epsActual: 0.48, epsEstimate: 0.45, epsDifference: 0.03, surprisePercent: 6.67 });
+  });
+
+  test("stale source rows remain usable while reporting incomplete coverage", async () => {
+    const definition = createEarningsEstimatesHeadless({ loadSources: async () => ({ ...sources, actions: { ...sources.actions!, stale: true } }) });
+    const result = await definition.load(args({ kind: "all" }), context);
+    expect(result.rows.length).toBeGreaterThan(0);
+    expect(result.errors?.join(" ")).toContain("stale");
+  });
   test("maps the shared event model into estimate rows", async () => {
     const definition = createEarningsEstimatesHeadless({
       loadSources: async () => sources,

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

@@ -9,16 +9,16 @@ import type {
   HeadlessPaneLoadArgs,
   HeadlessRowsResult,
 } from "../../../types/plugin";
-import { buildEventRows, type EventRow } from "./event-model";
+import { formatEventMetric, buildEventRows, eventSourceNotice, type EventRow } from "./event-model";
 
 const ESTIMATE_COLUMNS = [
   { key: "date", header: "Date" },
   { key: "status", header: "Event" },
   { key: "period", header: "Period" },
-  { key: "qEps", header: "Q EPS", align: "right" as const },
-  { key: "qRevenue", header: "Q revenue", align: "right" as const },
-  { key: "annualEps", header: "Annual EPS", align: "right" as const },
-  { key: "annualRevenue", header: "Annual revenue", align: "right" as const },
+  { key: "qEps", header: "Q EPS", align: "right" as const, format: (value: unknown, row: Record<string, unknown>) => formatEventMetric(value == null ? undefined : Number(value), typeof row.epsCurrency === "string" ? row.epsCurrency : undefined, "eps") },
+  { key: "qRevenue", header: "Q revenue", align: "right" as const, format: (value: unknown, row: Record<string, unknown>) => formatEventMetric(value == null ? undefined : Number(value), typeof row.revenueCurrency === "string" ? row.revenueCurrency : undefined, "revenue") },
+  { key: "annualEps", header: "Annual EPS", align: "right" as const, format: (value: unknown, row: Record<string, unknown>) => formatEventMetric(value == null ? undefined : Number(value), typeof row.epsCurrency === "string" ? row.epsCurrency : undefined, "eps") },
+  { key: "annualRevenue", header: "Annual revenue", align: "right" as const, format: (value: unknown, row: Record<string, unknown>) => formatEventMetric(value == null ? undefined : Number(value), typeof row.revenueCurrency === "string" ? row.revenueCurrency : undefined, "revenue") },
   { key: "value", header: "Value", align: "right" as const },
   { key: "detail", header: "Detail" },
 ];
@@ -83,9 +83,9 @@ const defaultDependencies: EarningsEstimatesHeadlessDependencies = {
 };
 
 function matchesKind(row: EventRow, kind: string): boolean {
-  if (kind === "all") return true;
+  if (kind === "all") return ["Earnings", "Q Est", "FY Est", "TTM"].includes(row.status);
   if (kind === "estimates") return row.status === "Q Est" || row.status === "FY Est";
-  return row.status === "Earnings" || row.status === "TTM";
+  return row.status === "Earnings" && row.earningsState === "reported";
 }
 
 export function projectEarningsEstimatesHeadless(
@@ -101,17 +101,28 @@ export function projectEarningsEstimatesHeadless(
     sources.currency,
   ).filter((row) => matchesKind(row, kind));
   const rows = matching.slice(0, limit).map((row) => ({ ...row }));
+  const notice = eventSourceNotice({ variant: "earnings-estimates", symbol: args.symbols[0] ?? String(args.argument ?? ""),
+    actions: sources.actions, estimates: sources.estimates,
+    actionsError: sources.actions ? null : "Source unavailable", estimatesError: sources.estimates ? null : "Source unavailable",
+  });
+  const errors = [...(sources.errors ?? []), ...(notice?.failed ? [notice.text] : [])];
+  const unmatchedReportedPeriods = matching.filter((row) => row.earningsState === "reported" && !row.fiscalPeriodEnd).map((row) => row.date);
+  if (unmatchedReportedPeriods.length) errors.push(`No statement period identified for ${unmatchedReportedPeriods.length} reported earnings row(s); quarterly revenue is unavailable.`);
 
   return {
     columns: ESTIMATE_COLUMNS,
     rows,
-    errors: sources.errors?.length ? sources.errors : undefined,
+    errors: errors.length ? errors : undefined,
     metadata: {
       currency: sources.currency,
       kind,
       total: matching.length,
       returned: rows.length,
       truncated: rows.length < matching.length,
+      coverageNote: notice?.text,
+      epsBasis: "Provider EPS and consensus may be adjusted; accounting basis is unspecified. TTM EPS comes from statements.",
+      dateNote: "Fiscal period dates are not announcement dates. Revenue is attached only to an identified statement period.",
+      unmatchedReportedPeriods,
     },
   };
 }

package/src/plugins/builtin/research/index.test.ts

@@ -8,7 +8,8 @@ import {
   sortRatingRows,
   type RatingSortPreference,
 } from "./analyst-pane";
-import { buildEventRows, matchEarningsSecFiling } from "./corporate-actions-pane";
+import { buildEventDetailBody, buildEventRows, matchEarningsSecFiling } from "./corporate-actions-pane";
+import { eventSourceNotice } from "./event-model";
 
 const ratings: AnalystRatingRecord[] = [
   {
@@ -174,11 +175,28 @@ describe("analyst summary", () => {
     } satisfies AnalystResearchData);
 
     expect(lines[0]).toBe("low $225.00   med $482.50   high $625.00");
-    expect(lines[1]).toBe("rating 8.8/10   SB 12  B 18  H 4  S 1   35 analysts (month)");
+    expect(lines[1]).toBe("Upside reference price $467.50");
+    expect(lines[2]).toBe("rating 8.8/10   SB 12  B 18  H 4  S 1   35 analysts (month)");
   });
 });
 
 describe("event rows", () => {
+  test("estimate drilldown and JSON retain distinct EPS/revenue inputs, currencies and attribution", () => {
+    const eps = { date: "2026-09-30", period: "current quarter", currency: "USD", average: 4.4, low: 4, high: 5, yearAgo: 0, growth: 0, analysts: 12 };
+    const revenue = { date: eps.date, period: eps.period, currency: "TWD", average: 1.45e12, low: 1.4e12, high: 1.5e12, yearAgo: 1e12, growth: .45, analysts: 20 };
+    const rows = buildEventRows(null, { symbol: "TSM", providerId: "yahoo", fetchedAt: "2026-09-11T12:00:00Z",
+      recommendations: [], ratings: [], earningsEstimates: [eps], revenueEstimates: [revenue] }, null, "USD");
+    const row = JSON.parse(JSON.stringify(rows[0]));
+    expect(row).toMatchObject({ estimateInputs: { eps, revenue }, estimateGrowthMetric: "eps", providerId: "yahoo", fetchedAt: "2026-09-11T12:00:00Z" });
+    const detail = buildEventDetailBody({ row, secFilingsLoading: false, filing: null, documents: [], documentsLoading: false,
+      inlineContent: new Map(), primaryContent: null, primaryContentLoading: false });
+    expect(detail).toContain("Low: 4 USD | High: 5 USD");
+    expect(detail).toContain("Low: 1,400,000,000,000 TWD | High: 1,500,000,000,000 TWD");
+    expect(detail).toContain("Prior-year input: 0 USD");
+    expect(detail).toContain("Provider growth: 0.00%");
+    expect(detail).toContain("Provider growth: +45.00%");
+  });
+
   test("combines EPS and revenue estimates into one estimate row", () => {
     const rows = buildEventRows(null, {
       symbol: "AAPL",
@@ -258,7 +276,7 @@ describe("event rows", () => {
       dividends: [],
       splits: [],
       earnings: [
-        { date: "2026-05-01", epsActual: 1.24, surprisePercent: 4.2 },
+        { date: "2026-03-31", dateType: "fiscal-period-end" as const, epsActual: 1.24, surprisePercent: 4.2 },
       ],
     };
     const financials = {
@@ -271,7 +289,7 @@ describe("event rows", () => {
     };
     const rows = buildEventRows(actions, null, financials, "USD");
 
-    const earnings = rows.find((row) => row.id === "earn:2026-05-01");
+    const earnings = rows.find((row) => row.status === "Earnings" && row.date === "2026-03-31");
     const ttm = rows.find((row) => row.status === "TTM");
 
     expect(earnings).toMatchObject({
@@ -325,7 +343,7 @@ describe("event rows", () => {
     expect(rows).toMatchObject([
       { id: "div:2026-02-10", status: "Dividend", value: "$0.26" },
       { id: "earn:2026-01-30", status: "Earnings" },
-      { id: "split:2025-12-01:4-for-1 split", status: "Split", value: "1:4" },
+      { id: "split:2025-12-01:4-for-1 split", status: "Factor", value: "4:1" },
     ]);
     expect(rows[0]?.qEps).toBeUndefined();
     expect(rows[0]?.annualEps).toBeUndefined();
@@ -360,5 +378,55 @@ describe("event rows", () => {
     ];
 
     expect(matchEarningsSecFiling(row, filings)?.accessionNumber).toBe("0000320193-26-000009");
+    expect(matchEarningsSecFiling({ ...row!, dateType: "fiscal-period-end" }, filings)).toBeNull();
+    const periodRow = { ...row!, dateType: "fiscal-period-end" as const,
+      dateEvidence: { accessionNumber: "0000320193-26-000010", filed: "2026-02-04", startDate: "2025-10-01" } };
+    expect(matchEarningsSecFiling(periodRow, filings)?.form).toBe("10-Q");
+    const detail = buildEventDetailBody({ row: periodRow, secFilingsLoading: false,
+      filing: filings[0]!, documents: [], documentsLoading: false, inlineContent: new Map(),
+      primaryContent: "Fiscal statement content", primaryContentLoading: false });
+    expect(detail).toContain("Fiscal statement content");
+  });
+});
+
+describe("event source notice", () => {
+  const loaded = {
+    variant: "corporate-actions" as const,
+    symbol: "DBK",
+    actions: { symbol: "DBK", dividends: [{ exDate: "2026-05-29", amount: 1 }], splits: [], earnings: [] },
+    actionsError: null,
+    estimates: {
+      symbol: "DBK",
+      recommendations: [],
+      ratings: [],
+      earningsEstimates: [{ date: "2026-12-31", period: "current_year", average: 3.3, analysts: 10 }],
+      revenueEstimates: [],
+    } satisfies AnalystResearchData,
+    estimatesError: null,
+  };
+
+  test("stays quiet when both sources delivered", () => {
+    expect(eventSourceNotice(loaded)).toBeNull();
+  });
+
+  /**
+   * A failed corporate-actions request left the table showing only estimate and
+   * TTM rows, which reads as a working pane for a company with no events.
+   */
+  test("names a failed source and marks it as a failure", () => {
+    expect(eventSourceNotice({ ...loaded, actions: null, actionsError: "Cloud request failed" })).toEqual({
+      text: "Corporate actions unavailable: Cloud request failed",
+      failed: true,
+    });
+  });
+
+  test("reports genuinely empty data without calling it a failure", () => {
+    expect(eventSourceNotice({
+      ...loaded,
+      actions: { symbol: "DBK", dividends: [], splits: [], earnings: [] },
+    })).toEqual({
+      text: "No dividends, splits, or reported earnings for DBK",
+      failed: false,
+    });
   });
 });

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

@@ -5,6 +5,7 @@ import { AnalystResearchView } from "./analyst-pane";
 import { CorporateActionsView } from "./corporate-actions-pane";
 import { EquityDiagnosticView } from "./equity-diagnostic-pane";
 import { RelativeValuationPane } from "./relative-valuation-pane";
+import { relativeValuationHeadless } from "./relative-valuation-headless";
 import { analystResearchHeadless } from "./analyst-headless";
 import { eventsHeadless } from "./events-headless";
 import { earningsEstimatesHeadless } from "./headless";
@@ -84,6 +85,7 @@ export const researchModule: PluginModule = {
       name: "Relative Valuation",
       icon: "R",
       component: RelativeValuationPane,
+      headless: relativeValuationHeadless,
       defaultPosition: "right",
       defaultMode: "floating",
       defaultFloatingSize: { width: 104, height: 24 },
@@ -146,6 +148,7 @@ export const researchModule: PluginModule = {
     },
     {
       id: "relative-valuation-pane",
+      headless: relativeValuationHeadless,
       paneId: "relative-valuation",
       label: "Relative Valuation",
       description: "Compare valuation and operating metrics across peers.",

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

@@ -0,0 +1,192 @@
+import { expect, test } from "bun:test";
+import type { HeadlessPaneContext } from "../../../types/headless";
+import { createTestDataProvider } from "../../../test-support/data-provider";
+import { comparableMarketCap, relativeValuationValues } from "./relative-valuation-model";
+import { relativeValuationHeadless } from "./relative-valuation-headless";
+
+test("fresh quotes do not hide stale fundamentals in a peer research report", async () => {
+  const symbols = ["BAC", "JPM"];
+  let stale = true;
+  const ctx = { signal: new AbortController().signal, marketData: createTestDataProvider({
+    async getTickerFinancials(symbol) {
+      return { annualStatements: [], quarterlyStatements: [], priceHistory: [],
+        quote: { symbol, price: 60, change: 0, changePercent: 0, currency: "USD", lastUpdated: 1789567200000, stale: false, marketCap: 420e9 },
+        fundamentals: { trailingPE: 13.94, financialCurrency: "USD", source: "yahoo" as const,
+          fetchedAt: "2026-09-14T17:23:38.462Z", stale: symbol === "BAC" && stale },
+      };
+    },
+  }) } as HeadlessPaneContext;
+  const args = { symbols, argument: symbols, rawArgument: symbols.join(" "), options: {} };
+  const report = await relativeValuationHeadless.load(args, ctx);
+  expect(report.complete).toBe(false);
+  expect(report.metadata?.staleFundamentalsSymbols).toEqual(["BAC"]);
+  expect(report.errors).toEqual(["BAC: Fundamentals stale: retained values may be out of date"]);
+  expect(report.rows[0]).toMatchObject({ price: 60, trailingPE: 13.94, fundamentalsProvenance: { stale: true } });
+  stale = false;
+  const refreshed = await relativeValuationHeadless.load(args, ctx);
+  expect(refreshed.complete).toBe(true);
+  expect(refreshed.errors).toEqual([]);
+  expect(refreshed.metadata?.staleFundamentalsSymbols).toEqual([]);
+});
+
+test("relative valuations share derived metrics, preserve zeroes, and identify missing peers", async () => {
+  const symbols = ["GOOD", "ZERO", "EMPTY", "MISSING"];
+  const ctx = {
+    signal: new AbortController().signal,
+    marketData: createTestDataProvider({
+      async getTickerFinancials(symbol) {
+        if (symbol === "MISSING") throw new Error("Unavailable");
+        const empty = { annualStatements: [], quarterlyStatements: [], priceHistory: [] };
+        if (symbol === "EMPTY") return empty;
+        return {
+          ...empty,
+          quote: { symbol, price: 10, change: 1, changePercent: 10, currency: "USD", lastUpdated: 1, marketCap: symbol === "ZERO" ? 0 : 100 },
+          fundamentals: { financialCurrency: "USD", enterpriseValue: 200, revenue: symbol === "ZERO" ? 0 : 50, freeCashFlow: 5, revenueGrowth: 0, lastQuarterGrowth: 0.2, operatingMargin: 0.1 },
+        };
+      },
+    }),
+  } as HeadlessPaneContext;
+  const result = await relativeValuationHeadless.load({ symbols, argument: symbols, rawArgument: symbols.join(","), options: {} }, ctx);
+  expect(result.rows[0]).toMatchObject({ evSales: 4, fcfYield: 0.05, revenueGrowth: 0, operatingMargin: 0.1 });
+  expect(result.rows[1]).toMatchObject({ marketCap: 0, evSales: null, fcfYield: null, revenueGrowth: 0 });
+  expect(result.unavailableSymbols).toEqual(["MISSING", "EMPTY"]);
+  expect(result.errors).toEqual(["MISSING: Unavailable"]);
+});
+
+
+test("relative valuation does not divide unconverted foreign cash flows by a USD market value", () => {
+  const financials = {
+    annualStatements: [], quarterlyStatements: [], priceHistory: [], financialCurrency: "TWD",
+    quote: { symbol: "TSM", price: 200, change: 0, changePercent: 0, currency: "USD", lastUpdated: 1, marketCap: 100 },
+    fundamentals: { financialCurrency: "TWD", enterpriseValue: 110, revenue: 1000, freeCashFlow: 300, operatingMargin: 0.4 },
+  };
+  expect(relativeValuationValues(financials)).toMatchObject({ evSales: null, fcfYield: null, operatingMargin: 0.4 });
+  // Converted summary fundamentals are independent of the statement currency.
+  financials.fundamentals.financialCurrency = "";
+  expect(relativeValuationValues(financials)).toMatchObject({ evSales: null, fcfYield: null });
+  financials.fundamentals.financialCurrency = "USD";
+  expect(relativeValuationValues(financials)).toMatchObject({ evSales: 0.11, fcfYield: 3 });
+});
+
+
+test("peer market caps convert before ranking and missing FX never becomes a 1:1 conversion", () => {
+  const rates = new Map([["JPY", 0.0065], ["GBP", 1.3]]);
+  expect(comparableMarketCap(1e12, "JPY", "USD", rates)).toBe(6.5e9);
+  expect(comparableMarketCap(1e9, "GBP", "USD", rates)).toBe(1.3e9);
+  expect(comparableMarketCap(1e9, "EUR", "USD", rates)).toBeNull();
+});
+
+
+test("provider EV/S requires verified compatible reporting units even when a ratio is supplied", () => {
+  // Reproduces the ADR summary whose vendor EV is inconsistent with its market cap.
+  const financials = { annualStatements: [], quarterlyStatements: [], priceHistory: [], financialCurrency: "TWD",
+    quote: { symbol: "TSM", price: 426.22, change: 0, changePercent: 0, currency: "USD", lastUpdated: 1, marketCap: 2_257_983_274_434 },
+    fundamentals: { financialCurrency: undefined as string | undefined, enterpriseToRevenue: 3.56, enterpriseValue: 501_458_070_727, revenue: 140_865_738_606 },
+  };
+  expect(relativeValuationValues(financials)).toMatchObject({ evSales: null, marketCap: 2_257_983_274_434 });
+  financials.fundamentals.financialCurrency = "TWD";
+  expect(relativeValuationValues(financials).evSales).toBeNull();
+
+  // A separately verified summary currency permits the provider ratio; the
+  // statement currency never supplies missing summary metadata.
+  financials.fundamentals = { financialCurrency: "USD", enterpriseToRevenue: 4.2, enterpriseValue: 100, revenue: 25 };
+  expect(relativeValuationValues(financials).evSales).toBe(4.2);
+  financials.fundamentals.enterpriseToRevenue = NaN;
+  expect(relativeValuationValues(financials).evSales).toBe(4);
+});
+
+test("loss-making peers retain reported multiples without ranking them as cheap earnings", async () => {
+  const financials = { annualStatements: [], quarterlyStatements: [], priceHistory: [],
+    quote: { symbol: "LOSS", price: 16, currency: "USD", change: 0, changePercent: 0, lastUpdated: 1, marketCap: 100 },
+    fundamentals: { trailingPE: -5.2, forwardPE: -9, financialCurrency: "USD", freeCashFlow: -20 } };
+  const ctx = { signal: new AbortController().signal,
+    marketData: createTestDataProvider({ getTickerFinancials: async () => financials }) } as HeadlessPaneContext;
+  const result = await relativeValuationHeadless.load({ symbols: ["LOSS"], argument: ["LOSS"], rawArgument: "LOSS", options: {} }, ctx);
+  expect(result.rows[0]).toMatchObject({ trailingPE: null, forwardPE: null, fcfYield: -0.2,
+    reportedMultiples: { trailingPE: -5.2, forwardPE: -9 } });
+  for (const key of ["trailingPE", "forwardPE"]) {
+    const column = relativeValuationHeadless.columns!.find((column) => column.key === key)!;
+    expect(column.format!(result.rows[0]![key], result.rows[0]!)).toBe("N/M");
+  }
+  expect(financials.fundamentals).toMatchObject({ trailingPE: -5.2, forwardPE: -9, freeCashFlow: -20 });
+});
+
+test("qualified peers retain dated fundamental caps after stale quote removal and preserve cash-flow currency boundaries", async () => {
+  const base = { annualStatements: [], quarterlyStatements: [], priceHistory: [],
+    fundamentals: { marketCap: 55_866_216_448, marketCapCurrency: "USD", financialCurrency: "USD",
+      freeCashFlow: -7_940_250_112, source: "yahoo" as const, fetchedAt: "2026-09-11T15:23:57.311Z", stale: false } };
+  const values = relativeValuationValues(base);
+  expect(values).toMatchObject({ price: null, currency: null, marketCap: base.fundamentals.marketCap, marketCapCurrency: "USD",
+    marketCapProvenance: { kind: "fundamentals", source: "yahoo", retrievedAt: base.fundamentals.fetchedAt, stale: false } });
+  expect(values.fcfYield).toBeCloseTo(-7_940_250_112 / 55_866_216_448, 12);
+  expect(relativeValuationValues({ ...base, fundamentals: { ...base.fundamentals, financialCurrency: undefined } }).fcfYield).toBeNull();
+  expect(relativeValuationValues({ ...base, fundamentals: { ...base.fundamentals, financialCurrency: "EUR" } }).fcfYield).toBeNull();
+
+  const requested: Array<[string, string | undefined]> = [];
+  const ctx = { signal: new AbortController().signal,
+    marketData: createTestDataProvider({ async getTickerFinancials(symbol, exchange) { requested.push([symbol, exchange]); return base; } }) } as HeadlessPaneContext;
+  const result = await relativeValuationHeadless.load({ symbols: ["F:XNYS"], argument: ["F:XNYS"], rawArgument: "F:XNYS", options: {} }, ctx);
+  expect(result.rows[0]).toMatchObject({ symbol: "F:XNYS", marketCapCurrency: "USD", marketCapProvenance: values.marketCapProvenance });
+  expect(result.unavailableSymbols).toEqual([]);
+  expect(requested).toEqual([["F", "NYSE"]]);
+  expect(result.metadata?.marketCapBasis).toContain("retrieval time is not a valuation date");
+});
+
+test("a foreign fundamental capitalization converts in its own currency, independently of the quote", () => {
+  const financials = { annualStatements: [], quarterlyStatements: [], priceHistory: [],
+    quote: { symbol: "TSM", price: 200, currency: "USD", change: 0, changePercent: 0, lastUpdated: 1 },
+    fundamentals: { marketCap: 1000, marketCapCurrency: "TWD", financialCurrency: "TWD", freeCashFlow: 100 } };
+  const row = relativeValuationValues(financials);
+  expect(row).toMatchObject({ price: 200, currency: "USD", marketCap: 1000, marketCapCurrency: "TWD", fcfYield: 0.1 });
+  expect(comparableMarketCap(row.marketCap, row.marketCapCurrency, "USD", new Map([["TWD", 0.03]]))).toBe(30);
+  expect(comparableMarketCap(row.marketCap, row.marketCapCurrency, "USD", new Map())).toBeNull();
+});
+
+test("stale quotes cannot rank as current prices or seed quote-based cash-flow yields", async () => {
+  const observed = { annualStatements: [], quarterlyStatements: [], priceHistory: [],
+    // Condensed source boundary from the captured PLD financials response: the
+    // financials envelope succeeded while its embedded quote was explicitly stale.
+    quote: { symbol: "PLD", price: 135.75, change: 1.34, changePercent: .9969496317, currency: "USD",
+      lastUpdated: 1789167600002, stale: true, marketCap: 131961405440, providerId: "gloomberb-cloud", dataSource: "delayed" as const },
+    fundamentals: { trailingPE: 30.233854, freeCashFlow: 5406941184, financialCurrency: "USD", operatingMargin: .4,
+      source: "yahoo" as const, fetchedAt: "2026-09-11T23:52:16.139Z", stale: false } };
+  const raw = structuredClone(observed);
+  const values = relativeValuationValues(observed);
+  expect(values).toMatchObject({ price: null, changePercent: null, marketCap: null, fcfYield: null,
+    quoteStale: true, quoteAsOf: observed.quote.lastUpdated, trailingPE: 30.233854, operatingMargin: .4,
+    reportedQuote: { price: 135.75, stale: true, marketCap: observed.quote.marketCap, lastUpdated: observed.quote.lastUpdated },
+    fundamentalsProvenance: { source: "yahoo", retrievedAt: observed.fundamentals.fetchedAt, stale: false } });
+  expect(observed).toEqual(raw);
+  const ctx = { signal: new AbortController().signal, marketData: createTestDataProvider({
+    getTickerFinancials: async (symbol) => symbol === "MISSING" ? Promise.reject(new Error("source unavailable"))
+      : { ...observed, quote: { ...observed.quote, symbol, stale: symbol === "PLD" } },
+  }) } as HeadlessPaneContext;
+  const symbols = ["PLD", "FRESH", "MISSING"];
+  const result = await relativeValuationHeadless.load({ symbols, argument: symbols, rawArgument: symbols.join(","), options: {} }, ctx);
+  expect(result.complete).toBe(false);
+  expect(result.errors).toContain("PLD: Quote stale: quote-based values unavailable");
+  expect(result.errors).toContain("MISSING: source unavailable");
+  expect(result.unavailableSymbols).toEqual(["MISSING"]);
+  expect(result.metadata?.staleSymbols).toEqual(["PLD"]);
+  expect(result.rows[1]).toMatchObject({ price: 135.75, changePercent: observed.quote.changePercent,
+    marketCap: observed.quote.marketCap, quoteStale: false });
+  expect(Number(result.rows[1]!.fcfYield)).toBeCloseTo(observed.fundamentals.freeCashFlow / observed.quote.marketCap, 12);
+  const priceColumn = relativeValuationHeadless.columns!.find((column) => column.key === "price")!;
+  expect(priceColumn.format!(result.rows[0]!.price, result.rows[0]!)).toBe("-");
+  expect(relativeValuationHeadless.columns!.find((column) => column.key === "trailingPE")!.format!(values.trailingPE, values)).toBe("30.2");
+});
+
+test("a stale quote may use an independent fundamental cap with its own source and currency", async () => {
+  const financials = { annualStatements: [], quarterlyStatements: [], priceHistory: [],
+    quote: { symbol: "DUAL", price: 50, change: 1, changePercent: 2, currency: "USD", lastUpdated: 1789167600002, stale: true, marketCap: 500 },
+    fundamentals: { marketCap: 100, marketCapCurrency: "EUR", freeCashFlow: 5, financialCurrency: "EUR", source: "yahoo" as const,
+      fetchedAt: "2026-09-11T23:52:16.139Z", stale: false } };
+  const values = relativeValuationValues(financials);
+  expect(values).toMatchObject({ price: null, marketCap: 100, marketCapCurrency: "EUR", fcfYield: .05,
+    marketCapProvenance: { kind: "fundamentals", source: "yahoo", retrievedAt: financials.fundamentals.fetchedAt, stale: false } });
+  const recovered = relativeValuationValues({ ...financials, quote: { ...financials.quote, stale: false } });
+  expect(recovered).toMatchObject({ price: 50, marketCap: 500, marketCapCurrency: "USD", fcfYield: null, quoteStale: false });
+  const unknown = relativeValuationValues({ ...financials, quote: { ...financials.quote, stale: undefined } });
+  expect(unknown.quoteStale).toBeNull();
+  expect(unknown.reportedQuote?.stale).toBeNull();
+});

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

@@ -0,0 +1,51 @@
+import { formatPriceEarnings, PRICE_EARNINGS_NOTICE } from "../../../utils/price-earnings";
+import type { HeadlessPaneDefinition } from "../../../types/headless";
+import { formatCurrency, formatNumber, formatPercent } from "../../../utils/format";
+import { loadHeadlessFinancials, loadHeadlessSymbols } from "../shared/headless-market-data";
+import { RELATIVE_VALUATION_STALE_FUNDAMENTALS_NOTICE, RELATIVE_VALUATION_STALE_QUOTE_NOTICE, relativeValuationValues } from "./relative-valuation-model";
+import { paneSchemas } from "./headless-schema";
+
+export const relativeValuationHeadless: HeadlessPaneDefinition<"rows"> = {
+  ...paneSchemas["relative-valuation-pane"],
+  shape: "rows",
+  describe: ({ symbols }) => `Relative Valuation | ${symbols.join(", ")}`,
+  columns: [
+    { key: "symbol", header: "Ticker" },
+    { key: "price", header: "Last", align: "right", format: (value, row) => value == null || !row.currency ? "-" : formatCurrency(Number(value), String(row.currency)) },
+    ...([ ["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>) => formatPriceEarnings((row.reportedMultiples as ReturnType<typeof relativeValuationValues>["reportedMultiples"] | undefined)?.[key]),
+    })),
+    ...[["evSales", "EV/S"]].map(([key, header]) => ({
+      key: key!, header: header!, align: "right" as const,
+      format: (value: unknown) => value == null ? "-" : formatNumber(Number(value), 1),
+    })),
+    ...[["fcfYield", "FCF Yield"], ["revenueGrowth", "Revenue Growth"], ["operatingMargin", "Op Margin"]].map(([key, header]) => ({
+      key: key!, header: header!, align: "right" as const,
+      format: (value: unknown) => value == null ? "-" : formatPercent(Number(value)),
+    })),
+  ],
+  async load({ symbols }, ctx) {
+    const loaded = await loadHeadlessSymbols(symbols, ctx, (symbol) => loadHeadlessFinancials(ctx, symbol));
+    const rows = loaded.entries.map(({ symbol, data }) => ({ symbol, ...relativeValuationValues(data) }));
+    const unavailableSymbols = [...loaded.unavailableSymbols, ...rows.filter((row) => ![
+      row.marketCap, row.trailingPE, row.forwardPE, row.evSales, row.fcfYield, row.revenueGrowth, row.operatingMargin,
+    ].some((value) => value != null)).map(({ symbol }) => symbol)];
+    const staleSymbols = rows.filter((row) => row.quoteStale).map((row) => row.symbol);
+    const staleFundamentalsSymbols = rows.filter((row) => row.fundamentalsProvenance?.stale).map((row) => row.symbol);
+    const errors = [...loaded.errors,
+      ...staleSymbols.map((symbol) => `${symbol}: ${RELATIVE_VALUATION_STALE_QUOTE_NOTICE}`),
+      ...staleFundamentalsSymbols.map((symbol) => `${symbol}: ${RELATIVE_VALUATION_STALE_FUNDAMENTALS_NOTICE}`),
+    ];
+    return { rows, unavailableSymbols, errors, complete: unavailableSymbols.length === 0 && errors.length === 0, metadata: {
+      staleSymbols,
+      staleFundamentalsSymbols,
+      quoteBasis: "Stale quote fields are excluded from comparison; reportedQuote retains the rejected observation and quoteAsOf retains its source timestamp.",
+      fundamentalsBasis: "Provider multiples and operating metrics retain independent fundamentalsProvenance. Retrieval time does not establish the valuation date.",
+      notices: rows.some((row) => Object.values(row.reportedMultiples).some((value) => value != null && value <= 0)) ? [PRICE_EARNINGS_NOTICE] : [],
+      multipleBasis: "Comparable P/E fields require a positive finite multiple; reportedMultiples preserves the finite provider 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.",
+    } };
+
+  },
+};