gloomberb 0.18.4 → 0.19.0

package/src/time-series/total-return.ts

@@ -0,0 +1,160 @@
+import type { CorporateActionsData } from "../types/financials";
+import { cashInMajorUnits } from "../utils/dividend-cash";
+import { resolveCurrencyUnit } from "../utils/currency-units";
+import { logFailure } from "../utils/log-failure";
+import { dividendReferencePrice } from "../utils/trailing-dividend";
+import { observationDate } from "./price-comparison";
+import { CHART_RESOLUTION_STEP_MS, chartBarSizeStepMs } from "./resolution";
+import type { ResolvedSeries, TimeSeriesPoint } from "./types";
+
+/** One cash distribution per share: its ex-date (`YYYY-MM-DD`) and its amount in the listing's major currency unit. */
+export interface CashDistribution {
+  exDate: string;
+  amount: number;
+}
+
+export interface TotalReturnOptions {
+  /** The session day a bar belongs to, `YYYY-MM-DD`. */
+  dayOf: (point: TimeSeriesPoint) => string;
+  /**
+   * A bar's price in the distributions' currency unit, or null when the two
+   * currencies differ (nothing is converted).
+   */
+  cashPrice: (price: number) => number | null;
+  /**
+   * Bars longer than a session (weekly, monthly) are dated at their start, so a
+   * distribution belongs to the bar that holds its ex-date, not the first one
+   * dated on or after it. This is how many days a bar holds; the last bar holds
+   * that many from its own date, and a distribution after that precedes no bar.
+   */
+  barDays?: number;
+  /** Today, `YYYY-MM-DD`: a distribution dated after it has not gone ex. */
+  asOf?: string;
+}
+
+export interface TotalReturnResult {
+  points: TimeSeriesPoint[];
+  /** Distributions reinvested inside the series; one before its first bar or after its last is not. */
+  applied: number;
+}
+
+/** The day a bar of `barDays` days dated `day` ends on; 30-day multiples are calendar months. */
+function barEnd(day: string, barDays: number): string {
+  const end = new Date(`${day}T00:00:00Z`);
+  if (barDays >= 28 && barDays % 30 === 0) end.setUTCMonth(end.getUTCMonth() + barDays / 30);
+  else end.setUTCDate(end.getUTCDate() + barDays);
+  return end.toISOString().slice(0, 10);
+}
+
+function scaled(value: number | null | undefined, factor: number): number | null | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value * factor : value;
+}
+
+/**
+ * A price series as its total return: every cash distribution is reinvested at
+ * the close of its ex-date bar, so the series moves by (close + cash) over the
+ * bar before. Each price is multiplied by the shares the cash has bought
+ * since the series began, which leaves its first bar as it was; volume is
+ * left alone. A distribution dated at or before the first bar precedes the
+ * series, so nothing is reinvested for it.
+ */
+export function reinvestDistributions(
+  points: readonly TimeSeriesPoint[],
+  distributions: readonly CashDistribution[],
+  { dayOf, cashPrice, barDays, asOf }: TotalReturnOptions,
+): TotalReturnResult {
+  const ordered = [...points].sort((left, right) => left.date.getTime() - right.date.getTime());
+  const holdingBar = barDays !== undefined && barDays > 1;
+  const cash = distributions
+    .filter((entry) => /^\d{4}-\d{2}-\d{2}$/.test(entry.exDate) && Number.isFinite(entry.amount) && entry.amount > 0
+      && (asOf === undefined || entry.exDate <= asOf))
+    .sort((left, right) => left.exDate.localeCompare(right.exDate));
+  const days = ordered.map(dayOf);
+  let factor = 1;
+  let applied = 0;
+  let next = 0;
+  const adjusted = ordered.map((point, index) => {
+    const barDay = days[index]!;
+    const before = holdingBar ? days[index + 1] ?? barEnd(barDay, barDays!) : null;
+    while (next < cash.length) {
+      const entry = cash[next]!;
+      if (before !== null ? entry.exDate >= before : entry.exDate > barDay) break;
+      if (index === 0) { next += 1; continue; }
+      const close = point.close ?? point.value;
+      // A bar with no price leaves the cash for the next bar that has one.
+      if (typeof close !== "number" || !Number.isFinite(close) || close <= 0) break;
+      // Cash in another currency than the price buys nothing: the series stays a price series.
+      const price = cashPrice(close);
+      if (price !== null && price > 0) {
+        factor *= 1 + entry.amount / price;
+        applied += 1;
+      }
+      next += 1;
+    }
+    if (factor === 1) return point;
+    return {
+      ...point,
+      value: scaled(point.value, factor) ?? null,
+      ...point.rawValue !== undefined ? { rawValue: scaled(point.rawValue, factor) ?? null } : {},
+      ...point.open !== undefined ? { open: scaled(point.open, factor) } : {},
+      ...point.high !== undefined ? { high: scaled(point.high, factor) } : {},
+      ...point.low !== undefined ? { low: scaled(point.low, factor) } : {},
+      ...point.close !== undefined ? { close: scaled(point.close, factor) } : {},
+    };
+  });
+  return { points: adjusted, applied };
+}
+
+export interface TotalReturnOutcome {
+  series: ResolvedSeries;
+  /** Why the series stays a price series, when it does. */
+  notice?: string;
+}
+
+const DAY_MS = 86_400_000;
+
+/** How many days a bar holds when it is longer than a session (a month counts as 30), so a distribution belongs to the bar holding its ex-date. */
+function barDaysLongerThanSession(series: Pick<ResolvedSeries, "barSize" | "historyResolution">): number | undefined {
+  const step = series.barSize ? chartBarSizeStepMs(series.barSize)
+    : series.historyResolution ? CHART_RESOLUTION_STEP_MS[series.historyResolution] : null;
+  return step !== null && step > DAY_MS ? Math.round(step / DAY_MS) : undefined;
+}
+
+/**
+ * A price series as its total return, from the cash history its listing pays.
+ * The series says which basis it ended up on: `total` once its distributions
+ * are reinvested (a listing that pays none is its price), `price` with the
+ * reason when the history cannot be read, covers no distributions, or is in
+ * another currency than the prices. Nothing is converted.
+ */
+export async function totalReturnSeries(
+  series: ResolvedSeries,
+  loadActions: () => Promise<CorporateActionsData | null>,
+  priceCurrency: string | undefined,
+  asOf: Date,
+): Promise<TotalReturnOutcome> {
+  const priceOnly = (notice: string): TotalReturnOutcome => ({ series: { ...series, returnBasis: "price" }, notice });
+  const actions = await loadActions().catch(logFailure("total-return", "Loading distribution history failed", null));
+  if (!actions) return priceOnly("distribution history unavailable; showing the price return.");
+  const cash = cashInMajorUnits(actions);
+  const dividends = Array.isArray(cash.dividends) ? cash.dividends : [];
+  if (cash.coverage?.dividends === "unavailable" || (cash.coverage?.dividends !== "available" && dividends.length === 0)) {
+    return priceOnly("distribution history unavailable; showing the price return.");
+  }
+  const currency = resolveCurrencyUnit(cash.currency).currency;
+  if (dividends.length > 0 && !currency) return priceOnly("distribution currency unknown; showing the price return.");
+  if (dividends.length > 0 && !resolveCurrencyUnit(priceCurrency).currency) {
+    return priceOnly("price currency unknown; showing the price return.");
+  }
+  if (dividends.length > 0 && dividendReferencePrice(1, priceCurrency, currency) === null) {
+    return priceOnly(`distributions are in ${currency}, not the price currency; showing the price return.`);
+  }
+  const { points } = reinvestDistributions(series.points, dividends, {
+    dayOf: (point) => observationDate(point.date.getTime(), series),
+    cashPrice: (price) => dividendReferencePrice(price, priceCurrency, currency),
+    barDays: barDaysLongerThanSession(series),
+    asOf: asOf.toISOString().slice(0, 10),
+  });
+  // "ECC Close" is its price: a label the chart wrote from the field says what the series is now.
+  return { series: { ...series, points, returnBasis: "total", label: series.label.replace(/ (?:Close|Price|Open|High|Low)$/, " Total return") } };
+}

