gloomberb 0.18.3 → 0.18.4

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

@@ -1,9 +1,10 @@
 import { formatCurrency } from "../../../utils/format";
 import { comparablePriceEarnings, notMeaningfulMultiples } from "../../../utils/price-earnings";
-import { selectMarketCapitalization } from "../../../utils/market-capitalization";
-import { enterpriseValueReconciliationNote, enterpriseValueWithdrawn, reportedEnterpriseValue } from "../../../utils/fundamentals";
+import { marketCapBasisNote, viewMarketCapitalization } from "../../../utils/market-capitalization";
+import { enterpriseValueNotMeaningful, enterpriseValueReconciliationNote, enterpriseValueWithdrawn, reportedEnterpriseValue } from "../../../utils/fundamentals";
 import { getExtendedSessionDisplay, getQuoteSessionFields } from "../../../market-data/market/status";
-import { atRegularSessionPrice, movePriceDerivedFigures } from "../../../market-data/quotes/regular-session-valuation";
+import { atRegularSessionPrice, movePriceDerivedFigures, regularSessionValuationPrice } from "../../../market-data/quotes/regular-session-valuation";
+import { latestFinancialPeriod, latestReportedPeriod } from "../../../utils/latest-financial-period";
 import type { Quote, TickerFinancials } from "../../../types/financials";
 
 export function formatRelativePrice(price: number | null | undefined, currency: string | null | undefined): string {
@@ -12,6 +13,41 @@ export function formatRelativePrice(price: number | null | undefined, currency:
 }
 
 export const RELATIVE_VALUATION_STALE_QUOTE_NOTICE = "Quote stale: quote-based values unavailable";
+
+/** The RV figures a row can lack, each with the short reason it draws in its place. */
+export type RelativeValuationGapKey = "price" | "changePercent" | "marketCap" | "trailingPE" | "forwardPE"
+  | "evSales" | "fcfYield" | "revenueGrowth" | "operatingMargin";
+
+const NOT_REPORTED = "not reported";
+const QUOTE_STALE = "quote stale";
+
+const finiteNumber = (value: number | null | undefined): value is number => value != null && Number.isFinite(value);
+
+/** Why EV/S is missing, in the order the figure needs its parts. */
+function evSalesGap(
+  fundamentals: TickerFinancials["fundamentals"],
+  quoteCurrency: string | undefined,
+  withdrawn: boolean,
+  enterpriseValueGap: boolean,
+): string {
+  if (withdrawn || enterpriseValueGap) return "EV unavailable";
+  if (!fundamentals) return NOT_REPORTED;
+  if (!finiteNumber(fundamentals.enterpriseToRevenue) && !finiteNumber(fundamentals.enterpriseValue)) return "no EV";
+  if (!finiteNumber(fundamentals.enterpriseToRevenue) && !(finiteNumber(fundamentals.revenue) && fundamentals.revenue > 0)) return "no revenue";
+  // EV/S is read only where the TTM block names its currency and it is the price's.
+  if (!fundamentals.financialCurrency) return "revenue ccy unstated";
+  if (quoteCurrency && fundamentals.financialCurrency !== quoteCurrency) return `revenue in ${fundamentals.financialCurrency}`;
+  return NOT_REPORTED;
+}
+
+/** Why the FCF yield is missing: no trailing free cash flow, no cap, or the two in different currencies. */
+function fcfYieldGap(fundamentals: TickerFinancials["fundamentals"], capCurrency: string | null): string {
+  if (!finiteNumber(fundamentals?.freeCashFlow)) return "no TTM FCF";
+  if (!capCurrency) return "no market cap";
+  if (!fundamentals?.financialCurrency) return "FCF ccy unstated";
+  if (fundamentals.financialCurrency !== capCurrency) return `FCF in ${fundamentals.financialCurrency}`;
+  return NOT_REPORTED;
+}
 export const RELATIVE_VALUATION_STALE_FUNDAMENTALS_NOTICE = "Fundamentals stale: retained values may be out of date";
 
 /**
@@ -30,7 +66,9 @@ export function relativeValuationValues(snapshot: TickerFinancials | null) {
   const session = getQuoteSessionFields(quoteStale ? null : quote);
   // An overnight price that is the session's bid and ask midpoint, nothing having traded in it.
   const extendedMark = !quoteStale && getExtendedSessionDisplay(quote)?.mark === true;
-  const capitalization = selectMarketCapitalization(quoteStale ? undefined : quote, fundamentals);
+  // The cap `valuation` shows: the share count times the price where the provider's sits more than 2% from it.
+  const capitalization = viewMarketCapitalization(quoteStale ? undefined : quote, fundamentals,
+    quoteStale ? null : regularSessionValuationPrice(quote));
   const enterpriseValue = reportedEnterpriseValue(fundamentals);
   // A zero or non-finite enterprise value is the source's gap, and the ratio it serves beside it comes from the same observation.
   const enterpriseValueGap = fundamentals?.enterpriseValue != null && enterpriseValue == null;
@@ -42,10 +80,37 @@ export function relativeValuationValues(snapshot: TickerFinancials | null) {
   };
   // A multiple over a loss reads N/M even when the source served a positive one beside it.
   const { trailingPE: trailingNotMeaningful, forwardPE: forwardNotMeaningful } = notMeaningfulMultiples(fundamentals);
-  const notMeaningful = {
+  // An EV at or below zero makes EV/S N/M, whatever the source divided it by, as `valuation` reads the EV.
+  const evSalesNotMeaningful = enterpriseValueNotMeaningful(fundamentals);
+  const notMeaningful: Partial<Record<"trailingPE" | "forwardPE" | "evSales", string>> = {
     ...(trailingNotMeaningful ? { trailingPE: trailingNotMeaningful } : {}),
     ...(forwardNotMeaningful ? { forwardPE: forwardNotMeaningful } : {}),
+    ...(evSalesNotMeaningful ? { evSales: evSalesNotMeaningful } : {}),
   };
+  const evSalesWithdrawn = enterpriseValueWithdrawn(fundamentals);
+  const evSales = !compatibleCurrency || enterpriseValueGap || evSalesNotMeaningful ? null
+    : fundamentals?.enterpriseToRevenue != null && Number.isFinite(fundamentals.enterpriseToRevenue)
+      ? fundamentals.enterpriseToRevenue
+      : enterpriseValue != null && fundamentals?.revenue != null && fundamentals.revenue > 0
+        ? enterpriseValue / fundamentals.revenue : null;
+  const fcfYield = capitalization && fundamentals?.financialCurrency === capitalization.currency
+    && fundamentals.freeCashFlow != null && Number.isFinite(fundamentals.freeCashFlow) && capitalization.value > 0
+    ? fundamentals.freeCashFlow / capitalization.value : null;
+  const revenueGrowth = fundamentals?.revenueGrowth ?? fundamentals?.lastQuarterGrowth ?? null;
+  const operatingMargin = fundamentals?.operatingMargin ?? null;
+  const trailingPE = trailingNotMeaningful ? null : comparablePriceEarnings(reportedMultiples.trailingPE);
+  const forwardPE = forwardNotMeaningful ? null : comparablePriceEarnings(reportedMultiples.forwardPE);
+  // Every figure a row lacks says why, so an export's blank cell is never silent: N/M multiples say so themselves.
+  const gaps: Partial<Record<RelativeValuationGapKey, string>> = {};
+  if (session.price == null) gaps.price = quoteStale ? QUOTE_STALE : NOT_REPORTED;
+  if (session.changePercent == null) gaps.changePercent = quoteStale ? QUOTE_STALE : NOT_REPORTED;
+  if (capitalization == null) gaps.marketCap = quoteStale && !fundamentals?.marketCap ? QUOTE_STALE : NOT_REPORTED;
+  if (trailingPE == null && !trailingNotMeaningful && reportedMultiples.trailingPE == null) gaps.trailingPE = NOT_REPORTED;
+  if (forwardPE == null && !forwardNotMeaningful && reportedMultiples.forwardPE == null) gaps.forwardPE = NOT_REPORTED;
+  if (evSales == null && !evSalesNotMeaningful) gaps.evSales = evSalesGap(fundamentals, quote?.currency, evSalesWithdrawn, enterpriseValueGap);
+  if (fcfYield == null) gaps.fcfYield = fcfYieldGap(fundamentals, capitalization?.currency ?? null);
+  if (revenueGrowth == null) gaps.revenueGrowth = NOT_REPORTED;
+  if (operatingMargin == null) gaps.operatingMargin = NOT_REPORTED;
   return {
     ...session,
     extendedMark,
@@ -61,29 +126,33 @@ export function relativeValuationValues(snapshot: TickerFinancials | null) {
       source: fundamentals.source ?? null, retrievedAt: fundamentals.fetchedAt ?? null,
       stale: fundamentals.stale ?? null,
     } : null,
+    /** The newest statement period the trailing figures run through, as `valuation` names it. */
+    fundamentalsThrough: fundamentals && snapshot ? latestReportedPeriod(snapshot) : null,
+    /** The end of the latest quarter, the one revenueGrowth compares with a year earlier. */
+    revenueGrowthQuarter: revenueGrowth != null ? latestFinancialPeriod(snapshot?.quarterlyStatements, (row) => row.date)?.date ?? null : null,
     currency: quote?.currency ?? null,
     marketCap: capitalization?.value ?? null,
     marketCapCurrency: capitalization?.currency ?? null,
     marketCapProvenance: capitalization?.provenance ?? null,
-    trailingPE: trailingNotMeaningful ? null : comparablePriceEarnings(reportedMultiples.trailingPE),
-    forwardPE: forwardNotMeaningful ? null : comparablePriceEarnings(reportedMultiples.forwardPE),
+    /** valuation's note when the cap is the share count times the price: the provider's figure it replaced. */
+    marketCapNote: marketCapBasisNote(capitalization) ?? null,
+    trailingPE,
+    forwardPE,
     reportedMultiples,
-    /** Why a multiple is N/M: its earnings base is zero or a loss. */
+    /** Why a multiple is N/M: its earnings base is zero or a loss, or for EV/S the enterprise value is at or below zero. */
     notMeaningful,
     // Vendor ADR ratios can mix unverified valuation and reporting units too.
-    evSales: !compatibleCurrency || enterpriseValueGap ? null
-      : fundamentals?.enterpriseToRevenue != null && Number.isFinite(fundamentals.enterpriseToRevenue)
-        ? fundamentals.enterpriseToRevenue
-        : enterpriseValue != null && fundamentals?.revenue != null && fundamentals.revenue > 0
-          ? enterpriseValue / fundamentals.revenue : null,
+    evSales,
     /** Why EV/S is missing when the provider's EV was withdrawn, as `valuation` says it; null otherwise. */
-    evSalesUnavailable: enterpriseValueWithdrawn(fundamentals)
+    evSalesUnavailable: evSalesWithdrawn
       ? enterpriseValueReconciliationNote(fundamentals) ?? "EV unavailable." : null,
-    fcfYield: capitalization && fundamentals?.financialCurrency === capitalization.currency
-      && fundamentals.freeCashFlow != null && Number.isFinite(fundamentals.freeCashFlow) && capitalization.value > 0
-      ? fundamentals.freeCashFlow / capitalization.value : null,
-    revenueGrowth: fundamentals?.revenueGrowth ?? fundamentals?.lastQuarterGrowth ?? null,
-    operatingMargin: fundamentals?.operatingMargin ?? null,
+    /** Why EV/S is N/M, as `valuation` says it: "EV N/M: cash and short-term investments exceed ..."; null otherwise. */
+    evSalesNote: evSalesNotMeaningful ? enterpriseValueReconciliationNote(fundamentals) ?? null : null,
+    fcfYield,
+    revenueGrowth,
+    operatingMargin,
+    /** Why each missing figure is missing, in a few words the row draws in its place. */
+    gaps,
   };
 }
 

