gloomberb 0.17.5 → 0.18.0

package/src/market-data/market/freshness.ts

@@ -358,6 +358,33 @@ export function latestRegularSessionClose(
   return null;
 }
 
+/**
+ * When the venue's regular session on `date` (its local `YYYY-MM-DD`) closed,
+ * a published early close included. Null when the venue had no session that
+ * day or its hours are unknown.
+ */
+export function regularSessionCloseOn(exchange: string | undefined, date: string): number | null {
+  const timeZone = sessionCalendarTimeZone(exchange);
+  if (!timeZone || isoLocalDateToUtcDay(date) == null) return null;
+  const endOfDay = zonedWallClockToUtcMs(timeZone, Number(date.slice(0, 4)), Number(date.slice(5, 7)), Number(date.slice(8, 10)), 23, 59, 59);
+  const close = latestRegularSessionClose(exchange, endOfDay);
+  return close?.date === date ? close.close : null;
+}
+
+/** The US pre-market opens at 04:00 New York. */
+const US_PRE_MARKET_OPEN_MINUTES = 4 * 60;
+
+/**
+ * When a US listing's pre-market opened on `date` (its New York
+ * `YYYY-MM-DD`): 04:00 there. Null for any other venue, whose pre-market
+ * hours are not known, and for a date that does not parse.
+ */
+export function preMarketOpenOn(exchange: string | undefined, date: string): number | null {
+  if (!isUsListingExchange(canonicalExchange(exchange)) || isoLocalDateToUtcDay(date) == null) return null;
+  return zonedWallClockToUtcMs("America/New_York", Number(date.slice(0, 4)), Number(date.slice(5, 7)), Number(date.slice(8, 10)),
+    Math.floor(US_PRE_MARKET_OPEN_MINUTES / 60), US_PRE_MARKET_OPEN_MINUTES % 60, 0);
+}
+
 /**
  * The UTC minute of the day the venue's regular session closed, for the latest
  * session at or before `time` (20:00 UTC is 1200 while New York is on daylight
@@ -518,7 +545,7 @@ function formatUsSessionState(timestampMs: number): UsSessionState {
   const minute = Number(parts.find((part) => part.type === "minute")?.value ?? "0");
   const totalMinutes = hour * 60 + minute;
 
-  if (totalMinutes < 4 * 60) return "PREPRE";
+  if (totalMinutes < US_PRE_MARKET_OPEN_MINUTES) return "PREPRE";
   if (totalMinutes < 9 * 60 + 30) return "PRE";
   if (totalMinutes < 16 * 60) return "REGULAR";
   if (totalMinutes < 20 * 60) return "POST";
@@ -633,9 +660,7 @@ export function isTimestampStaleForExchangeSession(
 ): boolean {
   try {
     return isTimestampStaleForExchangeSessionUnsafe(timestampMs, exchange, now, marketState, weekendDays);
-  } catch {
-    return true;
-  }
+  } catch { /* Intentional ignore: Invalid session dates are conservatively stale, never fresh. */ return true; }
 }
 
 function isTimestampStaleForExchangeSessionUnsafe(

package/src/market-data/market/index-level.ts

@@ -0,0 +1,51 @@
+import { classifyInstrumentType, isCryptoVenuePerpetual } from "../../tickers/instrument-kind";
+
+/**
+ * The unit an index level is in, as a chart's axis and series name it. A
+ * generic future on an index reads in the same points.
+ */
+export const INDEX_POINTS_UNIT = "points";
+
+/** How a report line names that unit: `history` heads an index's bars with it, `ticker` its quote. */
+export const INDEX_POINTS_LABEL = "Index points";
+
+/** How an export names it, in `currency_or_unit` and a `unit` field. */
+export const INDEX_POINTS_EXPORT_UNIT = "index points";
+
+/**
+ * An index level is points, not money: ^GSPC at 7,805.45 or ^VIX at 19.99 has
+ * no currency to name, wherever it is shown, though its quote names the
+ * currency its members trade in.
+ */
+export function isIndexLevel(instrumentType: string | null | undefined): boolean {
+  return classifyInstrumentType(instrumentType) === "index";
+}
+
+/** The currency a quote's price is in: none for an index level, nor for a quote that names none. */
+export function quotePriceCurrency(quote: { currency?: string | null; instrumentType?: string | null } | null | undefined): string | null {
+  if (!quote || isIndexLevel(quote.instrumentType)) return null;
+  return quote.currency?.trim() || null;
+}
+
+/**
+ * What a price chart of the instrument reads in: points for an index level,
+ * otherwise its currency, so an axis never puts a dollar sign on ^VIX.
+ */
+export function priceSeriesUnit(currency: string, instrumentType: string | null | undefined): string {
+  return isIndexLevel(instrumentType) ? INDEX_POINTS_UNIT : currency;
+}
+
+/**
+ * A quote's volume where it counts one. An index and a crypto venue's
+ * perpetual price carry 0 for a volume nobody counts, which is not a session
+ * without trades: null for those, as for a quote with no volume. A broad
+ * index whose source sums its members' volume (^GSPC) keeps it.
+ */
+export function reportedQuoteVolume(
+  quote: { volume?: number | null; instrumentType?: string | null; name?: string | null } | null | undefined,
+): number | null {
+  const volume = quote?.volume;
+  if (volume == null || !Number.isFinite(volume)) return null;
+  if (volume === 0 && (isIndexLevel(quote!.instrumentType) || isCryptoVenuePerpetual(quote!.instrumentType, quote!.name))) return null;
+  return volume;
+}

package/src/market-data/market/status.ts

@@ -3,6 +3,8 @@ import { blendHex, colors, priceColor, type ThemeColors } from "../../theme/colo
 import { isFiniteNumber } from "../../utils/guards";
 import { canonicalExchange, isKnownExchangeCode } from "../../utils/exchanges";
 import { quoteTradingDay } from "../quotes/day-range";
+import { isQuoteBeforeLatestSession } from "../quotes/freshness";
+import { preMarketOpenOn, regularSessionCloseOn } from "./freshness";
 
 const CLOSED_CHANGE_MUTING_RATIO = 0.55;
 const US_SESSION_TIME = new Intl.DateTimeFormat("en-US", {
@@ -60,6 +62,28 @@ export function marketStateLabel(state: MarketState): string {
   }
 }
 
+/** What a quote's session reads as once its last print is older than its venue's latest completed session. */
+const STALE_SESSION_LABEL = "STALE";
+
+const WEEKDAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"] as const;
+
+/** `Thu close`: the weekday of the session whose close a quote still stands at. */
+function closeLabel(date: string): string {
+  return `${WEEKDAYS[new Date(`${date}T00:00:00Z`).getUTCDay()]} close`;
+}
+
+/**
+ * A quote's market state as a status cell names it (marketStateLabel), STALE
+ * for a print older than its venue's latest session, and the close it stands
+ * at (`Thu close`) in a pre-market nothing has traded in yet.
+ */
+export function quoteMarketStateLabel(quote: Quote | null | undefined, now = Date.now()): string | null {
+  if (!quote?.marketState) return null;
+  if (isQuoteBeforeLatestSession(quote, now)) return STALE_SESSION_LABEL;
+  const awaiting = preMarketCloseAwaitingPrint(quote);
+  return awaiting ? closeLabel(awaiting.date) : marketStateLabel(quote.marketState);
+}
+
 /** An extended session's column, named as marketStateLabel names its state. */
 export function extendedSessionStateLabel(session: ExtendedSession): string {
   return session === "OVERNIGHT" ? "OVERNIGHT" : marketStateLabel(session);
@@ -136,19 +160,53 @@ function overnightSessionDisplay(quote: Quote): ExtendedSessionDisplay | null {
 }
 
 /**
- * A quote's session as a status cell names it: the overnight session while
- * the quote is priced by it, else its market state (marketStateLabel). The
- * exchange stays closed overnight, so the state alone reads CLOSED.
+ * A quote's session as a status cell names it: STALE when its last print is
+ * older than its venue's latest completed session (isQuoteBeforeLatestSession),
+ * the overnight session while the quote is priced by it, the close it stands
+ * at (`Thu close`) in a pre-market nothing has traded in yet, else its market
+ * state (marketStateLabel). The exchange stays closed overnight, so the state
+ * alone reads CLOSED.
  */
-export function quoteSessionLabel(quote: Quote | null | undefined): string | null {
+export function quoteSessionLabel(quote: Quote | null | undefined, now = Date.now()): string | null {
+  return sessionLabel(quote, now, true);
+}
+
+/**
+ * quoteSessionLabel as an export keeps it, one of a fixed set: the market
+ * state (`PRE-MKT`) in a pre-market nothing has traded in yet, where the
+ * status cell names the close (`Thu close`).
+ */
+export function quoteSessionStateLabel(quote: Quote | null | undefined, now = Date.now()): string | null {
+  return sessionLabel(quote, now, false);
+}
+
+function sessionLabel(quote: Quote | null | undefined, now: number, standingClose: boolean): string | null {
   if (!quote?.marketState) return null;
-  return overnightSessionDisplay(quote) ? "OVERNIGHT" : marketStateLabel(quote.marketState);
+  if (isQuoteBeforeLatestSession(quote, now)) return STALE_SESSION_LABEL;
+  if (overnightSessionDisplay(quote)) return "OVERNIGHT";
+  const awaiting = standingClose ? preMarketCloseAwaitingPrint(quote) : null;
+  return awaiting ? closeLabel(awaiting.date) : marketStateLabel(quote.marketState);
 }
 
-/** The color of quoteSessionLabel: an extended session's while the overnight session prices the quote. */
-export function quoteSessionColor(quote: Quote | null | undefined, palette: ThemeColors = colors): string {
+/**
+ * The color of quoteSessionLabel: STALE in the warning color every stale
+ * mark uses, an extended session's while the overnight session prices the
+ * quote, a closed session's for the close a pre-market still stands at.
+ */
+export function quoteSessionColor(quote: Quote | null | undefined, palette: ThemeColors = colors, now = Date.now()): string {
   if (!quote?.marketState) return palette.textDim;
-  return overnightSessionDisplay(quote) ? marketStateColor("POST", palette) : marketStateColor(quote.marketState, palette);
+  if (isQuoteBeforeLatestSession(quote, now)) return palette.warning;
+  if (overnightSessionDisplay(quote)) return marketStateColor("POST", palette);
+  return marketStateColor(preMarketCloseAwaitingPrint(quote) ? "CLOSED" : quote.marketState, palette);
+}
+
+/**
+ * The market state a session dot pictures for a quote: none for one whose
+ * last print is older than its venue's latest session, so it draws as a quote
+ * with no known session rather than an open market.
+ */
+export function quoteDotMarketState(quote: Quote | null | undefined, now = Date.now()): MarketState | undefined {
+  return quote && !isQuoteBeforeLatestSession(quote, now) ? quote.marketState : undefined;
 }
 
 /** Closed prices are final snapshots, so they should not look live or directional. */
@@ -181,7 +239,8 @@ export function exchangeShortName(exchangeName?: string, fullExchangeName?: stri
  */
 export function getActiveQuoteDisplay(quote: Quote | null | undefined): ActiveQuoteDisplay | null {
   if (!quote) return null;
-  if ((quote.marketState === "PRE" || quote.marketState === "PREPRE") && quote.preMarketPrice != null) {
+  // A pre-market price of 0 is no print.
+  if ((quote.marketState === "PRE" || quote.marketState === "PREPRE") && isPositive(quote.preMarketPrice)) {
     return { price: quote.preMarketPrice, change: quote.preMarketChange, changePercent: quote.preMarketChangePercent };
   }
   const extendedPrice = (quote.marketState === "POST" || quote.marketState === "POSTPOST") ? quote.postMarketPrice : undefined;
@@ -205,6 +264,8 @@ interface CompletedRegularSession {
   close: number;
   /** The close's move from the session before it, when the quote reports it with the close. */
   reported: { change: number; changePercent: number } | null;
+  /** The session's exchange-local date when the quote reports it with the close; otherwise the quote's own day. */
+  date?: string;
 }
 
 function reportedRegularMove(quote: Quote, close: number): CompletedRegularSession["reported"] {
@@ -236,9 +297,11 @@ function completedRegularSession(quote: Quote): CompletedRegularSession | null {
     if (state === "PRE") {
       // The quote's own day is today; the close must be an earlier one, with its move.
       const today = quoteTradingDay(quote);
-      return reported && closeDate && today && closeDate < today ? { close, reported } : null;
+      return reported && closeDate && today && closeDate < today ? { close, reported, date: closeDate } : null;
+    }
+    if (closeDate ? closeDate === quoteTradingDay(quote) : state === "POST") {
+      return closeDate ? { close, reported, date: closeDate } : { close, reported };
     }
-    if (closeDate ? closeDate === quoteTradingDay(quote) : state === "POST") return { close, reported };
   }
   if (state === "POST" && isFiniteNumber(quote.postMarketPrice) && isFiniteNumber(quote.postMarketChange)) {
     const derived = quote.postMarketPrice - quote.postMarketChange;
@@ -251,6 +314,58 @@ function completedRegularClose(quote: Quote): number | null {
   return completedRegularSession(quote)?.close ?? null;
 }
 
+/**
+ * Whether a pre-market quote's pre-market price is a trade: not missing or
+ * 0, not the regular close carried forward, and, when the source projects
+ * its last print into the pre-market fields (`projected`), not the quote's
+ * own price.
+ */
+function hasPreMarketPrint(quote: Quote, close: number, projected: boolean): boolean {
+  const price = quote.preMarketPrice;
+  if (!isPositive(price) || price === close) return false;
+  return !(projected && price === quote.price);
+}
+
+/**
+ * The completed regular session a pre-market quote's headline still shows
+ * while nothing has traded in the pre-market, its exchange-local date and
+ * when it closed, so the quote reads as that close (`Thu close`, at 20:00
+ * UTC), not as the pre-market or the after-hours print before it. Only when
+ * the quote cannot hold a pre-market trade: never when the source says it
+ * does (extendedSessionPrint true); when it says nothing has traded (false),
+ * while its pre-market price is no trade (hasPreMarketPrint), its own price
+ * included while that was last updated before the pre-market opened; when it
+ * does not say, while there is no pre-market price other than the close and
+ * its last update is from before the venue's pre-market opened today. Null in
+ * any other session, and while the quote cannot say which close its headline
+ * is or its venue's hours are unknown.
+ */
+function preMarketCloseAwaitingPrint(quote: Quote | null | undefined): { date: string; closedAt: number } | null {
+  if (quote?.marketState !== "PRE" || quote.extendedSessionPrint === true) return null;
+  const session = completedRegularSession(quote);
+  const today = quoteTradingDay(quote);
+  if (!session?.date || !today) return null;
+  const exchange = quote.listingExchangeName || quote.exchangeName;
+  const opened = preMarketOpenOn(exchange, today);
+  // Last updated before today's pre-market opened: the price is carried from the last session.
+  const carried = opened != null && Number.isFinite(quote.lastUpdated) && quote.lastUpdated < opened;
+  const saysNoTrade = quote.extendedSessionPrint === false;
+  if (!saysNoTrade && !carried) return null;
+  if (hasPreMarketPrint(quote, session.close, saysNoTrade && carried)) return null;
+  const closedAt = regularSessionCloseOn(exchange, session.date);
+  return closedAt == null ? null : { date: session.date, closedAt };
+}
+
+/**
+ * When the price a quote's headline shows was observed: the regular close a
+ * pre-market with no trade yet still stands at (preMarketCloseAwaitingPrint),
+ * otherwise the quote's last update. What an Updated cell and a report's
+ * as-of date the quote by.
+ */
+export function quoteHeadlineTime(quote: Quote): number {
+  return preMarketCloseAwaitingPrint(quote)?.closedAt ?? quote.lastUpdated;
+}
+
 /**
  * The day's headline: the regular session, which stops at its close. Once it
  * is over, and in the pre-market while the quote carries the last session's
@@ -286,6 +401,27 @@ export function getCompletedRegularSessionDisplay(quote: Quote | null | undefine
   return quote && completedRegularClose(quote) != null ? getRegularSessionDisplay(quote) : null;
 }
 
+/**
+ * The price a daily, weekly or monthly bar takes from a quote: the regular
+ * session's, never an extended print, so a closed market's last bar is the
+ * close `history` and `portfolio show --close` give. While the session
+ * trades, or when the quote does not say its session, the quote's price. Once
+ * it is over, its close as the headline reads it, with that session's date
+ * when the quote reports one (in the pre-market it is an earlier day's).
+ * Null in the pre-market while the quote cannot say which close that is: a
+ * pre-market print is no regular session's price, and today's bar has not
+ * opened.
+ */
+export function getRegularSessionBarClose(quote: Quote | null | undefined): { price: number; sessionDate: string | null } | null {
+  if (!quote) return null;
+  const state = quote.marketState;
+  if (state == null || state === "REGULAR") return { price: quote.price, sessionDate: null };
+  const session = completedRegularSession(quote);
+  if (session) return { price: session.close, sessionDate: session.date ?? null };
+  if (state === "PRE" || (state === "PREPRE" && quote.preMarketPrice != null)) return null;
+  return { price: quote.price, sessionDate: null };
+}
+
 /**
  * The pre-market or after-hours print, measured from the regular close before
  * it, while the quote has one: the pre-market until the open, the after-hours
@@ -298,9 +434,12 @@ export function getExtendedSessionDisplay(quote: Quote | null | undefined): Exte
   if (overnight) return overnight;
   const state = quote.marketState;
   if (state === "PRE" || state === "PREPRE") {
-    if (isFiniteNumber(quote.preMarketPrice)) {
+    // Nothing has traded in the pre-market: its figures are the close carried forward, no print.
+    if (state === "PRE" && preMarketCloseAwaitingPrint(quote)) return null;
+    // A pre-market price of 0 is no print.
+    if (isPositive(quote.preMarketPrice)) {
       // Against the close the headline shows, so the two cannot disagree about it.
-      const close = state === "PRE" && quote.preMarketPrice > 0 ? completedRegularClose(quote) : null;
+      const close = state === "PRE" ? completedRegularClose(quote) : null;
       if (close != null) {
         const change = quote.preMarketPrice - close;
         return { session: "PRE", price: quote.preMarketPrice, change, changePercent: (change / close) * 100 };

package/src/market-data/model-dividend-yield.ts

@@ -0,0 +1,117 @@
+import type { CorporateActionsData, Fundamentals } from "../types/financials";
+import { abortable, settleWithin } from "../utils/async-deadline";
+import { distributionHistory, forwardYieldMayHaveLapsed, lapsedDividend, lastPaidNote, NO_CURRENT_DIVIDEND } from "../utils/forward-dividend";
+
+/**
+ * How long a distribution history must go without a dividend before it says a
+ * security pays none: fifteen months, since an annual payer's next ex-date can
+ * slip a few weeks past a year (Gloom Cloud withdraws a lapsed yield the same
+ * way). Gloom Cloud's history reaches back ten years (SAP's and Novartis's
+ * annual dividends from 2017 on), well past this window.
+ */
+const NO_DIVIDEND_WINDOW_MS = 455 * 86_400_000;
+
+/** How long the history may take before the yield is left unknown. */
+const HISTORY_DEADLINE_MS = 5_000;
+
+/**
+ * The continuous dividend yield an option model values an underlying at, read
+ * the same way by OSA and the options chain's Greeks
+ * (docs/research-data.md#greeks-spot-and-time):
+ *
+ * - `stated`: the yield the underlying's fundamentals state, which the caller
+ *   reads (0 for a company whose quote affirms it pays none);
+ * - `none-paid`: 0, when no yield is stated but its distribution history,
+ *   current and covering dividends, has none paid or declared in the last
+ *   fifteen months (a fund that pays none, such as GLD);
+ * - `stopped`: 0, when the dividend has stopped by the issuer's own cadence
+ *   (lapsedDividend, as every pane reads a lapsed forward yield): WHR, last
+ *   paid 2026-02-27, whose stated 12.91% annualized a payment that did not
+ *   recur. `lastPaid` dates it.
+ *
+ * Null when none says: an unknown yield is never taken as 0.
+ */
+export interface ModelDividendYield {
+  /** Decimal annual yield. */
+  value: number;
+  basis: "stated" | "none-paid" | "stopped";
+  /** The last distribution's ex-date (YYYY-MM-DD) of a `stopped` dividend; null when unknown. */
+  lastPaid?: string | null;
+}
+
+/** What the yield is read from: the fundamentals' yield, its basis, and the ex-date of the distribution it annualizes. */
+type StatedDividend = Pick<Fundamentals, "dividendYield" | "dividendYieldBasis" | "exDividendDate">;
+
+const symbolKey = (value: string | null | undefined) => (value ?? "").trim().toUpperCase().replace(/[^A-Z0-9]/g, "");
+
+/** Whether a history is `symbol`'s own and current, covering dividends. */
+function currentHistory(actions: CorporateActionsData | null | undefined, symbol: string): actions is CorporateActionsData {
+  return !!actions && !actions.stale && actions.coverage?.dividends === "available" && symbolKey(actions.symbol) === symbolKey(symbol);
+}
+
+/** Whether a current history that covers dividends shows none paid or declared for `symbol` in the last fifteen months. */
+function paysNoDividend(actions: CorporateActionsData, now: number): boolean {
+  const since = now - NO_DIVIDEND_WINDOW_MS;
+  // A date that cannot be read counts as recent: it cannot show the dividend stopped.
+  const recent = (exDate: unknown) => {
+    const time = typeof exDate === "string" ? Date.parse(`${exDate.slice(0, 10)}T00:00:00Z`) : Number.NaN;
+    return !Number.isFinite(time) || time >= since;
+  };
+  return !actions.dividends.some((dividend) => recent(dividend.exDate))
+    && !(actions.declaredDividends ?? []).some((dividend) => recent(dividend.exDate));
+}
+
+/** 0, dated by the last distribution, when the current history shows the dividend dated `asOf` stopped (lapsedDividend). */
+function stoppedDividend(asOf: string | undefined, actions: CorporateActionsData, now: number): ModelDividendYield | null {
+  const lapse = lapsedDividend(asOf, distributionHistory(actions, new Date(now)), new Date(now));
+  return lapse ? { value: 0, basis: "stopped", lastPaid: lapse.lastPaid } : null;
+}
+
+interface DividendHistoryOptions {
+  now?: number;
+  /** Stops waiting for the history; the request itself is shared and keeps running. */
+  signal?: AbortSignal;
+  timeoutMs?: number;
+}
+
+/**
+ * The yield to value `symbol` at: 0 when its distribution history shows the
+ * dividend stopped, else `stated` when it is a yield, else 0 when the history
+ * shows none paid, else null. The history is read when no yield is stated,
+ * and for a forward yield old enough to have lapsed; one that fails, is stale
+ * or takes over five seconds leaves a stated yield as it is and an unstated
+ * one unknown.
+ */
+export async function loadModelDividendYield(
+  stated: StatedDividend | null | undefined,
+  symbol: string,
+  loadActions: (() => Promise<CorporateActionsData | null | undefined>) | null | undefined,
+  { now = Date.now(), signal, timeoutMs = HISTORY_DEADLINE_MS }: DividendHistoryOptions = {},
+): Promise<ModelDividendYield | null> {
+  const value = stated?.dividendYield;
+  const statedYield: ModelDividendYield | null = typeof value === "number" && Number.isFinite(value) && value >= 0
+    ? { value, basis: "stated" } : null;
+  const mayHaveLapsed = !!statedYield && statedYield.value > 0 && forwardYieldMayHaveLapsed(stated, new Date(now));
+  if ((statedYield && !mayHaveLapsed) || !loadActions) return statedYield;
+  const read = await abortable(settleWithin(Promise.resolve().then(loadActions), timeoutMs), signal, "Dividend history read was cancelled");
+  const actions = currentHistory(read, symbol) ? read : null;
+  if (!actions) return statedYield;
+  if (statedYield) return stoppedDividend(stated?.exDividendDate, actions, now) ?? statedYield;
+  if (paysNoDividend(actions, now)) return { value: 0, basis: "none-paid" };
+  return stoppedDividend(stated?.exDividendDate, actions, now);
+}
+
+/** What a yield the history shows none paid is, beside the 0%: `no dividend in the last 15 months`. */
+const NO_DIVIDEND_PAID = "no dividend in the last 15 months";
+
+/**
+ * What a yield read as 0 is, beside the 0%: `no dividend in the last 15
+ * months`, or `no current dividend, last paid 2026-02-27` in the words every
+ * pane reads a stopped dividend in. Null for a stated yield.
+ */
+export function modelDividendYieldNote(dividend: Pick<ModelDividendYield, "basis" | "lastPaid"> | null | undefined): string | null {
+  if (dividend?.basis === "none-paid") return NO_DIVIDEND_PAID;
+  if (dividend?.basis !== "stopped") return null;
+  const lastPaid = lastPaidNote({ lastPaid: dividend.lastPaid ?? null });
+  return lastPaid ? `${NO_CURRENT_DIVIDEND}, ${lastPaid}` : NO_CURRENT_DIVIDEND;
+}

package/src/market-data/quotes/freshness.ts

@@ -1,13 +1,16 @@
 import type { Quote } from "../../types/financials";
-import { isUsListingExchange } from "../../utils/exchanges";
+import { canonicalExchange, isUsListingExchange } from "../../utils/exchanges";
 import { zonedDateKey } from "../../utils/zoned-date-time";
 import { getPublishedUsEquitySession } from "../published-us-sessions";
 import { quoteFutureToleranceMs } from "./clock";
 import {
   activeUsExtendedHoursSession,
+  isAlwaysOpenExchange,
   isTimestampStaleForExchangeSession,
   isUsPriorSessionPremarketQuote,
   isUsRegularCloseQuoteInPostSession,
+  latestRegularSessionClose,
+  latestRegularSessionOpen,
 } from "../market/freshness";
 
 // Give the next regular session's NAV time to publish after its actual close.
@@ -90,6 +93,32 @@ export function isQuoteStaleForCurrentSession(quote: Quote | null | undefined, n
   );
 }
 
+/** Spot FX: its week is in `fx-market-hours`, not a session calendar. */
+const FX_VENUE = "CCY";
+/** Every venue with sessions has had one within this long; Spring Festival can close TWSE for twelve days. */
+const LONGEST_SESSION_GAP_MS = 14 * 24 * 60 * 60_000;
+
+/**
+ * Whether a quote's last print is older than its venue's latest completed
+ * regular session: a whole session traded since, so the state its source
+ * reports says where the market is, not where this price is (a delisted
+ * line read as OPEN). Only a quote already stale for its session can be;
+ * the last session's close before the open, an after-hours print after it,
+ * and round-the-clock venues and FX keep their state. A venue without a
+ * calendar counts a print older than any venue goes between sessions.
+ */
+export function isQuoteBeforeLatestSession(quote: Quote | null | undefined, now = Date.now()): boolean {
+  if (!quote || !isQuoteStaleForCurrentSession(quote, now)) return false;
+  const venue = canonicalExchange(quote.listingExchangeName || quote.exchangeName);
+  if (venue === FX_VENUE || isAlwaysOpenExchange(venue)) return false;
+  const printed = quote.lastUpdated;
+  if (!Number.isFinite(printed) || printed <= 0 || printed > now) return false;
+  const latest = latestRegularSessionClose(venue, now);
+  if (!latest) return now - printed > LONGEST_SESSION_GAP_MS;
+  const open = latestRegularSessionOpen(venue, latest.close);
+  return open != null ? printed < open : zonedDateKey(printed, latest.timeZone) < latest.date;
+}
+
 export function hasFreshQuoteForCurrentSession(
   quotes: Iterable<Quote | null | undefined>,
   now = Date.now(),

package/src/{plugins/builtin/portfolio-list → market-data/quotes}/live-valuation.ts

@@ -1,9 +1,11 @@
-import type { AnalystResearchData, Fundamentals, Quote } from "../../../types/financials";
-import { atRegularSessionPrice, regularSessionValuationPrice } from "../../../market-data/quotes/regular-session-valuation";
-import { hasLikelyQuoteUnitMismatch } from "../../../utils/currency-units";
-import { priceEarningsEps } from "../../../utils/fundamentals";
-import { selectMarketCapitalization, type MarketCapitalization } from "../../../utils/market-capitalization";
-import { priceEarningsOnEarnings, type PriceEarnings } from "../../../utils/price-earnings";
+import type { AnalystResearchData, CorporateActionsData, Fundamentals, Quote } from "../../types/financials";
+import { atRegularSessionPrice, regularSessionValuationPrice } from "./regular-session-valuation";
+import { hasLikelyQuoteUnitMismatch, resolveCurrencyUnit } from "../../utils/currency-units";
+import { cashInMajorUnits } from "../../utils/dividend-cash";
+import { cashDistribution, dividendReferencePrice, trailingDividendYield, type CashDistribution } from "../../utils/trailing-dividend";
+import { priceEarningsEps } from "../../utils/fundamentals";
+import { selectMarketCapitalization, type MarketCapitalization } from "../../utils/market-capitalization";
+import { priceEarningsOnEarnings, type PriceEarnings } from "../../utils/price-earnings";
 
 /**
  * Price-derived statistics repriced at the quote's regular session price
@@ -89,6 +91,50 @@ export function liveDividendYield(quote: Quote | null | undefined, fundamentals:
   return rate / price;
 }
 
+/** Whether a listing's yield is a trailing one, which is measured from its cash history (listingDividendYield). */
+export function measuresTrailingYield(fundamentals: Pick<Fundamentals, "dividendYield" | "dividendYieldBasis"> | null | undefined): boolean {
+  return fundamentals?.dividendYieldBasis === "trailing" && fundamentals.dividendYield != null;
+}
+
+/**
+ * A trailing dividend yield as DVD measures it (trailingDividendYield): the
+ * cash history's trailing twelve months over the quote's regular session
+ * price, in the cash's currency. Null when the history cannot be read in full
+ * (a row that is no paid distribution, no currency, dividends not covered) or
+ * the price is in another currency, where DVD leaves its own blank.
+ */
+export function historyTrailingDividendYield(
+  sourceActions: CorporateActionsData,
+  quote: Quote | null | undefined,
+  now = new Date(),
+): number | null {
+  const actions = cashInMajorUnits(sourceActions);
+  const currency = resolveCurrencyUnit(actions.currency).currency;
+  if (!currency || !Array.isArray(actions.dividends) || actions.coverage?.dividends === "unavailable") return null;
+  if (actions.coverage?.dividends !== "available" && actions.dividends.length === 0) return null;
+  const payments = actions.dividends.map((row) => cashDistribution(row.exDate, row.amount));
+  if (payments.some((payment) => payment == null)) return null;
+  const price = dividendReferencePrice(regularSessionValuationPrice(quote), quote?.currency, currency);
+  return trailingDividendYield(payments as CashDistribution[], price, now);
+}
+
+/**
+ * The dividend yield a listing shows at its regular session price. A trailing
+ * one is DVD's, measured from `actions`, the listing's cash history
+ * (historyTrailingDividendYield), so the overview, DIV% and DVD read one
+ * figure; until that history is read, or when it cannot be read in full, it
+ * is Gloom Cloud's, as a forward one is (liveDividendYield).
+ */
+export function listingDividendYield(
+  quote: Quote | null | undefined,
+  fundamentals: Fundamentals | undefined,
+  actions: CorporateActionsData | null | undefined,
+  now = new Date(),
+): number | undefined {
+  const measured = actions && measuresTrailingYield(fundamentals) ? historyTrailingDividendYield(actions, quote, now) : null;
+  return measured ?? liveDividendYield(quote, fundamentals);
+}
+
 /**
  * Whether a capitalization's implied share price is one this listing traded
  * at: the prior close (a source capitalization) or anywhere in the session

package/src/market-data/quotes/regular-session-valuation.ts

@@ -1,6 +1,9 @@
 import type { EnterpriseValueCheck, Fundamentals, Quote, TickerFinancials } from "../../types/financials";
 import { priceEarningsEps } from "../../utils/fundamentals";
-import { getRegularSessionDisplay } from "../market/status";
+import type { ReportTime } from "../../utils/utc-time";
+import { latestRegularSessionClose } from "../market/freshness";
+import { getCompletedRegularSessionDisplay, getRegularSessionDisplay } from "../market/status";
+import { quoteTradingDay } from "./day-range";
 
 function positive(value: number | null | undefined): value is number {
   return typeof value === "number" && Number.isFinite(value) && value > 0;
@@ -19,6 +22,34 @@ export function regularSessionValuationPrice(quote: Quote | null | undefined): n
   return positive(price) ? price : null;
 }
 
+/**
+ * When the completed regular session the quote reports closed: the venue's
+ * close on that day from its calendar, or the day alone when the calendar does
+ * not give the hour.
+ */
+function regularCloseTime(quote: Quote): ReportTime | null {
+  const date = quote.regularCloseSessionDate ?? quoteTradingDay(quote);
+  const exchange = quote.listingExchangeName || quote.exchangeName;
+  const close = exchange && Number.isFinite(quote.lastUpdated) ? latestRegularSessionClose(exchange, quote.lastUpdated) : null;
+  if (close && (!date || close.date === date)) return { time: close.close, dateOnly: false };
+  const day = date ? Date.parse(`${date}T00:00:00Z`) : Number.NaN;
+  return Number.isFinite(day) ? { time: day, dateOnly: true } : null;
+}
+
+/**
+ * When the price regularSessionValuationPrice reads is from: once the regular
+ * session is over (and in the pre-market while the quote carries the last
+ * session's close), that session's close; while it trades, the quote's own
+ * time. A figure measured at that price is dated by it, never by an
+ * after-hours or pre-market print. Null without a dated quote.
+ */
+export function regularSessionValuationTime(quote: Quote | null | undefined): ReportTime | null {
+  if (!quote) return null;
+  const close = getCompletedRegularSessionDisplay(quote) ? regularCloseTime(quote) : null;
+  if (close) return close;
+  return Number.isFinite(quote.lastUpdated) && quote.lastUpdated > 0 ? { time: quote.lastUpdated, dateOnly: false } : null;
+}
+
 function scaled(value: number | undefined, ratio: number): number | undefined {
   return value != null && Number.isFinite(value) ? value * ratio : value;
 }