package/src/time-series/transforms.ts

@@ -1,6 +1,7 @@
 import type { ResolvedSeries, SeriesTransform, TimeSeriesPoint } from "./types";
 import { calendarMonthsBefore } from "../utils/calendar-date";
 import { isFiniteNumber } from "../utils/guards";
+import { isOhlcSeriesStyle } from "./spec";
 
 const DAY_MS = 24 * 60 * 60 * 1_000;
 // Volume is separate supporting data, not another price. A volume series has
@@ -160,14 +161,13 @@ export function applyResolvedSeriesTransform(
     ...series,
     // A rebased or log value no longer counts what the price did.
     ...(series.statedUnit ? { statedUnit: undefined } : {}),
+    ...(series.valueDecimals !== undefined ? { valueDecimals: undefined } : {}),
     transform,
     rawUnit: series.rawUnit ?? series.unit,
     unit: percent ? "%" : transform === "index100" ? "index" : "log",
     unitGroup: percent ? "percent" : transform === "index100" ? "index" : "log",
     dataShape: "scalar",
-    style: series.style === "candles" || series.style === "ohlc" || series.style === "hlc"
-      ? "line"
-      : series.style,
+    style: isOhlcSeriesStyle(series.style) ? "line" : series.style,
     points: applySeriesTransform(series.points, transform, options),
   };
 }