package/src/plugins/builtin/research/relative-valuation-pane.tsx

@@ -8,6 +8,7 @@ import {
   type DataTableCell,
   type DataTableColumn,
   type DataTableKeyEvent,
+  type PaneFooterSegment,
 } from "../../../components";
 import type { PaneProps } from "../../../types/plugin";
 import { useAppSelector, usePaneInstance } from "../../../state/app/context";
@@ -29,7 +30,11 @@ import { handleRefreshKey, useClampSelectedIndex } from "../../../components/dat
 import { useAsyncResource } from "../../../react/async-resource";
 import { useBoundTicker as useSymbolBinding } from "../shared/ticker-request";
 import { useFxRatesMap } from "../../../market-data/hooks";
+import { useRemoteUiNode } from "../../../remote/semantic-tree";
+import { quoteFreshnessFields } from "../shared/report-freshness";
 import { RELATIVE_VALUATION_STALE_FUNDAMENTALS_NOTICE, formatRelativePrice, relativeValuationValues, withLiveQuote } from "./relative-valuation-model";
+import { conversionNote, conversionPairText, convertMarketCaps, usdRateFromEntry } from "./relative-valuation-currency";
+import { fundamentalsBasisParts, fundamentalsThroughText } from "./relative-valuation-basis";
 
 type ExtendedColumnId = "preMarket" | "afterHours" | "overnight";
 type RelativeColumnId = "symbol" | "price" | "changePercent" | ExtendedColumnId | "marketCap" | "trailingPE" | "forwardPE" | "evSales" | "fcfYield" | "revenueGrowth" | "operatingMargin";
