gloomberb 0.18.4 → 0.19.0

package/src/plugins/builtin/dividend-yield/client.ts

@@ -1,24 +1,82 @@
 import { apiClient } from "../../../api-client";
 import type { DividendSummary } from "../../../api-client/market-discovery";
 import type { ConnectionHealthRegistry } from "../../../core/connection-health";
-import type { DividendMetrics, DividendPayment } from "./types";
+import type { DividendMetrics, DividendPayment, GrowthPayments } from "./types";
 import { resolveCurrencyUnit } from "../../../utils/currency-units";
 import { calendarMonthsBefore } from "../../../utils/calendar-date";
-import { cashDistribution, dividendReferencePrice, dividendYieldAt, inferCadence, trailingCashAt, trailingDividendRate } from "../../../utils/trailing-dividend";
+import { cashDistribution, dividendReferencePrice, dividendYieldAt, inferCadence, trailingCashAt, trailingDividendRate, trailingPaymentShortfall, unevenRegularPayments } from "../../../utils/trailing-dividend";
 import { dividendQuotePriceMetadata } from "./reference-price";
 import { mapQuote } from "../../../sources/gloomberb-cloud/normalizers";
 import { regularSessionValuationPrice } from "../../../market-data/quotes/regular-session-valuation";
 import { declaredDividends } from "../../../utils/declared-dividends";
 import { cashInMajorUnits } from "../../../utils/dividend-cash";
 import { lapsedDividend } from "../../../utils/forward-dividend";
-import type { DeclaredDividendAction } from "../../../types/financials";
+import type { DeclaredCash, DeclaredDividendAction, TickerFinancials } from "../../../types/financials";
+import { logFailure } from "../../../utils/log-failure";
 
 export const DIVIDENDS_CONNECTION_ID = "gloom-dividends";
-export const INCOMPLETE_DIVIDEND_HISTORY = "Incomplete cash history; totals unavailable.";
+
+/** ` (last tried 2026-10-27 15:38 UTC)`, or nothing when the time is not known. */
+function lastTried(at: string | undefined): string {
+  const time = at ? Date.parse(at) : Number.NaN;
+  if (!Number.isFinite(time)) return "";
+  const iso = new Date(time).toISOString();
+  return ` (last tried ${iso.slice(0, 10)} ${iso.slice(11, 16)} UTC)`;
+}
+
+/** A read with some cash rows, but not all of them usable. */
+function incompleteDividendHistory(triedAt?: string): string {
+  return `Incomplete cash history${lastTried(triedAt)}; totals unavailable.`;
+}
+/** A read with no cash rows at all: nothing is incomplete, there is nothing. */
+function unavailableDividendHistory(triedAt?: string): string {
+  return `Cash history unavailable${lastTried(triedAt)}; no payments, totals or growth.`;
+}
+/** A read without its summary; `forward` when another source still gave the forward rate. */
+function unavailableDividendSummary(triedAt?: string, { forward = false } = {}): string {
+  return `Dividend summary unavailable${lastTried(triedAt)}; no ${forward ? "payout ratio or pay date" : "forward rate, payout ratio or pay date"}.`;
+}
+export const INCOMPLETE_DIVIDEND_HISTORY = incompleteDividendHistory();
 export const MISSING_DIVIDEND_CURRENCY = "Dividend currency is unavailable; cash amounts cannot be compared safely.";
-export const UNAVAILABLE_DIVIDEND_SUMMARY = "Dividend summary unavailable.";
+export const UNAVAILABLE_DIVIDEND_SUMMARY = unavailableDividendSummary();
 export const INVALID_DIVIDEND_SUMMARY_DATE = "Invalid dividend summary date.";
 
+/** The forward rate a listing's fundamentals state: the annual rate, in the major unit of `currency`, and the ex-date it annualizes. */
+interface StatedForwardRate {
+  rate: number;
+  exDate: string;
+  currency: string;
+}
+
+/**
+ * The forward rate fundamentals state for a listing (DUK's 4.34, declared,
+ * ex 2026-11-13), in its quote's currency; null when its yield is not a
+ * forward one or the rate, its ex-date or the currency is missing.
+ */
+export function statedForwardRate(financials: Pick<TickerFinancials, "fundamentals" | "quote"> | null | undefined): StatedForwardRate | null {
+  const fundamentals = financials?.fundamentals;
+  const currency = resolveCurrencyUnit(financials?.quote?.currency).currency;
+  const rate = fundamentals?.dividendRate;
+  const exDate = fundamentals?.exDividendDate;
+  if (fundamentals?.dividendYieldBasis !== "forward" || !currency || typeof rate !== "number" || !Number.isFinite(rate) || rate <= 0
+    || !exDate || !/^\d{4}-\d{2}-\d{2}$/.test(exDate)) return null;
+  return { rate, exDate, currency };
+}
+
+/** A summary holding only a stated forward rate, dated by its ex-date, for a read whose own summary is missing. */
+function statedRateSummary(stated: StatedForwardRate): QuoteSummaryDividendFields {
+  return {
+    trailingAnnualDividendRate: null, trailingAnnualDividendYield: null, payoutRatio: null, dividendDate: null,
+    forwardAnnualDividendRate: stated.rate, forwardRateAsOf: stated.exDate,
+    exDividendDate: Date.parse(`${stated.exDate}T00:00:00Z`) / 1000, currency: stated.currency,
+  };
+}
+
+interface DividendReadOptions {
+  /** The forward rate fundamentals state (statedForwardRate), asked only when the summary is missing. */
+  loadStatedForwardRate?: () => Promise<StatedForwardRate | null> | StatedForwardRate | null;
+}
+
 let connectionHealth: ConnectionHealthRegistry | null = null;
 
 export function attachDividendYieldHealth(health?: ConnectionHealthRegistry): void {
@@ -55,6 +113,18 @@ export function toDividendPayment(
   };
 }
 
