gloomberb 0.17.2 → 0.17.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gloomberb",
-  "version": "0.17.2",
+  "version": "0.17.3",
   "packageManager": "bun@1.3.11",
   "description": "Market research and portfolio tracker for the terminal",
   "module": "src/public/index.ts",

package/src/api-client/futures-curve.ts

@@ -30,6 +30,22 @@ export interface FuturesContractTermsPayload {
   inDelivery: boolean
   /** The newest exchange settlement confirmed for the contract, with its session. */
   settlement: { price: number; date: string } | null
+  /**
+   * For a continuous symbol (CL=F) or a front generic: the nearest contract
+   * still trading when the symbol has rolled past it to the most active one,
+   * with its last trade; null when it prices the nearest itself. Absent from
+   * servers that do not send it.
+   */
+  nearest?: FuturesNearestContract | null
+}
+
+/** The nearest contract still trading, which a continuous symbol has rolled past (CLX26 under CL=F on Dec). */
+interface FuturesNearestContract {
+  contract: string
+  contractSymbol: string
+  /** YYYY-MM */
+  deliveryMonth: string
+  lastTrade: string | null
 }
 
 /** Gloom Cloud futures prices retain provider denomination and explicit quote units. */

package/src/api-client/index.ts

@@ -12,7 +12,7 @@ import {
   parseCloudLayoutEntry,
   parseCloudLayoutList,
 } from "../layout-marketplace/cloud";
-import type { SyncSnapshot } from "../sync/types";
+import { SyncRevisionConflictError, type SyncSnapshot } from "../sync/types";
 import { withDeadline } from "../utils/async-deadline";
 import { CloudASKGApi } from "./askg";
 import { CloudAuthApi } from "./auth";
@@ -450,14 +450,24 @@ class GloomApiClient {
     return this.request<CloudSyncSnapshotResponse>("/sync/snapshot", { method: "GET" });
   }
 