@@ -49,6 +54,34 @@ function relativeSymbolsFromPane(symbol: string | null, paneSettings: Record<str
 
 const EXTENDED_COLUMN_IDS: Record<ExtendedSession, ExtendedColumnId> = { PRE: "preMarket", POST: "afterHours", OVERNIGHT: "overnight" };
 
+/** The latest quarter's revenue against the same quarter a year earlier; the footer names the quarter. */
+const REVENUE_GROWTH_LABEL = "Q REV%";
+
+/**
+ * The footer's word on the figures, longest first: the rates MCAP was
+ * converted at with their times, the statement period the trailing figures
+ * run through and the quarter Q REV% compares, as `fn RV` ends; shorter forms
+ * keep the rates without their times, then the period alone after them, then
+ * the rates alone.
+ */
+function basisFooterSegment(conversions: Parameters<typeof conversionNote>[1], baseCurrency: string, basis: readonly string[], through: string | null): PaneFooterSegment | null {
+  const column = `MCAP ${baseCurrency}`;
+  const rates = conversions.length > 0 ? `${column} at ${conversions.map(conversionPairText).join(", ")}` : null;
+  const forms = [
+    [conversionNote(baseCurrency, conversions, column), ...basis],
+    [rates, ...basis],
+    [rates, through],
+    [rates ?? through],
+  ].map((form) => form.filter((part): part is string => !!part).join(" · "));
+  if (!forms[0]) return null;
+  const variants = [...new Set(forms.slice(1))].filter((form) => form && form !== forms[0]);
+  return {
+    id: "basis",
+    parts: [{ text: forms[0], tone: "muted" }],
+    ...(variants.length > 0 ? { variants: variants.map((text) => [{ text, tone: "muted" as const }]) } : {}),
+  };
+}
+
 /** The extended sessions some peer has a print for, in the order their columns go. */
 function extendedSessionsOf(rows: readonly RelativeRow[]): ExtendedSession[] {
   return (["PRE", "POST", "OVERNIGHT"] as const).filter((session) => rows.some((row) => row.extendedSession === session));
@@ -83,7 +116,7 @@ function buildRelativeColumns(baseCurrency: string, extendedSessions: readonly E
     { id: "evSales", label: "EV/S", width: metricWidth, align: "right" },
     { id: "fcfYield", label: "FCF%", width: metricWidth, align: "right" },
     // Latest quarter against the year before, and a trailing-twelve-month margin.
-    { id: "revenueGrowth", label: "Q REV%", width: metricWidth, align: "right" },
+    { id: "revenueGrowth", label: REVENUE_GROWTH_LABEL, width: metricWidth, align: "right" },
     { id: "operatingMargin", label: "TTM OP%", width: metricWidth, align: "right" },
   ];
 }
@@ -171,14 +204,16 @@ export function RelativeValuationPane({ focused, width, height }: PaneProps) {
     weight: 60,
   })), [symbols]);
   const { entries: liveQuotes } = useLiveQuoteEntries(quoteTargets);