package/src/time-series/types.ts

@@ -10,7 +10,7 @@ export type SeriesPeriod = "auto" | "daily" | "weekly" | "monthly" | "quarterly"
  * "band" draws a line through each point's value inside a shaded range from
  * its `low` to its `high`: an average within its historical range.
  */
-export type SeriesStyle = "line" | "area" | "step" | "columns" | "points" | "candles" | "ohlc" | "hlc" | "band";
+export type SeriesStyle = "line" | "area" | "step" | "columns" | "points" | "candles" | "hollow" | "heikin-ashi" | "ohlc" | "hlc" | "band";
 export type SeriesTransform = "raw" | "percent" | "index100" | "yoy" | "qoq" | "log";
 export type SeriesAxis = "auto" | "left" | "right";
 export type SeriesInterpolation = "none" | "step-after";
@@ -110,6 +110,11 @@ export interface ChartViewportSpec {
   maxPoints?: number;
   /** Intraday market history includes pre-market and after-hours bars where the venue has them. */
   extendedHours?: boolean;
+  /**
+   * Security price series are drawn as total returns: each cash distribution
+   * is reinvested at the close of its ex-date bar. Price returns otherwise.
+   */
+  totalReturn?: boolean;
 }
 
 export interface ChartSpec {
@@ -141,6 +146,8 @@ export interface TimeSeriesPoint {
   low?: number | null;
   close?: number | null;
   volume?: number | null;
+  /** The bar this figure traded in closed below its open: volume draws it in the falling colour. */
+  fell?: boolean;
   periodLabel?: string;
   /**
    * A financial statement period as the FA columns name it: `FY2025`, `Q3 FY26`,
@@ -183,6 +190,12 @@ export interface ResolvedSeries {
   unit: string;
   /** Unit of rawValue, retained when presentation transforms change unit. */
   rawUnit?: string;
+  /**
+   * What a price series' returns are, set when the chart asked for total
+   * returns: `total` once its distributions are reinvested, `price` when the
+   * source gave none to reinvest (`warning` says why).
+   */
+  returnBasis?: "total" | "price";
   unitGroup: string;
   /**
    * The unit the legend states beside each value, read bare as FUT prints its
@@ -192,6 +205,11 @@ export interface ResolvedSeries {
   statedUnit?: string;
   /** Source instrument category used only for monetary market-price precision. */
   priceAssetCategory?: string;
+  /**
+   * The decimals a value worked out from prices (a formula, a spread, a price
+   * over an FX rate) prints at: the most its legs print, from two to four.
+   */
+  valueDecimals?: number;
   /** Volume basis established by the source instrument; omitted when unspecified. */
   volumeUnit?: "shares" | "contracts";
   nativeFrequency: SeriesPeriod;
@@ -306,6 +324,14 @@ export interface ChartResolutionResult {
   loading: boolean;
   errors: string[];
   warnings: string[];
+  /**
+   * Where a series' source starts after the range asked for, and why (a
+   * publisher's cap on history), as `warnings` also carries it, so a report
+   * says it where it would otherwise print a range that quietly starts later.
+   */
+  coverageNotices?: string[];
+  /** What the price levels of a total-return chart without a comparison are (`warnings` also carries it). */
+  returnBasisNotice?: string;
   /**
    * Each charted listing that no longer trades: its symbol and label
    * ("Delisted Oct 27, 2022"), which `warnings` carries as "TWTR: Delisted Oct 27, 2022".

package/src/time-series/valuation-releases.ts

@@ -0,0 +1,39 @@
+import type { EarningsAction, FinancialStatement } from "../types/financials";
+import { regularSessionCloseOn } from "../market-data/market/freshness";
+import { financialAvailabilityTime } from "../utils/financial-statements";
+
+/** A reported event for this fiscal quarter, never a projected calendar date. */
+function releaseFor(statement: FinancialStatement, releases: readonly EarningsAction[]) {
+  return releases.filter((release) => release.dateType !== "fiscal-period-end"
+    && release.dateStatus === "reported"
+    && release.fiscalPeriod === statement.date.slice(0, 7)
+    && Date.parse(release.date) >= Date.parse(statement.date))
+    .sort((a, b) => a.date.localeCompare(b.date))[0];
+}
+
+/** Preserve dated inputs; an earnings release can precede the filing of the same period. */
+export function statementAtRelease(statement: FinancialStatement, releases: readonly EarningsAction[], exchange?: string): FinancialStatement {
+  const release = releaseFor(statement, releases);
+  if (!release) return statement;
+  const timestamp = release.reportedAt && Number.isFinite(Date.parse(release.reportedAt)) ? release.reportedAt : undefined;
+  const beforeClose = /^(bmo|dmh|pre[ -]?market|before (?:open|market)|during (?:market|hours))$/i.test(release.time ?? "");
+  const close = beforeClose ? regularSessionCloseOn(exchange, release.date) : null;
+  // A known session establishes availability by its close. Unknown timing,
+  // like an after-close release, takes effect on the following daily bar.
+  const publication = timestamp ?? (close != null ? new Date(close).toISOString() : release.date);
+  const earlier = (filed: string | undefined) => {
+    if (!filed) return undefined;
+    // A later comparative/restatement is not evidence that this value was in
+    // the original release. Restrict the substitution to this period's filing.
+    const lag = Date.parse(filed) - Date.parse(statement.date);
+    return lag >= 0 && lag <= 120 * 86_400_000 && financialAvailabilityTime(publication) <= financialAvailabilityTime(filed)
+      ? publication : filed;
+  };
+  return { ...statement,
+    availableAt: earlier(statement.availableAt),
+    ...(statement.fieldSources ? { fieldSources: Object.fromEntries(Object.entries(statement.fieldSources)
+      .map(([field, source]) => [field, source && { ...source, filed: earlier(source.filed) }])) } : {}),
+    ...(statement.fieldAvailability ? { fieldAvailability: Object.fromEntries(Object.entries(statement.fieldAvailability)
+      .map(([field, filed]) => [field, earlier(filed)!])) } : {}),
+  };
+}

package/src/types/data-provider.ts

@@ -148,6 +148,12 @@ export interface MarketDataRequestContext {
   historySession?: "extended";
   /** The listing's company, from its own quote: an SEC lookup for a non-US listing checks the registrant against it. */
   listingName?: string;
+  /**
+   * The caller prints what the quote's move is from: a short-lived process
+   * (the CLI) waits briefly for the daily closes that date a previous close
+   * no venue calendar dates. The long-lived app dates every quote anyway.
+   */
+  datesChangeBasis?: boolean;
 }
 
 export interface CachedFinancialsTarget {
@@ -216,6 +222,8 @@ export interface QuoteBatchOptions {
   revalidate?: boolean;
   /** The caller stopped waiting; a transport that can abandon the request does. */
   signal?: AbortSignal;
+  /** The caller prints what each move is from (MarketDataRequestContext.datesChangeBasis). */
+  datesChangeBasis?: boolean;
 }
 
 export interface TickerFinancialsBatchResult {
@@ -244,7 +252,7 @@ export interface AssetDataProvider {
   primaryMarketSourceName?(): string | null | Promise<string | null>;
   getCachedFinancialsForTargets?(targets: CachedFinancialsTarget[], options?: { allowExpired?: boolean; includeStaleQuotes?: boolean }): Map<string, TickerFinancials> | Promise<Map<string, TickerFinancials>>;
   getQuotesBatch?(targets: QuoteSubscriptionTarget[], options?: QuoteBatchOptions): Promise<QuoteBatchResult[]>;
-  getTickerFinancialsBatch?(targets: CachedFinancialsTarget[], options?: { forceRefresh?: boolean }): Promise<TickerFinancialsBatchResult[]>;
+  getTickerFinancialsBatch?(targets: CachedFinancialsTarget[], options?: { forceRefresh?: boolean; datesChangeBasis?: boolean }): Promise<TickerFinancialsBatchResult[]>;
   getTickerFinancials(ticker: string, exchange?: string, context?: MarketDataRequestContext): Promise<TickerFinancials>;
   getQuote(ticker: string, exchange?: string, context?: MarketDataRequestContext): Promise<Quote>;
   /** Listing facts may outlive the quote price; this method never returns price/session values. */

package/src/types/desktop-window.ts

@@ -8,6 +8,8 @@ export interface DesktopSharedStateSnapshot {
   /** @deprecated Ignored and no longer sent. */
   activePanel?: "left" | "right";
   statusBarVisible: boolean;
+  /** Transient position-sync failures, shared with detached Brokers panes. */
+  brokerSyncErrors?: Record<string, string>;
   mainStateRevision?: number;
   layoutChanged?: boolean;
 }

package/src/types/financials.ts

@@ -120,6 +120,12 @@ export interface Quote extends DepositaryReceiptFacts {
    */
   changeBasis?: "24h" | "none";
   previousClose?: number;
+  /**
+   * Exchange-local date of previousClose. The app's quote router reads it
+   * from the listing's own daily closes where the venue's calendar cannot
+   * date the close (PreviousCloseDates); a source may set it too.
+   */
+  previousCloseDate?: string;
   /** Official close of a completed regular session, in this quote's currency. */
   regularClose?: number;
   /** Exchange-local date of regularClose; separate from the daily previous-close reference. */
@@ -324,7 +330,12 @@ export interface Fundamentals extends DepositaryReceiptFacts {
   /** Set where Gloom Cloud checked `enterpriseValue` against market cap + total debt - cash; pairs with that value only. */
   enterpriseValueCheck?: EnterpriseValueCheck;
   /** Explicit provider retractions; omitted fields alone remain eligible for fallback. */
-  unavailableFields?: Array<"enterpriseValue" | "enterpriseToRevenue">;
+  unavailableFields?: Array<"enterpriseValue" | "enterpriseToRevenue" | "marketCap">;
+  /**
+   * Why `marketCap` is retracted, with "marketCap" in `unavailableFields`: a depositary receipt its source priced as
+   * an ordinary share (the receipt's price times the company's ordinary shares), with no ratio to convert them.
+   */
+  marketCapUnavailable?: "receipt-priced-as-ordinary";
   operatingCashFlow?: number;
   freeCashFlow?: number;
   dividendYield?: number;
@@ -339,6 +350,18 @@ export interface Fundamentals extends DepositaryReceiptFacts {
   revenue?: number;
   netIncome?: number;
   eps?: number;
+  /**
+   * Where `eps` and `trailingPE` come from: `filed-quarters` when `eps` is the
+   * diluted EPS of the last four filed quarters (or the fiscal year they end
+   * with), as PEB and GE read the statements, its last period ending
+   * `trailingEpsPeriodEnd`, and `trailingPE` the price over it; `served` when
+   * those quarters give none (or one that cannot be priced: see
+   * time-series/filed-trailing-eps) and both are Gloom Cloud's trailing
+   * figures, including a P/E it serves with no EPS (a fund's). Absent when
+   * there is neither an EPS nor a P/E.
+   */
+  trailingEpsSource?: "filed-quarters" | "served";
+  trailingEpsPeriodEnd?: string;
   operatingMargin?: number;
   profitMargin?: number;
   revenueGrowth?: number;
@@ -516,6 +539,8 @@ export type EarningsDateStatus = "reported" | "confirmed" | "projected";
 
 export interface EarningsAction {
   date: string;
+  /** Known release/acceptance timestamp, when the calendar has one. */
+  reportedAt?: string;
   dateType?: "announcement" | "fiscal-period-end";
   currency?: string;
   time?: string;
@@ -548,10 +573,24 @@ export interface CorporateActionsData {
   dividends: DividendAction[];
   /** Declared and unpaid, for the listings Gloom Cloud has them for; absent elsewhere and from older servers. */
   declaredDividends?: DeclaredDividendAction[];
+  /**
+   * What each paid row was declared as when the company declares in another
+   * currency than the listing pays (BP's dollars beside its London pence), per
+   * ordinary share, keyed by the paid row's ex-date. Absent elsewhere and from older servers.
+   */
+  declaredCash?: DeclaredCash;
+  /** Set when `dividends` is the last good history standing in for a refresh that could not read it: when that history was read. */
+  dividendsAsOf?: string;
   splits: SplitAction[];
   earnings: EarningsAction[];
 }
 
+/** Paid rows as their company declared them, in `currency` (its major unit). */
+export interface DeclaredCash {
+  currency: string;
+  rows: DividendAction[];
+}
+
 export interface CompanyProfile {
   description?: string;
   /**
@@ -971,6 +1010,8 @@ export interface EpsEstimateHistory {
 }
 
 export interface TickerFinancials {
+  /** Reported earnings-release events retained with daily valuation snapshots. */
+  earningsReleases?: EarningsAction[];
   statementHistory?: StatementHistoryAttempt;
   /** @deprecated No longer populated. */
   operatingHistoryRetryAt?: number;
@@ -1014,6 +1055,29 @@ export interface OptionContract {
   lastTradeDate: number;
   /** Millisecond timestamp for the latest streamed quote applied to this snapshot. */
   lastUpdated?: number;
+  /**
+   * A venue's own mark, for a venue that marks every contract (Deribit): the
+   * premium in `currency`, its implied volatility (a decimal) and Black-76
+   * greeks at the expiry's forward (delta per 1.00, gamma per 1.00, vega per
+   * volatility point, theta per calendar day). These replace the solved ones.
+   */
+  mark?: OptionMark;
+  /**
+   * The premiums in the coin a venue quotes them in (Deribit's BTC and ETH
+   * options); null where there is none. The contract's own prices are these
+   * at the expiry's forward.
+   */
+  coin?: { currency: string; bid: number | null; ask: number | null; mark: number; last: number | null };
+}
+
+export interface OptionMark {
+  price: number;
+  iv: number;
+  delta: number;
+  gamma: number;
+  vega: number;
+  theta: number;
+  forward: number;
 }
 
 export interface OptionsChain {
@@ -1023,11 +1087,18 @@ export interface OptionsChain {
   puts: OptionContract[];
   providerId?: string;
   dataSource?: "live" | "delayed";
-  feed?: "opra" | "gloom";
+  feed?: "opra" | "gloom" | "deribit";
   delayMinutes?: number;
   realtimeEligible?: boolean;
   /** ISO timestamp for the upstream options snapshot. */
   asOf?: string;
+  /**
+   * The rate the venue prices its premiums at (Deribit marks at zero); the
+   * model rate when absent, as for US listed options.
+   */
+  rate?: number;
+  /** The venue a chain is listed on when it is not a US options exchange (Deribit). */
+  venue?: string;
   /**
    * The session the chain's open interest counts, YYYY-MM-DD, as Gloom Cloud
    * states it; null when none of its counts is dated. Absent from a source

package/src/types/headless.ts

@@ -34,6 +34,12 @@ export interface HeadlessPaneArgumentDef {
   examples?: readonly string[];
 }
 
+/** A list the catalog prints under a function's options, such as the sector names a screen's criteria match. */
+export interface HeadlessPaneReference {
+  title: string;
+  items: readonly string[];
+}
+
 export interface HeadlessPaneOptionValue {
   value: string;
   aliases?: string[];
@@ -83,6 +89,8 @@ export interface HeadlessPaneOptionDef {
    * absent.
    */
   valueWords?: number;
+  /** The value is a comma list (`--metric trailingPE,dividendYieldPercent`), and the flag typed again adds to it. */
+  list?: boolean;
   /** The option in use as typed after the function, such as `--expiration 2028-01-21`; the catalog shows it as an example. */
   example?: string;
   /** The example runs without the function's optional argument, as an option that works only then does (`fn INS --side sell`). */
@@ -138,8 +146,10 @@ export interface HeadlessPaneContext {
    * known. A code several companies list (BDI) throws asking which, with
    * `quote`'s message; `argumentWith(key)` is the function's argument naming
    * that listing instead (`BDI:TSX`), for the retry each listing offers.
+   * `coinNote` is what `quote` says of a bare coin ticker read as a listing
+   * that is not the coin (ETH, the Grayscale fund), for the report's warnings.
    */
-  resolveListing?: (symbol: string, argumentWith: (key: string) => string) => Promise<{ symbol: string; exchange?: string; name?: string } | null>;
+  resolveListing?: (symbol: string, argumentWith: (key: string) => string) => Promise<{ symbol: string; exchange?: string; name?: string; coinNote?: string } | null>;
   /**
    * What a plugin keeps on this device only (its `ctx.resume` state, never
    * synced), such as ALRT's log of the alerts the app fired; null when none.
@@ -216,6 +226,14 @@ export interface HeadlessPaneEntry {
    * rather than read back the number `formatted` draws.
    */
   unit?: string;
+  /**
+   * In a report with `exportDated`, where this line is not of the section's own period and release (a previous
+   * reading, a year ago): the period it covers, when it was released and what it is as of. A null `released`
+   * or `asOf` leaves the cell blank rather than borrow the section's.
+   */
+  period?: string | null;
+  released?: string | null;
+  asOf?: string | null;
 }
 
 /**
@@ -353,7 +371,8 @@ export interface HeadlessPaneFreshness {
    * Each source's own newest observation, for data drawn from several venues
    * polled apart (a perpetuals board). The line then dates every source and
    * says how old the oldest of them is (`Binance 02:15 · Bybit 02:24 UTC ·
-   * oldest 9 min`), and `asOf` is the newest of them unless declared.
+   * oldest 9 min`), or with `ageOnly` the oldest observation, and `asOf` is the
+   * newest of them unless declared.
    */
   sources?: Array<{ source: string; asOf: string | number | Date }>;
   /** Say how old the oldest observation is (`oldest 4 min`): rows polled apart from one source. */
@@ -363,7 +382,8 @@ export interface HeadlessPaneFreshness {
    * For rows priced apart from a snapshot refreshed on a schedule (CRYP's board), where `live` would call prices
    * that are minutes old real-time and `delayed` would call a snapshot renewed every few seconds held back. A row
    * that states its own feed (`dataSource`, `delayMinutes`) still says it, and so does a declared `status`.
-   * Says how old the oldest observation is, as `oldestAge` does.
+   * Says how old the oldest observation is, as `oldestAge` does, even beside `sources`: a venue that streams some
+   * rows and not others is as old as its oldest row, not its newest.
    */
   ageOnly?: boolean;
   /**
@@ -527,6 +547,8 @@ export type HeadlessBundleSection =
     locked?: boolean;
     entries?: never;
     textEntries?: never;
+    period?: never;
+    released?: never;
   }
   | {
     title: string;
@@ -540,8 +562,14 @@ export type HeadlessBundleSection =
     textEntries?: HeadlessPaneEntry[];
     /** The symbol the figures are of, where the report's own is not: each exported line names it in `symbol_or_series`. */
     symbol?: string;
-    /** When the figures were observed (an ISO date or instant), where it is not the report's newest: each exported line names it in `as_of`. */
-    asOf?: string;
+    /**
+     * When the figures were observed (an ISO date or instant), where it is not the report's newest: each exported line names it in `as_of`.
+     * Null leaves `as_of` blank, for figures with no date of their own to state.
+     */
+    asOf?: string | null;
+    /** In a report with `exportDated`: the period the figures cover, and when they were released (an ISO date or instant), which each exported line names in `period` and `released`. */
+    period?: string;
+    released?: string;
     columns?: never;
     rows?: never;
     textColumns?: never;
@@ -584,6 +612,8 @@ export interface HeadlessSeries {
   interval?: string;
   /** Decimal places the text report prints the latest value to (a correlation to 3); JSON and CSV keep every digit. */
   textDecimals?: number;
+  /** The text report prints the latest value as the tables print an amount (63.33B), for a company's reported total; JSON and CSV keep every digit. */
+  textCompact?: boolean;
   /** Each point's `value` is its bar's close: `--csv` and `--ndjson` write Close alone, JSON keeps both. */
   valueIsClose?: boolean;
   points: HeadlessSeriesPoint[];
@@ -597,6 +627,8 @@ export interface HeadlessSeriesResult extends HeadlessPaneResultBase {
 export interface HeadlessSnapshotResult extends HeadlessPaneResultBase {
   asOf: string | number | Date;
   items: HeadlessPaneRow[];
+  /** What the report says when `items` is empty, in place of "No data.": why there are none. */
+  empty?: string;
 }
 
 export interface HeadlessPaneResultByShape {
@@ -622,6 +654,8 @@ export interface HeadlessPaneDefinition<Shape extends HeadlessPaneShape = Headle
     intents?: string[];
     dataRequirements?: string[];
     limitations?: string[];
+    /** Names an option's values match, listed by the catalog under each title: EQS's sectors and industries. */
+    reference?: HeadlessPaneReference[];
     screenshotReadiness?: "ready" | "partial" | "live-dom" | "unsupported";
   };
   /**
@@ -644,6 +678,21 @@ export interface HeadlessPaneDefinition<Shape extends HeadlessPaneShape = Headle
    * points at GIP's 1-minute bars). `key` is the listing as read, RMS:ASX.
    */
   usListingsOnlyHint?(key: string): string;
+  /**
+   * A typed symbol the function reads as another before it is resolved, with
+   * the note that says so: OPX and OVDV read a bare BTC or ETH as the coin
+   * (BTC-USD), whose options are the ones asked about, not the US fund that
+   * trades as BTC. Null reads the symbol as typed.
+   */
+  symbolAlias?(typed: string): { symbol: string; note: string } | null;
+  /**
+   * A listing the function has no data for, answered before any request with
+   * what exists instead: OPX and OVDV answer a coin nothing lists options on
+   * (SOL-USD) with BTC and ETH options, and OVDV, VCA and HIVG an FX pair with
+   * the currency funds' options. `key` is the listing as read; `details` is
+   * the line after `message`, left out when the message says it all.
+   */
+  refuseSymbol?(key: string): { message: string; details?: string } | null;
   /**
    * `fn` exits 1 when the report has no name with data: no rows, or every row
    * is one of `unavailableSymbols`. A list that gives data for some names
@@ -684,6 +733,13 @@ export interface HeadlessPaneDefinition<Shape extends HeadlessPaneShape = Headle
    * sessions), so a saved file keeps what stderr said.
    */
   exportWarnings?: boolean;
+  /**
+   * The rows are statistics dated by a period and a release, so `--csv` and
+   * `--ndjson` end every table with `period`, `released` and `retrieved` after
+   * the five fixed columns (a table's own columns of those names stand in for
+   * them), and `as_of` is the release, from the section's `rowAsOfKey` or `asOf`.
+   */
+  exportDated?: boolean;
   columns?: HeadlessPaneColumn[];
   /**
    * The report title. A report passes the loaded result, so a title can name

package/src/types/instrument.ts

@@ -79,6 +79,9 @@ export interface InstrumentSearchResult {
    * carries that name. A leftover listing of the merged company (GOGLC on
    * BYMA) is linked to it by search, naming the `successor`. */
   formerIssuer?: { symbol: string; name: string; until: string; successor?: { symbol: string; name: string | null } };
+  /** The name a renamed company had (Cassava Sciences Inc, now Filana Therapeutics' FLNA), sent by newer cloud
+   * servers on the row a search by that name found. `searchAliases` then carries it as EDGAR files it. */
+  formerName?: string;
   /** A US listing that no longer trades, found by its exact symbol (TWTR). Untrusted until parsed. */
   delisting?: ListingDelisting;
   /** The company's home line, its common stock on its home exchange (7203 on JPX for Toyota), sent by newer

package/src/types/news-source.ts

@@ -1,4 +1,5 @@
 export type {
+  NewsAccess,
   NewsArticle,
   NewsQuery,
   NewsQueryState,