+  /**
+   * `baseRevision` goes out as If-Match: the server ignores the body field and
+   * would replace a snapshot another device wrote since this one pulled. With
+   * the header it refuses that write (409), raised as SyncRevisionConflictError
+   * so the controller pulls again instead.
+   */
   async putSyncSnapshot(snapshot: SyncSnapshot, options?: { baseRevision?: number | null }): Promise<CloudSyncPushResponse> {
-    return this.request<CloudSyncPushResponse>("/sync/snapshot", {
-      method: "PUT",
-      body: JSON.stringify({
-        snapshot,
-        baseRevision: options?.baseRevision ?? null,
-      }),
-    });
+    const baseRevision = options?.baseRevision ?? null;
+    try {
+      return await this.request<CloudSyncPushResponse>("/sync/snapshot", {
+        method: "PUT",
+        ...(baseRevision !== null ? { headers: { "If-Match": String(baseRevision) } } : {}),
+        body: JSON.stringify({ snapshot, baseRevision }),
+      });
+    } catch (error) {
+      if (error instanceof ApiRequestError && error.status === 409) throw new SyncRevisionConflictError(error.message);
+      throw error;
+    }
   }
 
   async getMarketplaceLayout(

package/src/api-client/types.ts

@@ -459,10 +459,12 @@ export interface CloudPricePointPayload {
   low?: number;
   close: number;
   volume?: number;
-  /** A coin's daily bar for the UTC day still forming when served; it has no volume yet. */
+  /** A daily bar still forming when served: a coin's UTC day, or the trade date a future is trading. */
   partial?: boolean;
   /** A coin's daily bar whose prices were rebuilt from hourly bars; a day the source left empty has no volume. */
   filled?: boolean;
+  /** A future's closed session whose settlement is not confirmed yet: it closes on the last trade. */
+  unsettled?: boolean;
 }
 
 type CloudEconImpact = "high" | "medium" | "low";

package/src/cli/commands/market.ts

@@ -24,6 +24,7 @@ import { withCliServices, withMarketData } from "../context";
 import { isoDate, parsePositiveInt, requireOneArg, takeFlag, takeOption } from "./command-utils";
 import type { BuiltinCliCommandDef } from "../command-options";
 import { CLI_COMMAND_GROUPS, TABLE_SECTION_OPTION } from "../help";
+import { CLI_EXIT_CODES } from "../exit-codes";
 import {
   formatChangePercentCell,
   formatCountCell,
@@ -44,7 +45,9 @@ import {
 import { getPublishedUsEquityCalendarYears, getPublishedUsEquitySession } from "../../market-data/published-us-sessions";
 import { isQuoteStaleForCurrentSession } from "../../market-data/quotes/freshness";
 import { isOptionsUnavailableError, listedOptionsAlternative, optionsUnavailableTitle } from "../../market-data/options-alternatives";
-import { cliFuturesContract, futuresContractMetrics, fundamentalsReportTables, renderFundamentalsReport } from "./ticker";
+import {
+  cliFuturesContract, futuresContractMetrics, fundamentalsReportTables, loadForwardYieldDeclarations, renderFundamentalsReport,
+} from "./ticker";
 import type { FuturesContractTermsPayload } from "../../api-client/futures-curve";
 import { futuresSettleText, isFuturesInstrument } from "../../market-data/futures-contract";
 import {
@@ -65,6 +68,7 @@ import {
   type OptionsChainBasis,
 } from "./options-chain";
 import { missingExpiryMessage } from "../../utils/option-expiry";
+import { declaredDividends } from "../../utils/declared-dividends";
 import {
   DEFAULT_LEAPS_CRITERIA, LEAPS_EXTRA_COLUMNS, LEAPS_USAGE, parseLeapsCriteria, runLeapsScreen, takeLeapsOptions,
 } from "./options-leaps";
@@ -143,14 +147,14 @@ import { earningsCalendarFailure, earningsChoiceNote, earningsDateLabel, isListi
 import { formatBasisPoints, toBasisPoints } from "../../utils/basis-points";
 import { notATickerSymbol, providerMissReason } from "../../sources/provider-errors";
 import { isNotATickerMessage, withListingSuggestion } from "../not-a-ticker";
-import { describeSuggestion, suggestListing } from "../listing-suggestion";
+import { describeSuggestion, suggestListing, suggestUsTicker, type ListingSuggestion } from "../listing-suggestion";
 import { splitSymbolArgs, uniqueSecuritySymbols } from "../symbol-args";
 import { cliPerpetualContract, perpetualContractStats, type PerpetualContractPayload } from "../perpetual-contract";
 import { subMinuteDataMessage } from "../known-gaps";
 import { secRegistrantMismatchMessage, SecRegistrantMismatchError, areDifferentCompanies } from "../../sources/sec-registrant";
 import { isCryptoPairSymbol } from "../../utils/crypto-pair";
 import { looksLikeCurrencyPair } from "../../utils/currency-pair";
-import { isUsListingExchange } from "../../utils/exchanges";
+import { canonicalExchange, isUsListingExchange } from "../../utils/exchanges";
 import { describeTickerChange, startTickerChangeLookup, tickerChangeLine, type TickerChange } from "../../tickers/ticker-changes";
 import { noSecReportsNotice, nonUsSecListingVenue } from "../../utils/sec";
 import type { MarketContext } from "../types";
@@ -208,6 +212,8 @@ type QuoteCliRecord = Omit<QuoteBatchResult, "error"> & {
   perpetualContract?: PerpetualContractPayload;
   /** The symbol changed: its issuer moved to another symbol, or its holder had another before. */
   tickerChange?: TickerChange;
+  /** A bare symbol read on a listing abroad that is one slip from a US ticker: the US ticker it was most likely typed for. */
+  usSuggestion?: ListingSuggestion;
 };
 type FinancialsCliData = TickerFinancials & {
   symbol: string;
@@ -504,6 +510,13 @@ function corporateActionRows(data: CorporateActionsData) {
       date: event.exDate,
       detail: currency ? formatDistributionAmount(event.amount, currency) : cleanDecimal(event.amount),
     })),
+    // Declared and unpaid, at its ex-date beside the paid rows, never one of them.
+    ...declaredDividends(data).map((event) => ({
+      type: "dividend",
+      date: event.exDate,
+      detail: `declared ${currency ? formatDistributionAmount(event.amount, currency) : cleanDecimal(event.amount)}`
+        + (event.payDate ? `, payable ${event.payDate}` : ""),
+    })),
     ...data.splits.map((event) => ({
       type: "split",
       date: event.date,
@@ -568,7 +581,9 @@ async function runQuote(rawArgs: string[], ctx: Parameters<CliCommandDef["execut
     // So is whether a symbol changed (FB is now META), for the same lists.
     const changes = new Map(listings.length > MAX_CHOICE_LOOKUPS ? []
       : listings.map((listing) => [listing, startTickerChangeLookup(market.dataProvider, listing.symbol, listing.exchange)] as const));
-    const results = await market.dataProvider.getQuotesBatch(targets, { forceRefresh: ctx.cliOptions.refresh });
+    // The service's quote of the moment, not each form's local copy from whenever it was last asked for:
+    // BRK.B saved on NYSE, BRK-B and BRK.B:NYSE print one quote (GLO-735). A local copy answers only offline.
+    const results = await market.dataProvider.getQuotesBatch(targets, { forceRefresh: ctx.cliOptions.refresh, revalidate: true });
     const listingOf = (result: QuoteBatchResult, index: number) => listings[targets.indexOf(result.target)] ?? listings[index]!;
     const asked = results.map(listingOf);
     const request = { command: commandName, noun: "quote" };
@@ -595,6 +610,11 @@ async function runQuote(rawArgs: string[], ctx: Parameters<CliCommandDef["execut
     const perpetualContracts = await Promise.all(answers.map(({ result }) => commandName === "quote" && result.quote
       ? cliPerpetualContract(result.quote)
       : null));
+    // A bare symbol quoted on a listing abroad (APPL, Aptus Pharma on BSE) that is one slip from a US ticker (AAPL) says so.
+    const usSuggestions = await Promise.all(answers.map(({ result, listing, notes }) => {
+      const venue = result.quote && !listing.saved ? bareListingNote(listing, result.quote) : null;
+      return venue && notes.includes(venue) ? suggestUsTicker(listing.symbol, market) : null;
+    }));
     // Each row names its listing by key (SAN:EPA) and company, so the table needs no line above it.
     const data = answers.map(({ result, listing, failure }, index) => ({
       target: result.target,
@@ -604,6 +624,7 @@ async function runQuote(rawArgs: string[], ctx: Parameters<CliCommandDef["execut
       quote: result.quote,
       ...contracts[index] ? { futuresContract: contracts[index] } : {},
       ...perpetualContracts[index] ? { perpetualContract: perpetualContracts[index] } : {},
+      ...usSuggestions[index] ? { usSuggestion: usSuggestions[index] } : {},
       error: failure?.oneLine ?? errorMessage(result.error),
       ...yieldIndexFields(result),
       ...tickerChanges[index] ? { tickerChange: tickerChanges[index] } : {},
@@ -630,15 +651,38 @@ async function runQuote(rawArgs: string[], ctx: Parameters<CliCommandDef["execut
       freshness: quotesFreshness(data.map((row) => row.quote)),
     }, {
       rows: quoteRows,
-      details: quoteFuturesContractText,
+      details: quoteDetailsText,
       columns,
       ...(yieldsOnly ? { textColumns: columns.map((column) => column.key === "changePercent" ? { ...column, header: "Chg" } : column) } : {}),
     });
+    // The table names each symbol it found nothing for; with none found, the exit status says so too.
+    if (data.every((row) => !row.quote)) process.exitCode = CLI_EXIT_CODES.error;
   });
 }
 
 /**
- * Under the table, each futures row's Settle line and Contract block, worded
+ * Under the table: each futures row's Settle line and Contract block, then the
+ * line for a symbol that is not a US ticker though it is one slip from one.
+ */
+function quoteDetailsText(data: QuoteCliRecord[]): string {
+  return [quoteFuturesContractText(data), ...data.flatMap((row) => notUsTickerLine(row) ?? [])].filter(Boolean).join("\n\n");
+}
+
+/**
+ * "APPL is not a US ticker: it is Aptus Pharma Limited on BSE (INR). Did you
+ * mean AAPL (Apple Inc.)?", for a symbol read on a listing abroad that is one
+ * slip from a US ticker, worded as the not-a-ticker answers word it.
+ */
+function notUsTickerLine({ target, quote, listing, usSuggestion }: QuoteCliRecord): string | null {
+  if (!quote || !usSuggestion) return null;
+  const venue = canonicalExchange(quote.listingExchangeName || quote.exchangeName);
+  const name = quote.name || listing?.name;
+  const what = `${name ? `${name} on ` : ""}${venue}${quote.currency ? ` (${quote.currency})` : ""}`;
+  return cliStyles.warning(`${target.symbol} is not a US ticker: it is ${what}. Did you mean ${describeSuggestion(usSuggestion)}?`);
+}
+
+/**
+ * Each futures row's Settle line and Contract block, worded
  * as `ticker` words them. Several symbols name theirs in the block's title.
  */
 function quoteFuturesContractText(data: QuoteCliRecord[]): string {
@@ -842,16 +886,18 @@ async function runHistory(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
     const flagColumn: CliResultColumn = {
       key: "flag", header: "Flag", format: (value) => typeof value === "string" ? cliStyles.warning(value) : "",
     };
-    // Text also marks a bar still forming or rebuilt from hourly bars there; exports keep them as their own fields.
+    // Text also marks a bar still forming, rebuilt from hourly bars or closing before its settlement; exports keep them as fields.
     const flagTextColumn: CliResultColumn = {
       ...flagColumn,
       format: (value, row) => [
         typeof value === "string" ? cliStyles.warning(value) : "",
         row.partial ? cliStyles.muted("partial") : "",
         row.filled ? cliStyles.muted("filled") : "",
+        row.unsettled ? cliStyles.muted("unsettled") : "",
       ].filter(Boolean).join(" "),
     };
     const marked = data.some((row) => row.partial || row.filled);
+    const unsettled = data.some((row) => row.unsettled);
     ctx.printResult({
       data,
       metadata: {
@@ -880,6 +926,7 @@ async function runHistory(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
         ...priceColumns,
         flagColumn,
         ...marked ? [{ key: "partial", header: "Partial" }, { key: "filled", header: "Filled" }] : [],
+        ...unsettled ? [{ key: "unsettled", header: "Unsettled" }] : [],
         ...volume ? [{ key: "volumeUnit", header: "Volume unit" }, { key: "volumeNote", header: "Volume note" }] : [],
       ],
       // Every exported row says what it is a bar of, the currency a price is in and its bar size, so it survives head and concatenation.
@@ -937,6 +984,10 @@ async function runFinancials(rawArgs: string[], ctx: Parameters<CliCommandDef["e
       // Market cap, the multiples and the yield at the regular session price, as the text gives them; the quote stays as sent.
       const priced = atRegularSessionPrice(financials);
       const capitalization = selectMarketCapitalization(priced.quote, priced.fundamentals);
+      // A forward yield dated ahead names the declared distribution it annualizes, in the text and tables.
+      const report = ctx.cliOptions.format === "json" ? data : {
+        ...data, declaredDividends: await loadForwardYieldDeclarations(market.dataProvider, listing.request, financials.fundamentals),
+      };
       ctx.printResult({
         // JSON reads a multiple over a loss as null with its reason, never as a number.
         data: {
@@ -951,8 +1002,8 @@ async function runFinancials(rawArgs: string[], ctx: Parameters<CliCommandDef["e
         freshness,
         ...(choice.length > 0 ? { warnings: choice } : {}),
       }, {
-        text: () => renderFundamentalsReport(data, view),
-        ...(tabular ? { tables: selectTables(fundamentalsReportTables(data, view, freshness)) } : {}),
+        text: () => renderFundamentalsReport(report, view),
+        ...(tabular ? { tables: selectTables(fundamentalsReportTables(report, view, freshness)) } : {}),
         exportIdentity: { symbolOrSeries: listing.key },
       });
       return;

package/src/cli/commands/search.ts

@@ -26,7 +26,7 @@ import { indexRootFor, indexRootTryLine } from "../index-roots";
 import { knownGapMessage, settingsPointer } from "../known-gaps";
 import { instrumentTypeLabel } from "../../tickers/instrument-kind";
 import { canonicalExchange, isUsListingExchange } from "../../utils/exchanges";
-import { groupByCompany } from "../../tickers/company-name";
+import { groupByCompany, sameCompany } from "../../tickers/company-name";
 import { findCatalogSeries, renderSeriesMatches, type SeriesMatch } from "../series-search";
 import { centralBankCiting, centralBankNamed, type CentralBank } from "../../utils/central-banks";
 import { createPaneCatalog } from "../pane-functions/discovery";
@@ -120,7 +120,7 @@ export async function searchCandidatesForCli({
     const quote = BARE_SYMBOL.test(symbol) && candidates.some((candidate) => candidate.symbol.toUpperCase() === symbol)
       ? await (quoted ?? loadSearchedQuote(symbol, savedExchange, dataProvider))
       : null;
-    return withQuotedNames(symbol, withPrimaryListingFirst(symbol, candidates, quote), quote).slice(0, totalLimit);
+    return withQuotedNames(symbol, withHomeListingPrimary(symbol, withPrimaryListingFirst(symbol, candidates, quote)), quote).slice(0, totalLimit);
   } catch {
     return [];
   }
@@ -217,6 +217,47 @@ function withPrimaryListingFirst(
   ));
 }
 
+/** Venues that only quote shares listed elsewhere: the OTC tiers, Frankfurt's open market and Germany's regional exchanges. */
+const SECONDARY_VENUES = new Set(["OTC", "PNK", "OTCQX", "OTCQB", "FWB2", "MUNICH", "XSTU", "XDUS", "XBER", "XHAM", "HANOVER"]);
+
+/**
+ * How far a listing is from being its company's own line: 0 a plain one, 1 a
+ * line that only quotes shares listed elsewhere (a regional venue, OTC, a
+ * Milan 4MSFT or London 0XXX code), 2 a depositary receipt.
+ */
+function listingDistance(candidate: TickerSearchCandidate): 0 | 1 | 2 {
+  if (/depositary|^(?:ADR|ADS|GDR|CDR|BDR)$/i.test(candidate.instrumentType ?? "")) return 2;
+  return SECONDARY_VENUES.has(candidateExchange(candidate)) || /\d/.test(candidate.symbol) && /[A-Za-z]/.test(candidate.symbol) ? 1 : 0;
+}
+
+/**
+ * A company searched by name lists its home line as the primary listing. A
+ * search row names no home exchange or volume, so a company's lines go by
+ * how far each is from being its own line (`listingDistance`), then by the
+ * search score the service gives the listings people look up most. The
+ * listing search put first, often the one-off cross-listing whose short name
+ * matched the query (LUFTHANSA on Budapest), gives way only to a closer line,
+ * or to one searched at least twice as often, or any scored line when it has
+ * no score. A listing searched by its own symbol is not moved.
+ */
+function withHomeListingPrimary(symbol: string, candidates: TickerSearchCandidate[]): TickerSearchCandidate[] {
+  const primary = candidates.find((candidate) => candidate.category === "Primary Listing");
+  if (!primary || primary.kind !== "search" || primary.symbol.toUpperCase() === symbol) return candidates;
+  const company = resolveSearchName(primary);
+  const lines = candidates.filter((candidate) => candidate.kind === "search" && candidate.category !== "Funds & Derivatives"
+    && (candidate.instrumentClass === "equity" || candidate.instrumentClass === "other") && sameCompany(resolveSearchName(candidate), company));
+  const score = (candidate: TickerSearchCandidate) => candidate.result?.popularity ?? candidate.popularity ?? null;
+  const [home] = [...lines].sort((a, b) => listingDistance(a) - listingDistance(b) || (score(b) ?? -1) - (score(a) ?? -1) || candidates.indexOf(a) - candidates.indexOf(b));
+  if (!home || home === primary) return candidates;
+  const closer = listingDistance(home) < listingDistance(primary);
+  const [homeScore, primaryScore] = [score(home), score(primary)];
+  const moreSearched = listingDistance(home) === listingDistance(primary) && homeScore != null && (primaryScore == null || homeScore >= primaryScore * 2);
+  if (!closer && !moreSearched) return candidates;
+  const rest = candidates.filter((candidate) => candidate !== home);
+  const at = rest.indexOf(primary);
+  return [...rest.slice(0, at), { ...home, category: "Primary Listing" as const }, { ...primary, category: "Other Listings" as const }, ...rest.slice(at + 1)];
+}
+
 /** The candidate on the venue the quote prices; the US exchanges share one symbol, so a quote on any of them is its one US line. */
 function quotedCandidate(candidates: readonly TickerSearchCandidate[], quote: Quote | null): TickerSearchCandidate | undefined {
   const quoted = canonicalExchange(quote?.listingExchangeName || quote?.exchangeName);

package/src/cli/commands/ticker.ts

@@ -3,7 +3,7 @@ import { formatReportedMoney } from "../../utils/reported-money";
 import { convertedPriceEarningsNote, enterpriseValueLabel, enterpriseValueReconciliationNote, epsConversionNote, fundamentalsCurrency, reportedEnterpriseValue, ttmConversionNote } from "../../utils/fundamentals";
 import { latestFinancialPeriod } from "../../utils/latest-financial-period";
 import { exportedFundamentals, formatPriceEarnings, priceEarningsOnEarnings } from "../../utils/price-earnings";
-import { describeFundamentalMarketCap, selectMarketCapitalization } from "../../utils/market-capitalization";
+import { describeFundamentalMarketCap, marketCapShareBasisNote, selectMarketCapitalization } from "../../utils/market-capitalization";
 import {
   formatCompact,
   formatCurrency,
@@ -32,9 +32,9 @@ import {
 import type { FuturesContractTermsPayload } from "../../api-client/futures-curve";
 import { futuresContractLines, futuresSettleText, isFuturesInstrument, loadFuturesContractTerms } from "../../market-data/futures-contract";
 import type { AppConfig } from "../../types/config";
-import type { FinancialStatement, Quote, TickerFinancials } from "../../types/financials";
+import type { DeclaredDividendAction, FinancialStatement, Quote, TickerFinancials } from "../../types/financials";
 import { quoteTradingDay } from "../../market-data/quotes/day-range";
-import { atRegularSessionPrice } from "../../market-data/quotes/regular-session-valuation";
+import { atRegularSessionPrice, regularSessionValuationPrice } from "../../market-data/quotes/regular-session-valuation";
 import { computeTickerPriceReturns } from "../../market-data/ticker-price-returns";
 import { instrumentTypeLabel, isCryptoVenuePerpetual, resolveTickerInstrumentKind } from "../../tickers/instrument-kind";
 import type { SecFilingItem } from "../../types/data-provider";
@@ -69,6 +69,7 @@ import { exportEntriesTable, reportFooterLines, type CliReportTables } from "../
 import type { ReportFreshness } from "../pane-functions/freshness";
 import { fundamentalsFreshness, quotesFreshness } from "../freshness";
 import { forwardDividendBasis } from "../../utils/forward-dividend";
+import { declaredDividends } from "../../utils/declared-dividends";
 import { notTheCoinNote } from "./crypto-hints";
 
 const NEWS_ITEM_LIMIT = 5;
@@ -347,11 +348,38 @@ function percentFigure(fraction: number | null | undefined, format: (value: numb
   return fraction != null ? { text: format(fraction), value: fraction * 100, unit: "%" } : { text: "—" };
 }
 
-/** A forward yield says what it annualizes and when, as DVD does (a declared distribution by its ex-date); any other yield is the figure alone. */
-function forwardYieldFigure(fundamentals: TickerFinancials["fundamentals"]): MetricFigure {
+/** The declared, unpaid distributions a forward yield dated ahead is named from, in their own currency. */
+export interface ForwardYieldDeclarations {
+  rows: DeclaredDividendAction[];
+  currency?: string;
+}
+
+/**
+ * The listing's declared distributions, read only for a forward yield whose
+ * ex-date is still ahead (the one case its basis names one); null otherwise,
+ * and when they cannot be read, which leaves the basis to its dates.
+ */
+export async function loadForwardYieldDeclarations(
+  dataProvider: Pick<MarketContext["dataProvider"], "getCorporateActions">,
+  listing: { symbol: string; exchange: string },
+  fundamentals: TickerFinancials["fundamentals"],
+  now = new Date(),
+): Promise<ForwardYieldDeclarations | null> {
+  const exDate = fundamentals?.dividendYieldBasis === "forward" ? fundamentals.exDividendDate ?? "" : "";
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(exDate) || exDate <= now.toISOString().slice(0, 10) || !dataProvider.getCorporateActions) return null;
+  try {
+    const actions = await dataProvider.getCorporateActions(listing.symbol, listing.exchange);
+    return { rows: declaredDividends(actions, now), ...(actions.currency ? { currency: actions.currency } : {}) };
+  } catch {
+    return null;
+  }
+}
+
+/** A forward yield says what it annualizes and when, as DVD does (a declared distribution by its ex-date and stated amount); any other yield is the figure alone. */
+function forwardYieldFigure(fundamentals: TickerFinancials["fundamentals"], declared: ForwardYieldDeclarations | null): MetricFigure {
   const figure = percentFigure(fundamentals?.dividendYield, formatFractionPercentCell);
   return fundamentals?.dividendYieldBasis === "forward" && fundamentals.dividendYield != null
-    ? { ...figure, text: `${figure.text} (${forwardDividendBasis(fundamentals.exDividendDate)})` }
+    ? { ...figure, text: `${figure.text} (${forwardDividendBasis(fundamentals.exDividendDate, { declared: declared?.rows, currency: declared?.currency })})` }
     : figure;
 }
 
@@ -368,6 +396,7 @@ function fundamentalsMetrics(
   priceReturns: { return1Y?: number | null; return3Y?: number | null },
   reportingCurrency: string | undefined,
   enterpriseValue = reportedMoney(reportedEnterpriseValue(fundamentals), enterpriseValueCurrency(quote, fundamentals)),
+  declared: ForwardYieldDeclarations | null = null,
 ): FundamentalsMetric[] {
   const signed = (value: number) => colorBySign(formatPercent(value), value);
   const receipt = fundamentals?.sharesOutstanding != null && sharesOutstandingInReceipts(quote, fundamentals, profile?.description);
@@ -382,7 +411,7 @@ function fundamentalsMetrics(
     { label: "EPS (TTM)", ...reportedMoney(fundamentals?.eps, fundamentals?.epsCurrency?.trim() || reportingCurrency, true) },
     {
       label: `Dividend Yield${fundamentals?.dividendYieldBasis ? ` (${fundamentals.dividendYieldBasis})` : ""}`,
-      ...forwardYieldFigure(fundamentals),
+      ...forwardYieldFigure(fundamentals, declared),
     },
     { label: "Revenue (TTM)", ...reportedMoney(fundamentals?.revenue, reportingCurrency) },
     { label: "Net Income (TTM)", ...reportedMoney(fundamentals?.netIncome, reportingCurrency) },
@@ -404,6 +433,34 @@ function fundamentalsMetrics(
   ];
 }
 
+/**
+ * The float and the short interest `fundamentals` prints after the share count: the shares short, short % of float
+ * and days to cover of one settlement, dated, as the JSON gives them and `SI` and `SIW` show them.
+ */
+function floatAndShortInterestMetrics(
+  quote: TickerFinancials["quote"],
+  fundamentals: TickerFinancials["fundamentals"],
+  profile: TickerFinancials["profile"],
+): FundamentalsMetric[] {
+  const finite = (value: number | undefined): value is number => value != null && Number.isFinite(value);
+  const float = fundamentals?.floatShares;
+  const short = fundamentals?.sharesShort;
+  const days = fundamentals?.shortRatio;
+  const date = fundamentals?.shortInterestDate;
+  const receipt = finite(float) && sharesOutstandingInReceipts(quote, fundamentals, profile?.description);
+  return [
+    finite(float) && float > 0
+      ? { label: "Float", text: formatCompact(float), value: float, ...(receipt ? { unit: "ADR equivalent" } : {}) }
+      : { label: "Float", text: "—" },
+    finite(short)
+      ? { label: "Short Interest", text: `${formatCompact(short)}${date ? ` (settled ${date})` : ""}`, value: short, unit: "shares" }
+      : { label: "Short Interest", text: "—" },
+    ...finite(short) && date ? [{ label: "Short Interest Settlement", text: date, value: date, exportOnly: true }] : [],
+    { label: "Short % of Float", ...percentFigure(fundamentals?.shortPercentOfFloat, formatFractionPercentCell) },
+    finite(days) ? { label: "Days to Cover", text: formatNumber(days, 2), value: days } : { label: "Days to Cover", text: "—" },
+  ];
+}
+
 function metricLines(metrics: readonly FundamentalsMetric[]): Array<[string, string]> {
   return metrics.filter((metric) => !metric.exportOnly).map((metric) => [metric.label, metric.text]);
 }
@@ -411,28 +468,35 @@ function metricLines(metrics: readonly FundamentalsMetric[]): Array<[string, str
 const TRAILING_MONEY_METRICS = new Set(["EPS (TTM)", "Revenue (TTM)", "Net Income (TTM)", "Operating Cash Flow (TTM)", "Free Cash Flow (TTM)"]);
 
 /**
- * The notes under shown fundamentals: how a labelled or withdrawn EV compares with market cap + debt - cash, what a
- * converted TTM block was converted from, an EPS in another currency than the amounts beside it, and what a P/E on
- * such an EPS divides.
+ * The notes under shown fundamentals: a market cap that does not rest on the share count shown, how a labelled or
+ * withdrawn EV compares with market cap + debt - cash, what a converted TTM block was converted from, an EPS in
+ * another currency than the amounts beside it, and what a P/E on such an EPS divides. `priced` is the snapshot at
+ * the regular session price (atRegularSessionPrice), the figures the lines show, so each note reads those.
  */
 function fundamentalsNotes(
-  fundamentals: TickerFinancials["fundamentals"],
+  priced: Pick<TickerFinancials, "quote" | "fundamentals">,
   metrics: readonly FundamentalsMetric[],
   quoteCurrency: string | undefined,
 ): string[] {
+  const fundamentals = priced.fundamentals;
   const shown = (label: string) => metrics.some((metric) => metric.label === label && metric.text !== "—");
+  const shareBasis = shown("Market Cap") && shown("Shares Outstanding")
+    ? marketCapShareBasisNote(selectMarketCapitalization(priced.quote, fundamentals), fundamentals?.sharesOutstanding,
+      regularSessionValuationPrice(priced.quote), priced.quote?.currency)
+    : undefined;
   const conversion = [...TRAILING_MONEY_METRICS].some(shown) ? ttmConversionNote(fundamentals) : undefined;
   const eps = shown("EPS (TTM)") ? epsConversionNote(fundamentals) : undefined;
   const priceEarnings = metrics.some((metric) => metric.label === "P/E (TTM)" && typeof metric.value === "number")
     ? convertedPriceEarningsNote(fundamentals, quoteCurrency)
     : undefined;
   const enterpriseValue = shown("Enterprise Value") ? enterpriseValueReconciliationNote(fundamentals) : undefined;
-  return [enterpriseValue, conversion, eps, priceEarnings].filter((note): note is string => !!note);
+  return [shareBasis, enterpriseValue, conversion, eps, priceEarnings].filter((note): note is string => !!note);
 }
 
-const VALUATION_METRICS = new Set(["Market Cap", "Enterprise Value", "P/E (TTM)", "Forward P/E", "PEG", "EPS (TTM)"]);
+// The share count is the market cap's basis: the cap is the count times the price, or a note says why not.
+const VALUATION_METRICS = new Set(["Market Cap", "Shares Outstanding", "Enterprise Value", "P/E (TTM)", "Forward P/E", "PEG", "EPS (TTM)"]);
 
-type FundamentalsReportData = TickerFinancials & { symbol: string; exchange?: string };
+type FundamentalsReportData = TickerFinancials & { symbol: string; exchange?: string; declaredDividends?: ForwardYieldDeclarations | null };
 
 /**
  * What a fund's report cannot show yet, and for a US listing where its SEC
@@ -502,9 +566,16 @@ function fundamentalsReportMetrics(snapshot: FundamentalsReportData, view: "fund
   const marketCap: MetricFigure = capitalization
     ? { text: `${formatCompact(capitalization.value)} ${capitalization.currency}`, value: capitalization.value, unit: capitalization.currency }
     : { text: "—" };
-  const metrics = fundamentalsMetrics(quote, fundamentals, financials.profile, marketCap, computeTickerPriceReturns(financials), fundamentalsCurrency(financials));
-  if (view === "fundamentals") return metrics.filter((metric) => metric.text !== "—");
-  const valuation = metrics.filter(({ label, text }) => (VALUATION_METRICS.has(label) || label.startsWith("Dividend Yield")) && text !== "—");
+  const metrics = fundamentalsMetrics(quote, fundamentals, financials.profile, marketCap, computeTickerPriceReturns(financials), fundamentalsCurrency(financials),
+    undefined, snapshot.declaredDividends ?? null);
+  if (view === "fundamentals") {
+    return [...metrics, ...floatAndShortInterestMetrics(quote, fundamentals, financials.profile)]
+      .filter((metric) => metric.text !== "—");
+  }
+  const valued = metrics.filter(({ label, text }) => (VALUATION_METRICS.has(label) || label.startsWith("Dividend Yield")) && text !== "—");
+  // The share count follows the market cap it is the basis of.
+  const shares = valued.filter((metric) => metric.label === "Shares Outstanding");
+  const valuation = valued.flatMap((metric) => metric.label === "Shares Outstanding" ? [] : metric.label === "Market Cap" ? [metric, ...shares] : [metric]);
   // A listing with no valuation (a fund) says so rather than printing its price alone.
   return valuation.length === 0 ? [] : [...valuationPriceMetrics(financials).filter((metric) => metric.text !== "—"), ...valuation];
 }
@@ -532,7 +603,7 @@ export function renderFundamentalsReport(
   const fund = fundFactsNote(symbol, financials.exchange || quote?.exchangeName, financials);
   if (lines.length === before) lines.push("", cliStyles.muted([`No ${view} reported for ${financials.symbol}.`, fund].filter(Boolean).join(" ")));
   else if (fund) lines.push(cliStyles.muted(fund));
-  for (const note of fundamentalsNotes(financials.fundamentals, metrics, quote?.currency)) lines.push(cliStyles.muted(note));
+  for (const note of fundamentalsNotes(atRegularSessionPrice(financials), metrics, quote?.currency)) lines.push(cliStyles.muted(note));
   if (view === "fundamentals") appendTextSection(lines, "Description", profile?.description);
   return lines.join("\n");
 }
@@ -572,7 +643,7 @@ export function fundamentalsReportTables(
       notes: [
         ...metrics.length === 0
           ? [`No ${view} reported for ${financials.symbol}.`]
-          : fundamentalsNotes(financials.fundamentals, metrics, financials.quote?.currency),
+          : fundamentalsNotes(atRegularSessionPrice(financials), metrics, financials.quote?.currency),
         ...fund ? [fund] : [],
       ],
     }),
@@ -605,8 +676,11 @@ export async function buildTickerReport({
   recentNews = [],
   recentSecFilings = [],
   futuresContract = null,
+  declaredDividends: declared = null,
 }: {
   symbol: string;
+  /** The declared distributions a forward yield dated ahead is named from (loadForwardYieldDeclarations). */
+  declaredDividends?: ForwardYieldDeclarations | null;
   /** The exchange the command named, as a canonical code. */
   listingExchange?: string;
   /** A futures symbol's contract terms and latest confirmed settlement. */
@@ -732,10 +806,11 @@ export async function buildTickerReport({
     ]);
   }
 
-  const metrics = fundamentalsMetrics(quote, priced.fundamentals, profile, { text: marketCapText }, priceReturns, fundamentalsCurrency(financials), { text: enterpriseValueText });
+  const metrics = fundamentalsMetrics(quote, priced.fundamentals, profile, { text: marketCapText }, priceReturns, fundamentalsCurrency(financials),
+    { text: enterpriseValueText }, declared);
   const beforeFundamentals = lines.length;
   appendMetricSection(lines, "Fundamentals", metricLines(metrics));
-  for (const note of fundamentalsNotes(fundamentals, metrics, quote?.currency)) lines.push(cliStyles.muted(note));
+  for (const note of fundamentalsNotes(priced, metrics, quote?.currency)) lines.push(cliStyles.muted(note));
   // Where a fund's facts would go: under its fundamentals, or in their place.
   const fund = fundFactsNote(quote?.symbol ?? symbol,
     quote?.tradingExchangeName || listingExchange || quote?.listingExchangeName || quote?.exchangeName || tickerFile?.metadata.exchange, financials, tickerFile);
@@ -948,6 +1023,9 @@ export async function ticker(symbol: string, dependencies: TickerCommandDependen
 
     const notesFiles = new NotesFiles(dataDir);
     const listingName = listingIdentity(listing, quote).name;
+    // The text report's yield basis, read beside the rest for a forward yield dated ahead only; it never fails the report.
+    const declarations = dependencies.printResult ? null
+      : loadForwardYieldDeclarations(dataProvider, { symbol: requestSymbol, exchange }, resolvedFinancials.fundamentals);
     const [notesResult, newsResult, secFilingsResult] = await Promise.allSettled([
       notesFiles.load(tickerFile?.metadata.ticker ?? normalized),
       dataProvider.getNews({
@@ -1013,6 +1091,7 @@ export async function ticker(symbol: string, dependencies: TickerCommandDependen
         recentNews,
         recentSecFilings,
         futuresContract,
+        declaredDividends: await declarations,
     }));
     if (freshness) console.log(`\n${cliFreshnessFooter(freshness)}`);
   });