-  const rows = useMemo<RelativeRow[]>(() => (peers ?? []).map((peer) => {
+  // Each peer's snapshot with its live quote laid over it.
+  const snapshots = useMemo(() => (peers ?? []).map((peer) => {
     const entry = liveQuotes.get(peerQuoteKey(peer.symbol));
-    return {
-      symbol: peer.symbol,
-      ...relativeValuationValues(withLiveQuote(peer.financials, entry ? resolveEntryValue(entry) : null)),
-      error: peer.error,
-    };
+    return { peer, financials: withLiveQuote(peer.financials, entry ? resolveEntryValue(entry) : null) };
   }), [liveQuotes, peers]);
+  const rows = useMemo<RelativeRow[]>(() => snapshots.map(({ peer, financials }) => ({
+    symbol: peer.symbol,
+    ...relativeValuationValues(financials),
+    error: peer.error,
+  })), [snapshots]);
   const fxRates = useFxRatesMap([baseCurrency, ...rows.map((row) => row.marketCapCurrency)]);
   // A pre-market or after-hours print gets its own column when a peer has one.
   const extendedSessionsKey = extendedSessionsOf(rows).join(",");
@@ -191,6 +226,36 @@ export function RelativeValuationPane({ focused, width, height }: PaneProps) {
     ...row, marketCap: convertMarketCapitalization(row.marketCap, row.marketCapCurrency, baseCurrency, fxRates),
   })), [rows, baseCurrency, fxRates]);
   const missingFx = rows.some((row, index) => row.marketCap != null && comparableRows[index]?.marketCap == null);
+  // The rates the converted caps were read at, each with when it was observed, as `fn RV --currency` names them.
+  const conversions = useMemo(() => {
+    const coordinator = getSharedMarketDataCoordinator();
+    const legs = new Map([...fxRates].flatMap(([currency, rate]) => (
+      currency === "USD" ? [] : [[currency, usdRateFromEntry(rate, coordinator?.getFxEntry(currency))] as const]
+    )));
+    const converted = rows.filter((row, index) => row.marketCapCurrency !== baseCurrency && comparableRows[index]?.marketCap != null);
+    return convertMarketCaps(converted, baseCurrency, legs).conversions;
+  }, [baseCurrency, comparableRows, fxRates, rows]);
+  const basis = useMemo(() => fundamentalsBasisParts(rows, REVENUE_GROWTH_LABEL), [rows]);
+  const through = useMemo(() => fundamentalsThroughText(rows), [rows]);
+  const basisSegment = useMemo(() => basisFooterSegment(conversions, baseCurrency, basis, through), [baseCurrency, basis, conversions, through]);
+  const footerInfo = useMemo(() => (basisSegment ? [basisSegment] : []), [basisSegment]);
+  // A capture of the pane ends as `fn RV` does: each venue's session, the feed's delay, then the footer's word on
+  // the figures. The pane draws the session part nowhere; its footer keeps the rest.
+  useRemoteUiNode(rows.length > 0 ? {
+    role: "report-freshness",
+    label: "Peer freshness",
+    getMetadata: () => ({
+      datesEachVenue: true,
+      ...(basisSegment ? {
+        note: basisSegment.parts[0]!.text,
+        noteVariants: (basisSegment.variants ?? []).map((variant) => variant[0]!.text),
+      } : {}),
+      observations: snapshots.map(({ financials }, index) => ({
+        ...quoteFreshnessFields(financials?.quote),
+        quoteAsOf: rows[index]?.quoteAsOf ?? null,
+      })),
+    }),
+  } : null);
   // Sorting by a live column would reshuffle rows under the cursor on every
   // tick; the order is taken from values sampled every few seconds instead,
   // and at once when the sort or the peer set changes.