+/**
+ * The declared amount of each paid row by its ex-date: a company declaring in
+ * another currency than the listing pays. Rows in the listing's own currency,
+ * or with no usable amount, are not a declaration in another currency.
+ */
+function declaredCashByExDate(declared: DeclaredCash | undefined, cashCurrency: string): Map<string, { amount: number; currency: string }> {
+  const unit = resolveCurrencyUnit(declared?.currency);
+  if (!declared || !unit.currency || unit.currency === cashCurrency || !Array.isArray(declared.rows)) return new Map();
+  return new Map(declared.rows.flatMap((row) => typeof row?.exDate === "string" && Number.isFinite(row.amount) && row.amount > 0
+    ? [[row.exDate, { amount: row.amount / unit.divisor, currency: unit.currency }] as const] : []));
+}
+
 export interface DividendData {
   payments: DividendPayment[];
   /** Declared and unpaid, in `currency`; never in `payments` or any figure. Absent from older servers. */
@@ -67,6 +137,8 @@ export interface DividendData {
   historyError?: string;
   /** Independent summary failures do not invalidate usable cash history. */
   summaryError?: string;
+  /** Set when the summary was missing and the forward rate is the one fundamentals state (statedForwardRate). */
+  forwardFromFundamentals?: boolean;
   notes?: string[];
   providerId?: string;
   /** Source fetch time, not the last ex-date or this pane's cache-read time. */
@@ -81,31 +153,41 @@ export async function fetchDividendData(
   currentPrice: number | null,
   exchange = "",
   currentPriceCurrency?: string,
+  options: DividendReadOptions = {},
 ): Promise<DividendData> {
   const response = await trackRequest("dividends", () => apiClient.getMarketDividends(symbol, exchange));
   if (!response.data) throw new Error(`No dividend data found for ${symbol}`);
-  const { actions: sourceActions, quote: rawQuote, summary: quoteFields } = response.data;
+  const { actions: sourceActions, quote: rawQuote, summary, triedAt } = response.data;
   // In the major unit as the history arrives, as every other reader of it gets it.
   const actions = sourceActions ? cashInMajorUnits(sourceActions) : null;
   const quote = rawQuote ? mapQuote(rawQuote) : null;
-  const summaryError = response.data.summaryError ?? (!quoteFields ? UNAVAILABLE_DIVIDEND_SUMMARY
-    : [quoteFields.exDividendDate, quoteFields.dividendDate]
+  const cashCurrency = resolveCurrencyUnit(actions?.currency).currency;
+  // Without a summary, the forward rate fundamentals state stands in, dated by the ex-date it annualizes (DUK's declared one).
+  const stated = !summary && options.loadStatedForwardRate
+    ? await Promise.resolve().then(options.loadStatedForwardRate).catch(logFailure("dividend-yield.client", "Read the stated forward rate failed", null))
+    : null;
+  const statedFields = !summary && stated && (!cashCurrency || stated.currency === cashCurrency) ? statedRateSummary(stated) : null;
+  const quoteFields = summary ?? statedFields;
+  const summaryError = !summary ? unavailableDividendSummary(triedAt, { forward: quoteFields != null })
+    : response.data.summaryError ?? ([summary.exDividendDate, summary.dividendDate]
       .some((timestamp) => timestamp != null && reportedDividendDate(timestamp) === null)
       ? INVALID_DIVIDEND_SUMMARY_DATE : undefined);
-  const cashCurrency = resolveCurrencyUnit(actions?.currency).currency;
   const summaryUnit = resolveCurrencyUnit(quoteFields?.currency);
   const currency = cashCurrency || summaryUnit.currency;
-  let historyError = response.data.historyError;
+  let historyError = !actions && response.data.historyError ? unavailableDividendHistory(triedAt) : response.data.historyError;
   if (actions && !cashCurrency) historyError = MISSING_DIVIDEND_CURRENCY;
   if (!currency && (quoteFields?.trailingAnnualDividendRate != null || quoteFields?.forwardAnnualDividendRate != null)) {
     historyError = MISSING_DIVIDEND_CURRENCY;
   }
+  const declaredCash = cashCurrency ? declaredCashByExDate(actions?.declaredCash, cashCurrency) : new Map();
   const payments = actions && cashCurrency ? actions.dividends.flatMap(action => {
     const payment = toDividendPayment(action.exDate, action.amount, cashCurrency);
-    return payment ? [payment] : [];
+    const declared = declaredCash.get(action.exDate);
+    return payment ? [declared ? { ...payment, declared } : payment] : [];
   }).sort((a, b) => b.exDate.getTime() - a.exDate.getTime()) : [];
   if (!historyError && actions && (actions.coverage?.dividends === "unavailable" || payments.length !== actions.dividends.length)) {
-    historyError = INCOMPLETE_DIVIDEND_HISTORY;
+    // A read with no rows is not an incomplete one.
+    historyError = actions.dividends.length === 0 ? unavailableDividendHistory(triedAt) : incompleteDividendHistory(triedAt);
   }
   const suppliedPrice = dividendReferencePrice(currentPrice, currentPriceCurrency, currency);
   // The regular session's price, as the quote headlines it: after the close, the close rather than an after-hours print.
@@ -124,7 +206,9 @@ export async function fetchDividendData(
     payments, ...(declared.length > 0 ? { declared } : {}), metrics, price, currency: currency || undefined, historyAvailable,
     ...(suppliedPrice == null && price != null && quote ? dividendQuotePriceMetadata(quote) : {}),
     ...(historyError ? { historyError } : {}), ...(summaryError ? { summaryError } : {}),
-    providerId: actions?.providerId ?? "gloom", fetchedAt: actions?.fetchedAt,
+    ...(statedFields && metrics.forwardRate != null ? { forwardFromFundamentals: true } : {}),
+    // A history standing in for a refresh that could not read it is dated by its own read.
+    providerId: actions?.providerId ?? "gloom", fetchedAt: actions?.dividendsAsOf ?? actions?.fetchedAt,
     stale: response.stale === true || response.data.stale === true || actions?.stale === true,
     notes: ["Cash yield excludes taxes and reinvestment. SEC yield, tax components and future payments are not modeled."],
   };
@@ -155,9 +239,6 @@ export function buildDividendMetrics(
   const statedRate = options.summaryRatesComparable !== false ? quoteFields?.forwardAnnualDividendRate ?? null : null;
   const statedAsOf = statedRate != null && /^\d{4}-\d{2}-\d{2}$/.test(quoteFields?.forwardRateAsOf ?? "")
     ? quoteFields!.forwardRateAsOf! : null;
-  const growth1Y = options.historyAvailable !== false ? computeGrowth(eligible, 1, now) : null;
-  const growth3Y = options.historyAvailable !== false ? computeGrowth(eligible, 3, now) : null;
-
   // A reported ex-date can be the latest one or an announced one; keep them apart.
   const reportedExDate = reportedDividendDate(quoteFields?.exDividendDate ?? null);
   const pastExDates = payments.filter((payment) => payment.exDate <= now).map((payment) => payment.exDate.getTime());
@@ -179,8 +260,17 @@ export function buildDividendMetrics(
       exDates: [...payments.map((payment) => payment.exDate), ...lastExDividendDate ? [lastExDividendDate] : []], declared }, now)
     : lapsedDividend([statedAsOf, lastExDividendDate?.toISOString().slice(0, 10)]
       .filter((day): day is string => !!day).sort().at(-1), { exDates: null, declared }, now);
-  const forwardRate = lapse ? null : statedRate;
-  const forwardRateAsOf = lapse ? null : statedAsOf;
+  // A year whose regular payments differ widely (HSBC's final beside its interims) has no one payment to annualize: its total stands.
+  const uneven = statedRate != null && !lapse && options.historyAvailable !== false ? unevenRegularPayments(eligible, now) : null;
+  const forwardRate = lapse ? null : uneven ? uneven.total : statedRate;
+  const forwardRateAsOf = lapse ? null : uneven ? uneven.latest.toISOString().slice(0, 10) : statedAsOf;
+  const growth1Y = options.historyAvailable !== false ? computeGrowth(eligible, 1, now) : null;
+  const growth3Y = options.historyAvailable !== false ? computeGrowth(eligible, 3, now) : null;
+
+  // A payout over zero or negative earnings (ECC's 2000% beside an EPS of -1.30) is not a payout, whatever the source states.
+  const payoutNotMeaningful = typeof quoteFields?.trailingEps === "number" && Number.isFinite(quoteFields.trailingEps) && quoteFields.trailingEps <= 0;
+  // A trailing yield over a hole in a regular payer's history says how many payments it counts; a stopped dividend has said so.
+  const trailingPayments = options.historyAvailable !== false && !lapse ? trailingPaymentShortfall(eligible, now) : null;
 
   return repriceDividendMetrics({
     trailingYield: null,
@@ -188,10 +278,15 @@ export function buildDividendMetrics(
     trailingRate,
     forwardRate,
     forwardRateAsOf,
+    ...(uneven ? { forwardBasis: "uneven" as const } : {}),
     lapse,
-    payoutRatio: quoteFields?.payoutRatio ?? null,
-    growth1Y,
-    growth3Y,
+    payoutRatio: payoutNotMeaningful ? null : quoteFields?.payoutRatio ?? null,
+    payoutNotMeaningful,
+    trailingPayments,
+    growth1Y: growth1Y?.growth ?? null,
+    growth3Y: growth3Y?.growth ?? null,
+    ...(growth1Y?.shortfall ? { growth1YPayments: growth1Y.shortfall } : {}),
+    ...(growth3Y?.shortfall ? { growth3YPayments: growth3Y.shortfall } : {}),
     paymentFrequency: options.historyAvailable !== false ? inferFrequency(eligible, now) : null,
     lastExDividendDate,
     nextExDividendDate,
@@ -207,14 +302,27 @@ export function repriceDividendMetrics(metrics: DividendMetrics, price: number |
   };
 }
 
-function computeGrowth(payments: DividendPayment[], years: number, now: Date): number | null {
+/**
+ * Cash growth between the trailing year and the one `years` before it, only
+ * when each holds every payment the cadence pays: a year with a hole in its
+ * history (AZN's missing August interim) measures the hole, not a cut, so it
+ * has no growth and says how many payments it holds. A year with none is a
+ * suspension, which still reads as a full decline.
+ */
+function computeGrowth(payments: DividendPayment[], years: number, now: Date): { growth: number | null; shortfall?: GrowthPayments } | null {
   const priorEnd = calendarMonthsBefore(now, 12 * years);
   const priorStart = calendarMonthsBefore(priorEnd, 12);
   // A new fund's partial first year is not a full-year growth baseline.
   if (!payments.some((payment) => payment.exDate <= priorStart)) return null;
+  for (const end of [now, priorEnd]) {
+    const short = trailingPaymentShortfall(payments, end);
+    if (short && short.counted > 0) {
+      return { growth: null, shortfall: { ...short, ...end === now ? {} : { yearTo: end.toISOString().slice(0, 10) } } };
+    }
+  }
   const recent = trailingCashAt(payments, now);
   const prior = trailingCashAt(payments, priorEnd);
-  return prior > 0 ? Math.pow(recent / prior, 1 / years) - 1 : null;
+  return { growth: prior > 0 ? Math.pow(recent / prior, 1 / years) - 1 : null };
 }
 
 function inferFrequency(payments: DividendPayment[], now: Date): DividendMetrics["paymentFrequency"] {

package/src/plugins/builtin/dividend-yield/headless.ts

@@ -4,12 +4,12 @@ import type {
   HeadlessPaneDefinition,
   HeadlessPaneLoadArgs,
 } from "../../../types/plugin";
-import { fetchDividendData, type DividendData } from "./client";
+import { fetchDividendData, statedForwardRate, type DividendData } from "./client";
 import { dividendReferencePrice } from "../../../utils/trailing-dividend";
-import type { DividendPayment } from "./types";
-import { formatDividendYield, toDividendRows } from "./view";
+import type { DividendPayment, GrowthPayments } from "./types";
+import { formatDividendYield, growthPaymentsText, PAYOUT_NOT_MEANINGFUL, staleHistoryText, toDividendRows, trailingPaymentsText } from "./view";
 import { formatDistributionAmount, formatPercent } from "../../../utils/format";
-import { forwardDividendBasis, noCurrentDividend, TRAILING_DIVIDEND_BASIS } from "../../../utils/forward-dividend";
+import { forwardDividendBasis, noCurrentDividend, TRAILING_DIVIDEND_BASIS, UNEVEN_REGULAR_PAYMENTS } from "../../../utils/forward-dividend";
 import { currencyPriceMinDigits, formatMarketPriceWithCurrency } from "../../../market-data/market/format";
 import type { Quote } from "../../../types/financials";
 import { regularSessionValuationPrice } from "../../../market-data/quotes/regular-session-valuation";
@@ -43,6 +43,11 @@ const PAYMENT_COLUMNS = [
   { key: "type", header: "Type" },
 ];
 
+/** After the amount, for a company declaring in another currency than the listing pays: what it declared. */
+const DECLARED_COLUMN = { key: "declared", header: "Declared", align: "right" as const,
+  format: (value: unknown, row: Record<string, unknown>) => typeof value === "number" && typeof row.declaredCurrency === "string"
+    ? formatDistributionAmount(value, row.declaredCurrency) : "-" };
+
 export interface DividendYieldHeadlessDependencies {
   loadData(symbol: string, context: HeadlessPaneContext): Promise<DividendData>;
   /** A US-listed fund's bond facts (SEC yield, yield to worst, duration); null for any other listing. */
@@ -59,10 +64,12 @@ const defaultDependencies: DividendYieldHeadlessDependencies = {
     let currentPrice: number | null = null;
     let currentPriceCurrency: string | undefined;
     let referenceQuote: Quote | undefined;
+    // `ULVR:LSE` is ULVR on LSE, as quote and events read it: the history is asked for that listing, not for a symbol `ULVR:LSE`.
     const instrument = await context.resolveInstrument?.(symbol);
+    const listingSymbol = instrument?.symbol ?? symbol;
     const exchange = instrument?.exchange ?? "";
     try {
-      const quote = await context.marketData.getQuote(symbol, exchange);
+      const quote = await context.marketData.getQuote(listingSymbol, exchange);
       // The regular session's price: after the close, the close rather than an after-hours print.
       currentPrice = regularSessionValuationPrice(quote);
       currentPriceCurrency = quote.currency;
@@ -71,7 +78,10 @@ const defaultDependencies: DividendYieldHeadlessDependencies = {
       logFailure("dividend-yield.headless", "Read dividend reference quote failed")(error);
       currentPrice = null;
     }
-    const data = await fetchDividendData(symbol, currentPrice, exchange, currentPriceCurrency);
+    const data = await fetchDividendData(listingSymbol, currentPrice, exchange, currentPriceCurrency, {
+      // Read only when the summary is missing: the forward rate fundamentals state, as `fundamentals` shows it.
+      loadStatedForwardRate: async () => statedForwardRate(await context.marketData.getTickerFinancials(listingSymbol, exchange)),
+    });
     if (referenceQuote && dividendReferencePrice(currentPrice, currentPriceCurrency, data.currency ?? "") != null) {
       Object.assign(data, dividendQuotePriceMetadata(referenceQuote));
     }
@@ -80,7 +90,7 @@ const defaultDependencies: DividendYieldHeadlessDependencies = {
   async loadBond(symbol, context) {
     const instrument = await context.resolveInstrument?.(symbol);
     const exchange = instrument?.exchange ?? "";
-    const quote = await context.marketData.getQuote(symbol, exchange)
+    const quote = await context.marketData.getQuote(instrument?.symbol ?? symbol, exchange)
       .catch((error) => {
         logFailure("dividend-yield.headless", "Read bond fund classification quote failed")(error);
         throw new BondClassificationError("Bond fund quote check failed");
@@ -92,6 +102,11 @@ const defaultDependencies: DividendYieldHeadlessDependencies = {
   loadTreasury: (context) => loadTreasuryTenors(context.apiClient),
 };
 
+/** A growth figure, or what its short year holds: "n/a: 1 of 2 payments". */
+function growthText(growth: number | null, payments: GrowthPayments | null | undefined): string {
+  return growth == null && payments ? growthPaymentsText(payments) : formatPercent(growth ?? undefined);
+}
+
 function dateEntry(label: string, date: Date | null) {
   return { label, value: date, formatted: date ? date.toISOString().slice(0, 10) : "—" };
 }
@@ -129,11 +144,16 @@ export function projectDividendYieldHeadless(
       paymentDate: payment?.paymentDate?.toISOString() ?? null,
       declarationDate: payment?.declarationDate?.toISOString() ?? null,
       type: payment?.type ?? null,
+      ...(row.declared ? { declared: row.declared.amount, declaredCurrency: row.declared.currency } : {}),
     };
   });
+  const declaredColumns = rows.some((row) => row.declared)
+    ? [...PAYMENT_COLUMNS.slice(0, 2), DECLARED_COLUMN, ...PAYMENT_COLUMNS.slice(2)] : PAYMENT_COLUMNS;
   const metrics = data.metrics;
   const currency = data.currency ?? data.payments[0]?.currency ?? "";
   const priceStatus = dividendPriceStatus(data.price, data.priceAsOf, data.priceStale);
+  // A regular payer's year with fewer payments than its cadence pays: the yield says how many it counts.
+  const shortfall = trailingPaymentsText(metrics.trailingPayments, { cadence: true });
   const errors = [data.historyError, data.summaryError, tax?.checkError].filter((error): error is string => !!error);
 
   return {
@@ -143,18 +163,18 @@ export function projectDividendYieldHeadless(
         title: "Dividend metrics",
         entries: [
           { label: "Price", value: data.price, ...(data.price != null && currency ? { formatted: formatMarketPriceWithCurrency(data.price, currency, { minimumFractionDigits: currencyPriceMinDigits(currency) }) } : {}) },
-          ...(data.stale ? [{ label: "History status", value: "Stale cash history; recent distributions may be missing." }] : []),
+          ...(data.stale ? [{ label: "History status", value: staleHistoryText(data.fetchedAt) }] : []),
           ...(priceStatus ? [{ label: "Price status", value: priceStatus === "stale"
             ? "Stale reference price; cash yield may be out of date."
             : "Reference price time unavailable; cash yield may be out of date." }] : []),
           { label: bond ? `Trailing distribution yield (${NOT_SEC_YIELD})` : "Trailing yield", value: roundedRatio(metrics.trailingYield),
             formatted: metrics.trailingYield == null ? formatDividendYield(null)
-            : `${formatDividendYield(metrics.trailingYield)} (${TRAILING_DIVIDEND_BASIS})` },
+            : `${formatDividendYield(metrics.trailingYield)} (${TRAILING_DIVIDEND_BASIS}${shortfall ? `; counts ${shortfall}` : ""})` },
           { label: bond ? `Forward distribution yield (${NOT_SEC_YIELD})` : "Forward yield", value: roundedRatio(metrics.forwardYield),
             formatted: metrics.lapse ? noCurrentDividend(metrics.lapse)
             : metrics.forwardYield == null ? formatDividendYield(null)
-            : `${formatDividendYield(metrics.forwardYield)} (${forwardDividendBasis(metrics.forwardRateAsOf,
-              { payDate: forwardPayDate(metrics), declared: data.declared, currency })})` },
+            : `${formatDividendYield(metrics.forwardYield)} (${metrics.forwardBasis === "uneven" ? UNEVEN_REGULAR_PAYMENTS
+              : forwardDividendBasis(metrics.forwardRateAsOf, { payDate: forwardPayDate(metrics), declared: data.declared, currency })})` },
           ...(bond ? bondFigures(bond).map((figure) => ({
             label: figure.key === "secYield" ? "30-day SEC yield" : figure.label,
             value: figure.value,
@@ -162,9 +182,9 @@ export function projectDividendYieldHeadless(
           })) : []),
           { label: "Trailing rate", value: metrics.trailingRate, formatted: currency ? formatDistributionAmount(metrics.trailingRate ?? undefined, currency) : "—" },
           { label: "Forward rate", value: metrics.forwardRate, formatted: currency ? formatDistributionAmount(metrics.forwardRate ?? undefined, currency) : "—" },
-          { label: "Earnings Payout", value: roundedRatio(metrics.payoutRatio), formatted: formatDividendYield(metrics.payoutRatio) },
-          { label: "1Y Cash Growth", value: roundedRatio(metrics.growth1Y), formatted: formatPercent(metrics.growth1Y ?? undefined) },
-          { label: "3Y Cash CAGR", value: roundedRatio(metrics.growth3Y), formatted: formatPercent(metrics.growth3Y ?? undefined) },
+          { label: "Earnings Payout", value: roundedRatio(metrics.payoutRatio), formatted: metrics.payoutNotMeaningful ? PAYOUT_NOT_MEANINGFUL : formatDividendYield(metrics.payoutRatio) },
+          { label: "1Y Cash Growth", value: roundedRatio(metrics.growth1Y), formatted: growthText(metrics.growth1Y, metrics.growth1YPayments) },
+          { label: "3Y Cash CAGR", value: roundedRatio(metrics.growth3Y), formatted: growthText(metrics.growth3Y, metrics.growth3YPayments) },
           { label: "Frequency", value: metrics.paymentFrequency },
           dateEntry("Last ex-dividend", metrics.lastExDividendDate),
           dateEntry("Next ex-dividend", metrics.nextExDividendDate),
@@ -179,7 +199,7 @@ export function projectDividendYieldHeadless(
       }] : []),
       {
         title: "Dividend history",
-        columns: PAYMENT_COLUMNS,
+        columns: declaredColumns,
         rows,
         // Each amount is in its own row's currency.
         rowUnitKey: "currency",
@@ -201,10 +221,18 @@ export function projectDividendYieldHeadless(
       priceStale: data.priceStale ?? null,
       limitations: data.notes ?? [],
       yieldMethod: "Cash distributions with ex-dates in the preceding 12 months, one payment per period for a regular cadence, divided by the reference share price; excludes reinvestment and is not SEC yield or total return.",
+      // Set when a regular payer's year holds fewer payments than its cadence pays (a gap in its history): the yield counts only these.
+      trailingPayments: metrics.trailingPayments ?? null,
+      // Set when a year a growth figure compares holds fewer payments than the cadence pays: that figure is null.
+      growth1YPayments: metrics.growth1YPayments ?? null,
+      growth3YPayments: metrics.growth3YPayments ?? null,
       forwardRateAsOf: metrics.forwardRateAsOf,
+      // "uneven": the year's regular payments differ too widely for one to be annualized, so the forward rate is their total.
+      forwardBasis: metrics.forwardBasis ?? null,
       // Declared and unpaid, apart from the paid history the table and every figure read.
       declaredDividends: data.declared ?? [],
-      forwardRateMethod: "Indicated annual cash rate, the one fundamentals use: the latest regular distribution annualized, or once the next one is declared that one, dated by its ex-date (forwardRateAsOf; a date still ahead is the declared distribution's). Only when its currency units are comparable with the share price.",
+      forwardRateMethod: "Indicated annual cash rate, the one fundamentals use: the latest regular distribution annualized, or once the next one is declared that one, dated by its ex-date (forwardRateAsOf; a date still ahead is the declared distribution's). When the trailing year's regular payments differ widely (the largest over 1.5 times the smallest; forwardBasis: uneven), their total instead, dated by the latest. Only when its currency units are comparable with the share price.",
+      payoutMethod: "Trailing twelve-month dividends over trailing twelve-month diluted EPS, as the source states it; N/M (not meaningful) when that EPS is zero or negative.",
       paymentFrequencyMethod: "Cadence inferred from ex-dates in the last two years, unavailable when no cash was reported in the last year; not an announced payment schedule.",
       // A bond fund's sponsor figures, each dated; its distribution yields above are not its SEC yield.
       ...(bond ? { bondFund: { ...bond, class: bondClassText(bond) } } : {}),

package/src/plugins/builtin/dividend-yield/model.ts

@@ -2,7 +2,7 @@ import type { DataTableColumn } from "../../../components";
 import { compareSortValues, type SortDirection } from "../../../utils/sort-values";
 import type { DividendRow } from "./view";
 
-export type DividendColumnId = "exDate" | "amount" | "currency";
+export type DividendColumnId = "exDate" | "amount" | "declared" | "currency";
 export type DividendColumn = DataTableColumn & { id: DividendColumnId };
 
 export interface DividendSortPreference {
@@ -16,15 +16,17 @@ export const DEFAULT_SORT_PREFERENCE: DividendSortPreference = {
 };
 
 /**
- * The amount sits beside its ex-date rather than across the pane. The currency
- * column shows only when the payments mix currencies; otherwise the amount's
- * own symbol says it.
+ * The amount sits beside its ex-date rather than across the pane. The declared
+ * amount follows it only for a company declaring in another currency than the
+ * listing pays (BP's dollars beside its pence). The currency column shows only
+ * when the payments mix currencies; otherwise the amount's own symbol says it.
  */
-export function buildDividendColumns(rows: readonly Pick<DividendRow, "currency">[] = []): DividendColumn[] {
+export function buildDividendColumns(rows: readonly Pick<DividendRow, "currency" | "declared">[] = []): DividendColumn[] {
   const mixed = new Set(rows.map((row) => row.currency)).size > 1;
   return [
     { id: "exDate", label: "EX-DATE", width: 10, align: "left" },
     { id: "amount", label: "AMOUNT", width: 12, align: "right" },
+    ...(rows.some((row) => row.declared) ? [{ id: "declared" as const, label: "DECLARED", width: 10, align: "right" as const }] : []),
     ...(mixed ? [{ id: "currency" as const, label: "CCY", width: 6, align: "left" as const }] : []),
   ];
 }
@@ -33,6 +35,7 @@ function getSortValue(columnId: DividendColumnId, row: DividendRow): string | nu
   switch (columnId) {
     case "exDate": return row.exDate;
     case "amount": return row.amount;
+    case "declared": return row.declared?.amount ?? null;
     case "currency": return row.currency;
   }
 }

package/src/plugins/builtin/dividend-yield/pane.tsx

@@ -22,15 +22,16 @@ import { colors, priceColor } from "../../../theme/colors";
 import { TextAttributes, useUiCapabilities } from "../../../ui";
 import { displayWidth, formatCurrency, formatDistributionAmount, formatPercentRaw } from "../../../utils/format";
 import { resolveCurrencyUnit } from "../../../utils/currency-units";
-import { forwardDividendNote, lastPaidNote, NO_CURRENT_DIVIDEND } from "../../../utils/forward-dividend";
+import { parsePublicTickerKey } from "../../../utils/exchanges";
+import { forwardDividendNote, lastPaidNote, NO_CURRENT_DIVIDEND, UNEVEN_REGULAR_PAYMENTS } from "../../../utils/forward-dividend";
 import { nextHeaderSort } from "../../../utils/sort-values";
 import { handleRefreshKey, loadingErrorFooterInfo } from "../../../components/data-table/table-pane";
 import { SignInWall } from "../cloud/auth-actions";
 import { isCloudSessionRequired, useResearchCloudSession } from "../shared/research-cloud-session";
-import { fetchDividendData, repriceDividendMetrics, type DividendData } from "./client";
+import { fetchDividendData, repriceDividendMetrics, statedForwardRate, type DividendData } from "./client";
 import { dividendReferencePrice } from "../../../utils/trailing-dividend";
 import { useTickerQuoteStream } from "../../../state/hooks/live-ticker-financials";
-import { buildTrailingCashChartPoints, formatDividendYield, toDividendRows, type DividendRow } from "./view";
+import { buildTrailingCashChartPoints, formatDividendYield, growthPaymentsDetail, PAYOUT_NOT_MEANINGFUL, staleHistoryText, toDividendRows, trailingPaymentsText, type DividendRow } from "./view";
 import {
   DEFAULT_SORT_PREFERENCE,
   buildDividendColumns,
@@ -39,7 +40,7 @@ import {
   type DividendColumnId,
   type DividendSortPreference,
 } from "./model";
-import type { DividendMetrics } from "./types";
+import type { DividendMetrics, GrowthPayments } from "./types";
 import { dividendPriceStatus, dividendPriceTime, dividendQuotePriceMetadata } from "./reference-price";
 import type { FundBondFacts } from "../../../api-client/fund-facts";
 import { resolveTickerInstrumentKind } from "../../../tickers/instrument-kind";
@@ -57,6 +58,14 @@ function formatGrowth(value: number | null): string {
   return formatPercentRaw(value * 100);
 }
 
+/** A growth figure, or "n/a" with how many payments its short year holds. */
+function growthItem(id: string, label: string, growth: number | null, payments: GrowthPayments | null | undefined): StatItem {
+  if (growth == null && payments) {
+    return { id, label, value: "n/a", detail: growthPaymentsDetail(payments) };
+  }
+  return { id, label, value: formatGrowth(growth), color: priceColor(growth ?? 0) };
+}
+
 function formatDate(date: Date | null): string {
   if (!date) return "—";
   return date.toISOString().slice(0, 10);
@@ -86,11 +95,13 @@ function buildMetricItems(metrics: DividendMetrics, currency: string, hasHistory
     ? [{ id: "next-ex", label: "Next ex", value: formatDate(metrics.nextExDividendDate) }]
     : hasHistory ? [] : [{ id: "last-ex", label: "Last ex", value: formatDate(metrics.lastExDividendDate) }];
   const dated = metrics.lapse ? lastPaidNote(metrics.lapse)
-    : metrics.forwardYield != null ? forwardDividendNote(metrics.forwardRateAsOf, { declared, currency }) : null;
+    : metrics.forwardYield == null ? null
+    : metrics.forwardBasis === "uneven" ? UNEVEN_REGULAR_PAYMENTS : forwardDividendNote(metrics.forwardRateAsOf, { declared, currency });
   // "not SEC" in the grid: the SEC yield is the next cell, and the long form costs the header a column.
   const notSec = (note: string | null) => bond ? [note, "not SEC"].filter(Boolean).join(", ") : note;
   const forwardNote = notSec(dated);
-  const trailingNote = notSec(null);
+  // A regular payer's year with fewer payments than its cadence pays says how many the yield counts.
+  const trailingNote = notSec(trailingPaymentsText(metrics.trailingPayments));
   const ttmLabel = bond ? (short ? "TTM dist" : "TTM dist yld") : short ? "TTM yld" : "TTM yield";
   const fwdLabel = bond ? (short ? "Fwd dist" : "Fwd dist yld") : short ? "Fwd yld" : "Fwd yield";
   const sec = bond ? bondFigures(bond).find((figure) => figure.key === "secYield") : undefined;
@@ -107,9 +118,9 @@ function buildMetricItems(metrics: DividendMetrics, currency: string, hasHistory
     ...(sec ? [{ id: "sec-yield", label: short ? "SEC yld" : "SEC yield", value: sec.text, ...(sec.date ? { detail: `as of ${sec.date}` } : {}) }] : []),
     { id: "ttm-rate", label: short ? "TTM/sh" : "TTM/share", value: formatRate(metrics.trailingRate, currency) },
     { id: "forward-rate", label: short ? "Fwd/sh" : "Fwd/share", value: formatRate(metrics.forwardRate, currency) },
-    { id: "growth-1y", label: short ? "1Y chg" : "1Y growth", value: formatGrowth(metrics.growth1Y), color: priceColor(metrics.growth1Y ?? 0) },
-    { id: "cagr-3y", label: "3Y CAGR", value: formatGrowth(metrics.growth3Y), color: priceColor(metrics.growth3Y ?? 0) },
-    { id: "payout", label: "Payout", value: metrics.payoutRatio != null ? `${(metrics.payoutRatio * 100).toFixed(1)}%` : "—" },
+    growthItem("growth-1y", short ? "1Y chg" : "1Y growth", metrics.growth1Y, metrics.growth1YPayments),
+    growthItem("cagr-3y", "3Y CAGR", metrics.growth3Y, metrics.growth3YPayments),
+    { id: "payout", label: "Payout", value: metrics.payoutNotMeaningful ? PAYOUT_NOT_MEANINGFUL : metrics.payoutRatio != null ? `${(metrics.payoutRatio * 100).toFixed(1)}%` : "—" },
     { id: "cadence", label: "Cadence", value: formatFrequency(metrics.paymentFrequency) },
     ...exDate,
     { id: "next-pay", label: "Next pay", value: formatDate(metrics.nextPayDate) },
@@ -143,6 +154,8 @@ function renderCell(
         color: colors.textBright,
         attributes: TextAttributes.BOLD,
       };
+    case "declared":
+      return { text: row.declared ? formatDistributionAmount(row.declared.amount, row.declared.currency) : "", color: colors.textDim };
     case "currency":
       return { text: row.currency, color: colors.textDim };
   }
@@ -162,7 +175,11 @@ export function DividendYieldPane({ focused, width, height, loadData = fetchDivi
   const fundSymbol = ticker && resolveTickerInstrumentKind(ticker, financials) === "fund" && mayBeUsEquityOrFundTicker(ticker) ? ticker.metadata.ticker : null;
   const bond = useFundFacts(fundSymbol).data?.payload?.bond ?? null;
   const quoteCurrency = financials?.quote?.currency;
-  const exchange = ticker?.metadata.exchange ?? "";
+  // The listing's own symbol beside its venue: a `ULVR:LSE` key is ULVR on LSE, never a symbol of that name.
+  const listingKey = ticker?.metadata.ticker ?? symbol;
+  const parsedListing = listingKey ? parsePublicTickerKey(listingKey) : null;
+  const listingSymbol = parsedListing?.symbol ?? null;
+  const exchange = parsedListing?.exchange ?? ticker?.metadata.exchange ?? "";
   // The regular session's price: after the close, the close rather than an after-hours print.
   const quotePrice = regularSessionValuationPrice(financials?.quote);
 
@@ -173,9 +190,17 @@ export function DividendYieldPane({ focused, width, height, loadData = fetchDivi
   // quote is read through a ref instead of being an effect dependency.
   const quoteRef = useRef({ price: quotePrice, currency: quoteCurrency });
   quoteRef.current = { price: quotePrice, currency: quoteCurrency };
+  // The forward rate the ticker's fundamentals state, read only when the summary is missing. Fundamentals can
+  // arrive after the read, so a new stated rate reads again; a price tick does not.
+  const stated = statedForwardRate(financials);
+  const statedKey = stated ? `${stated.rate}|${stated.exDate}|${stated.currency}` : "";
+  const statedRef = useRef(stated);
+  statedRef.current = stated;
 
-  const request = useCallback(() => loadData(symbol!, quoteRef.current.price, exchange, quoteRef.current.currency), [exchange, loadData, symbol, cloudSession.requestKey]);
-  const { data, loading, error, updatedAt, reload: refresh } = useAsyncResource(symbol ? request : null);
+  const request = useCallback(() => loadData(listingSymbol!, quoteRef.current.price, exchange, quoteRef.current.currency, {
+    loadStatedForwardRate: () => statedRef.current,
+  }), [exchange, loadData, listingSymbol, cloudSession.requestKey, statedKey]);
+  const { data, loading, error, updatedAt, reload: refresh } = useAsyncResource(listingSymbol ? request : null);
   // An integrity response may contain no usable rows. Retain only historical
   // rows from this resource; its new unavailable metrics remain authoritative.
   const lastHistory = useRef<{ request: typeof request; data: DividendData } | null>(null);
@@ -211,7 +236,7 @@ export function DividendYieldPane({ focused, width, height, loadData = fetchDivi
   }, [authWall, currentPrice, historyData?.fetchedAt, data?.historyError, data?.summaryError, error, loading, priceAsOf, priceStatus, width]);
 
   const sourceWarnings = [
-    ...(data?.stale ? ["Stale cash history; recent distributions may be missing."] : []),
+    ...(data?.stale ? [staleHistoryText(data.fetchedAt)] : []),
   ];
   usePaneNoticeFooter({
     registrationId: "dividend-yield-notices",