@@ -216,6 +281,7 @@ export function RelativeValuationPane({ focused, width, height }: PaneProps) {
       ...rows.filter((row) => row.fundamentalsProvenance?.stale)
         .map((row) => `${row.symbol}: ${RELATIVE_VALUATION_STALE_FUNDAMENTALS_NOTICE}.`),
       ...rows.flatMap((row) => row.evSalesUnavailable ? [`${row.symbol}: ${row.evSalesUnavailable}`] : []),
+      ...rows.flatMap((row) => row.evSalesNote ? [`${row.symbol}: ${row.evSalesNote}`] : []),
     ],
     focused,
   });
@@ -243,7 +309,8 @@ export function RelativeValuationPane({ focused, width, height }: PaneProps) {
       case "forwardPE":
         return { text: formatPriceEarnings(row.notMeaningful.forwardPE ? NOT_MEANINGFUL : row.reportedMultiples.forwardPE), color: colors.text };
       case "evSales":
-        // A withdrawn EV says so; the footer says why.
+        // A withdrawn EV says so, one at or below zero reads N/M as a P/E over a loss does; the footer says why.
+        if (row.evSales == null && row.notMeaningful.evSales) return { text: formatPriceEarnings(NOT_MEANINGFUL), color: colors.text };
         return row.evSales == null && row.evSalesUnavailable
           ? { text: "EV n/a", color: colors.textDim }
           : { text: formatNumber(row.evSales ?? undefined, 1), color: colors.text };
@@ -266,7 +333,7 @@ export function RelativeValuationPane({ focused, width, height }: PaneProps) {
     }));
   }, []);
 
-  usePaneStatusFooter({ registrationId: "relative-valuation", loading, error: status });
+  usePaneStatusFooter({ registrationId: "relative-valuation", loading, error: status, info: footerInfo });
 
   return (
     <DataTableView<RelativeRow, RelativeColumn>

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

@@ -277,7 +277,7 @@ export async function pickPeers(symbol: string, financials: TickerFinancials | n
     description: financials?.profile?.description ?? null,
     marketCapUsd: null,
   };
-  const listYourOwn = `List them yourself: gloomberb fn RV ${symbol} <tickers>.`;
+  const listYourOwn = `List them yourself: gloom fn RV ${symbol} <tickers>.`;
   const group = peerGroupOf(subject);
   if (!group) throw new Error(`${symbol}'s profile names no industry, so --peers cannot pick its peers. ${listYourOwn}`);
   let candidates: PeerCandidates | null = null;

package/src/plugins/builtin/reverse-dcf/model.ts

@@ -1,8 +1,8 @@
 import { unavailableText } from "../../../components/ui/status";
 import { atRegularSessionPrice } from "../../../market-data/quotes/regular-session-valuation";
 import type { Fundamentals, TickerFinancials } from "../../../types/financials";
-import { enterpriseValueCheck, enterpriseValueLabel, enterpriseValueReconciliationNote, enterpriseValueWithdrawn,
-  reportedEnterpriseValue } from "../../../utils/fundamentals";
+import { enterpriseValueCheck, enterpriseValueLabel, enterpriseValueNotMeaningful, enterpriseValueReconciliationNote,
+  enterpriseValueWithdrawn, reportedEnterpriseValue } from "../../../utils/fundamentals";
 
 /** Years of explicit growth before the terminal value. */
 export const FORECAST_YEARS = 10;
@@ -151,6 +151,10 @@ export function projectReverseDcf(
   if (currency && valueCurrency && currency !== valueCurrency) {
     return { ...empty, error: `Cash flows are in ${currency} and the market value in ${valueCurrency}.` };
   }
+  // An EV at or below zero is N/M here as in `valuation` and RV, with the same reason: no growth rate prices it.
+  if (enterpriseValueNotMeaningful(fundamentals)) {
+    return { ...empty, enterpriseValue: null, error: enterpriseValueReconciliationNote(fundamentals)! };
+  }
   // A withdrawn EV is unavailable here as in `valuation`, which says why.
   if (enterpriseValueWithdrawn(fundamentals)) {
     return { ...empty, error: enterpriseValueReconciliationNote(fundamentals) ?? unavailableText("Enterprise value") };

package/src/plugins/builtin/risk-factors/index.tsx

@@ -29,10 +29,10 @@ function riskFactorsLockNote(lock: PaneLock): Promise<string> {
     does: "it groups a 10-K's risk factors by theme and shows what was added, dropped or reworded since the year before",
     shows: "it",
     free: [{
-      text: (ticker, company) => `gloomberb filings ${ticker} --form 10-K lists ${company}'s annual reports, each with its filing date and a link to the filing, whose Item 1A holds the risk factors as written.`,
+      text: (ticker, company) => `gloom filings ${ticker} --form 10-K lists ${company}'s annual reports, each with its filing date and a link to the filing, whose Item 1A holds the risk factors as written.`,
       answers: (symbol, context) => filesForm(symbol, "10-K", context),
     }, {
-      text: (ticker, company) => `gloomberb filings ${ticker} --form 20-F lists ${company}'s annual reports, each with its filing date and a link to the filing, whose Item 3.D holds the risk factors as written.`,
+      text: (ticker, company) => `gloom filings ${ticker} --form 20-F lists ${company}'s annual reports, each with its filing date and a link to the filing, whose Item 3.D holds the risk factors as written.`,
       answers: (symbol, context) => filesForm(symbol, "20-F", context),
     }],
   });

package/src/plugins/builtin/scanner/lock-note.ts

@@ -13,6 +13,6 @@ export function flowLockNote(lock: PaneLock): Promise<string> {
     argument: "none",
     does: "it streams real-time sweeps, blocks and large premium prints across US options exchanges",
     shows: "it",
-    free: [{ text: (ticker, company) => `gloomberb options ${ticker} lists ${company}'s option chain, each contract with its volume and open interest.` }],
+    free: [{ text: (ticker, company) => `gloom options ${ticker} lists ${company}'s option chain, each contract with its volume and open interest.` }],
   });
 }

package/src/plugins/builtin/sec/forms.ts

@@ -49,6 +49,19 @@ export function filterFilingsByForms(filings: readonly SecFilingItem[], forms: r
   });
 }
 
+/**
+ * A fund's own filings out of its trust's (ProShares Trust files for 166
+ * funds): the ones the service marks as filed for the fund's series. A list
+ * the service could not mark, a fund whose registrant runs no other series,
+ * or a list in which nothing is marked as the fund's own (a series list that
+ * came back empty) stays whole.
+ */
+export function fundSeriesFilings(filings: readonly SecFilingItem[]): readonly SecFilingItem[] {
+  return filings.some((filing) => filing.fundSeries === true)
+    ? filings.filter((filing) => filing.fundSeries === true)
+    : filings;
+}
+
 /** A form as typed or filed, without punctuation or the `SC`/`SCHEDULE` prefix of ownership schedules. */
 function compactFilingForm(form: string): string {
   return form.toUpperCase().replace(/[^A-Z0-9]/g, "").replace(/^(?:SCHEDULE|SC)(?=\d)/, "");

package/src/plugins/builtin/sec/fund-abroad.ts

@@ -0,0 +1,32 @@
+import { listingSuffixExchange } from "../../../sources/listing-symbols";
+import type { TickerFinancials } from "../../../types/financials";
+import { parsePublicTickerKey } from "../../../utils/exchanges";
+import { safeExternalUrl } from "../../../utils/external-url";
+import { listingAbroadVenue } from "../../../utils/sec";
+
+/** A fund listed abroad as its profile names it: its name, its page at its issuer, and where its description is from. */
+export interface FundAbroadProfile {
+  name?: string;
+  page?: string;
+  descriptionSource?: { publisher: string; url: string };
+}
+
+/** The venue abroad a listing names, by its key (3042:HKEX) or its symbol's suffix (3042.HK, VUSA.L); null for a US listing. */
+export function venueAbroad(key: string): string | null {
+  const keyed = listingAbroadVenue(key);
+  if (keyed) return keyed;
+  const { symbol, exchange } = parsePublicTickerKey(key);
+  const suffixed = exchange ? undefined : listingSuffixExchange(symbol);
+  return suffixed ? listingAbroadVenue(`${symbol}:${suffixed}`) : null;
+}
+
+/** What ETF says of a fund listed abroad, from its quote and profile; only links that are safe to open. */
+export function fundAbroadProfile(financials: Pick<TickerFinancials, "quote" | "profile"> | null | undefined): FundAbroadProfile {
+  const page = financials?.profile?.website ? safeExternalUrl(financials.profile.website) : null;
+  const source = financials?.profile?.descriptionSource;
+  return {
+    ...(financials?.quote?.name ? { name: financials.quote.name } : {}),
+    ...(page ? { page } : {}),
+    ...(source?.publisher && safeExternalUrl(source.url) ? { descriptionSource: source } : {}),
+  };
+}

package/src/plugins/builtin/sec/fund-facts.ts

@@ -1,6 +1,7 @@
 import { apiClient } from "../../../api-client";
-import type { FundFactsPayload } from "../../../api-client/fund-facts";
+import type { FundFactsPayload, FundLeverage, FundMetalHoldings } from "../../../api-client/fund-facts";
 import type { StatItem } from "../../../components/ui/stat-grid";
+import { leverageFactorLabel } from "../../../time-series/leverage";
 import { t, tf } from "../../../i18n";
 import { createPluginCache } from "../../../data/plugin-cache";
 import type { HeadlessPaneEntry } from "../../../types/plugin";
@@ -17,11 +18,22 @@ export const fundFactsCache = createPluginCache<FundFactsPayload>({
 type Client = Pick<typeof apiClient, "getFundFacts">;
 
 const fact = (value: unknown) => value === null || (typeof value === "object" && value !== null && "value" in value && "source" in value);
+const finite = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value);
+
+function isMetalHoldingsShape(value: FundFactsPayload["metalHoldings"]): boolean {
+  return value == null || ((value.metal === "gold" || value.metal === "silver") && typeof value.asOf === "string" && finite(value.ounces)
+    && (value.tonnes === null || finite(value.tonnes)) && typeof value.source?.publisher === "string"
+    && (value.change === null || (typeof value.change?.since === "string" && finite(value.change.ounces))));
+}
+
+/** Absent from servers before it; otherwise a dated factor with its reset period. */
+const leverageShape = (value: FundFactsPayload["leverage"]) => value === undefined || value === null
+  || (fact(value) && typeof value.value === "number" && Number.isFinite(value.value) && (value.reset === "daily" || value.reset === "monthly"));
 
 function validateFundFacts(data: FundFactsPayload): FundFactsPayload {
   if (!data || typeof data.ticker !== "string" || typeof data.covered !== "boolean"
     || ![data.expenseRatio, data.nav, data.premiumDiscount, data.netAssets, data.sponsor, data.inception, data.index].every(fact)
-    || !isBondFactsShape(data.bond)) {
+    || !isBondFactsShape(data.bond) || !leverageShape(data.leverage) || !isMetalHoldingsShape(data.metalHoldings)) {
     throw new Error("Unreadable fund facts response");
   }
   return data;
@@ -41,13 +53,14 @@ export function fundFactsErrorLine(error: unknown): string {
   return message === FUND_FACTS_UNAVAILABLE ? t(FUND_FACTS_UNAVAILABLE) : tf("Fund facts unavailable: {message}", { message });
 }
 
-export async function fetchFundFacts(ticker: string, client: Client = apiClient): Promise<FundFactsPayload> {
-  try { return validateFundFacts(await client.getFundFacts(ticker)); } catch (error) { throw unavailableOnServer(error, FUND_FACTS_UNAVAILABLE); }
+export async function fetchFundFacts(ticker: string, client: Client = apiClient, signal?: AbortSignal): Promise<FundFactsPayload> {
+  try { return validateFundFacts(await (signal ? client.getFundFacts(ticker, { signal }) : client.getFundFacts(ticker))); } catch (error) { throw unavailableOnServer(error, FUND_FACTS_UNAVAILABLE); }
 }
 const cacheKey = (ticker: string) => ticker.trim().toUpperCase();
 export const cachedFundFacts = (ticker: string) => cachedCloudResource(fundFactsCache, cacheKey(ticker), validateFundFacts);
-export const loadFundFacts = (ticker: string, force = false) =>
-  loadCloudResource(fundFactsCache, cacheKey(ticker), () => fetchFundFacts(ticker), { force, validate: validateFundFacts });
+/** Through the cache the ETF pane keeps; `client` is a report's own, `signal` ends a read it no longer waits for. */
+export const loadFundFacts = (ticker: string, force = false, { client = apiClient, signal }: { client?: Client; signal?: AbortSignal } = {}) =>
+  loadCloudResource(fundFactsCache, cacheKey(ticker), () => fetchFundFacts(ticker, client, signal), { force, validate: validateFundFacts, signal });
 
 /** A fee as the prospectus states it: two decimals at least, four when it has them (0.0945%). */
 function formatFeePercent(value: number): string {
@@ -67,6 +80,13 @@ function formatNetAssets(value: number): string {
   return `$${formatCompact(value)}`;
 }
 
+/** Ounces and tonnes as the sponsor publishes them, to its own decimals (34,085,936.5; 1,060.18). */
+const metalFigure = (value: number, signed = false) =>
+  `${signed && value > 0 ? "+" : ""}${value.toLocaleString("en-US", { maximumFractionDigits: 3 })}`;
+
+/** "Gold in trust", "Silver in trust". */
+const metalLabel = (holdings: FundMetalHoldings) => holdings.metal === "gold" ? "Gold in trust" : "Silver in trust";
+
 /**
  * The fee as the server says it is: a sponsor fee (IBIT, GLD), or an expense
  * ratio, net or gross of waivers, which its detail says. A pool's total
@@ -98,6 +118,17 @@ function wholeFund(facts: FundFactsPayload): boolean {
  */
 const BENCHMARK_LABEL = "Benchmark";
 
+/**
+ * A leveraged or inverse fund's objective, as the ETF pane and report label
+ * it: the times and direction of its benchmark's return it seeks.
+ */
+const OBJECTIVE_LABEL = "Objective";
+
+/** The objective in a few words: `3× daily, long`, `-3× daily, inverse`, `1.75× monthly, long`. */
+function leverageObjectiveText(leverage: Pick<FundLeverage, "value" | "reset">): string {
+  return `${leverageFactorLabel(leverage.value)} ${leverage.reset}, ${leverage.value < 0 ? "inverse" : "long"}`;
+}
+
 /**
  * How each dated figure reads beside the NAV, the date the sheet is about.
  * Every figure says its own date. One that is older than it looks is marked:
@@ -169,8 +200,24 @@ export function fundFactItems(facts: FundFactsPayload): StatItem[] {
   for (const figure of facts.bond ? bondFigures(facts.bond) : []) {
     items.push(cell(figure.key, figure.label, figure.text, { detail: figure.date, marked: facts.stale }));
   }
+  // A metal trust's metal in trust, in tonnes as the market quotes it and ounces as the trust counts it, then its day's change.
+  const metal = facts.metalHoldings;
+  if (metal) {
+    const ounces = `${formatCompact(metal.ounces)} oz`;
+    items.push(cell("metal", metalLabel(metal), metal.tonnes == null ? ounces : `${metalFigure(metal.tonnes)} t`,
+      { detail: metal.tonnes == null ? metal.asOf : `${ounces} · ${metal.asOf}`, marked: metal.stale }));
+    if (metal.change) {
+      const change = `${metalFigure(Math.round(metal.change.ounces), true)} oz`;
+      items.push(cell("metal-change", "Day change", metal.change.tonnes == null ? change : `${metalFigure(metal.change.tonnes, true)} t`,
+        { detail: metal.change.tonnes == null ? tf("since {date}", { date: metal.change.since }) : `${change} · ${tf("since {date}", { date: metal.change.since })}`, marked: metal.stale }));
+    }
+  }
   if (facts.sponsor) items.push({ id: "sponsor", label: "Sponsor", value: facts.sponsor.value });
   if (facts.inception) items.push({ id: "inception", label: "Inception", value: facts.inception.value });
+  // A leveraged or inverse fund's objective, dated by the sponsor page it was read from, beside its benchmark.
+  if (facts.leverage) {
+    items.push(cell("objective", OBJECTIVE_LABEL, leverageObjectiveText(facts.leverage), { detail: facts.leverage.asOf ?? undefined, marked: false }));
+  }
   if (facts.index) items.push({ id: "index", label: BENCHMARK_LABEL, value: facts.index.value, wide: true });
   return items;
 }
@@ -251,6 +298,15 @@ export function fundFactEntries(facts: FundFactsPayload): HeadlessPaneEntry[] {
       ? `${facts.netAssets.asOf} month-end${facts.netAssets.document ? ` ${facts.netAssets.document}` : ""}` : facts.netAssets.asOf;
     add("netAssets", "Net assets", facts.netAssets.value, provenance(formatNetAssets(facts.netAssets.value), date, scope, facts.netAssets.source), "USD");
   }
+  const metal = facts.metalHoldings;
+  if (metal) {
+    // The trust's own figures, as its sponsor's daily holdings file states them; JSON has the tonnes in `fundFacts`.
+    add("metalOunces", metalLabel(metal), metal.ounces, provenance(`${metalFigure(metal.ounces)} troy oz`,
+      metal.tonnes == null ? null : `${metalFigure(metal.tonnes)} tonnes`, metal.stale ? `${metal.asOf} stale` : metal.asOf, metal.source.publisher), "troy oz");
+    add("metalChangeOunces", "Day change", metal.change?.ounces ?? null, metal.change
+      ? provenance(`${metalFigure(metal.change.ounces, true)} troy oz`, metal.change.tonnes == null ? null : `${metalFigure(metal.change.tonnes, true)} tonnes`, `since ${metal.change.since}`)
+      : `-- · ${metal.asOf} is the first day stored`, "troy oz");
+  }
   if (facts.bond) {
     add("bondClass", "Bond fund", facts.bond.kind, bondClassText(facts.bond));
     const keys = { secYield: "secYieldPercent", yieldToWorst: "yieldToWorstPercent", duration: "durationYears" } as const;
@@ -261,6 +317,10 @@ export function fundFactEntries(facts: FundFactsPayload): HeadlessPaneEntry[] {
   }
   if (facts.sponsor) add("sponsor", "Sponsor", facts.sponsor.value, facts.sponsor.value);
   if (facts.inception) add("inception", "Inception", facts.inception.value, facts.inception.value);
+  if (facts.leverage) {
+    add("leverageFactor", OBJECTIVE_LABEL, facts.leverage.value,
+      provenance(leverageObjectiveText(facts.leverage), facts.leverage.asOf, facts.leverage.source), "x");
+  }
   if (facts.index) add("index", BENCHMARK_LABEL, facts.index.value, provenance(facts.index.value, facts.index.source));
   const url = facts.nav?.url ?? facts.expenseRatio?.url ?? facts.netAssets?.url;
   if (url) add("url", "Sponsor page", url, url);
@@ -278,8 +338,8 @@ export function listNames(names: readonly string[]): string {
  * the consolidated close cites Gloom Cloud on its own line, not here.
  */
 export function fundFactPublishers(facts: FundFactsPayload): string[] {
-  return [...new Set([facts.nav, facts.expenseRatio, facts.netAssets, facts.index, facts.bond?.secYield, facts.bond?.yieldToWorst, facts.bond?.duration]
-    .flatMap((value) => value ? [value.source] : []))];
+  return [...new Set([...[facts.nav, facts.expenseRatio, facts.netAssets, facts.leverage, facts.index, facts.bond?.secYield, facts.bond?.yieldToWorst, facts.bond?.duration]
+    .flatMap((value) => value ? [value.source] : []), ...facts.metalHoldings ? [facts.metalHoldings.source.publisher] : []])];
 }
 
 /** The newest NAV is stale: one line saying since when, as the report's note says it. */