@gloom-sh/terminal 0.18.5 → 0.19.1

package/src/plugins/builtin/seasonality/headless.ts

@@ -1,6 +1,7 @@
 import type { HeadlessPaneDefinition } from "../../../types/plugin";
 import { resolveHeadlessInstrument } from "../shared/headless-market-data";
 import { loadSeasonalityHistory } from "./client";
+import { closedHistoryBarDay, formingHistoryBar } from "../ticker-detail/data-panes/history-bars";
 import { MONTH_LABELS, projectSeasonality, projectWeekdays, TURN_OF_MONTH_LABELS } from "./model";
 
 const percent = (digits: number) => (value: unknown) => typeof value === "number" ? `${(value * 100).toFixed(digits)}%` : "--";
@@ -9,7 +10,7 @@ const statColumns = (digits: number, countHeader: string) => [{ key: "mean", hea
 
 export const seasonalityHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle", argument: { kind: "ticker", description: "Ticker" },
-  // Dated by the month of its last monthly close.
+  // Dated by its last monthly close, or by how far the running month's bar runs (`month to date, through Fri 23 Oct 2026`).
   freshness: { status: "not-a-feed", basis: "monthly closes", maxAgeMinutes: 45 * 24 * 60 },
   describe: (args) => `SEAS ${args.symbols[0] ?? ""}`,
   discovery: { screenshotReadiness: "live-dom", limitations: ["Local-price closes; dividends and FX are excluded.",
@@ -46,6 +47,13 @@ export const seasonalityHeadless: HeadlessPaneDefinition<"bundle"> = {
       };
     }
     const model = projectSeasonality(history.history, { symbol: instrument.symbol, lookbackYears: Number(args.options.lookbackYears) || 10 });
+    // Monthly bars are dated by their month's first day, which is no close while the month runs.
+    const bar = model.asOf?.toISOString().slice(0, 10);
+    // The venue whose sessions say whether the month still runs: the key's, or for a bare symbol its quote's.
+    const quote = bar && !instrument.exchange ? await ctx.marketData.getQuote(instrument.symbol, "").catch(() => null) : null;
+    const venue = instrument.exchange || quote?.listingExchangeName || quote?.exchangeName || undefined;
+    const forming = formingHistoryBar("1mo", bar, venue, Date.now());
+    const closed = forming ? null : closedHistoryBarDay("1mo", bar, venue, Date.now());
     const monthColumns = MONTH_LABELS.map((label, month) => ({ key: `m${month}`, header: label, format: percent(1) }));
     return {
       sections: [
@@ -57,6 +65,7 @@ export const seasonalityHeadless: HeadlessPaneDefinition<"bundle"> = {
       complete: !history.stale && !history.error && model.years.length > 0,
       unavailableSymbols: model.years.length ? [] : [instrument.symbol],
       ...common,
+      ...(forming ? { freshness: { periodToDate: forming } } : closed ? { freshness: { asOf: closed } } : {}),
       metadata: { unit: "decimal return, local-price close to close", asOf: model.asOf?.toISOString() ?? null, stale: history.stale,
         fetchedAt: history.fetchedAt, averagePath: model.averagePath, methodology: "docs/research-data.md#seasonality" },
     };

package/src/plugins/builtin/sec/fund-facts-view.tsx

@@ -4,7 +4,7 @@ import { useAsyncResource } from "../../../react/async-resource";
 import { Box } from "../../../ui";
 import { t } from "../../../i18n";
 import type { FundFactsPayload } from "../../../api-client/fund-facts";
-import { cachedFundFacts, fundFactItems, fundFactsEmptyText, fundFactsErrorLine, fundFactsStaleText, loadFundFacts } from "./fund-facts";
+import { cachedFundFacts, fundFactItems, fundFactsEmptyText, fundFactsErrorLine, fundFactsNavReasonText, fundFactsStaleText, loadFundFacts } from "./fund-facts";
 import type { CloudResource } from "../shared/cloud-resource";
 
 /** A fund's facts, served from the cache first and refreshed behind it; null asks for nothing. */
@@ -18,7 +18,8 @@ export function useFundFacts(symbol: string | null | undefined) {
 /**
  * The fund's facts as the summary sheet over its filings, or one line saying
  * why there are none. Loading is one muted line, so the filings never wait.
- * A stale NAV adds the line saying since when, under the marked figures.
+ * A stale NAV adds the line saying since when, under the marked figures; a
+ * fund without a NAV, the line saying why.
  */
 export function FundFactsSummary({ symbol, width, facts, loading, error }: {
   symbol: string;
@@ -29,10 +30,12 @@ export function FundFactsSummary({ symbol, width, facts, loading, error }: {
 }) {
   if (facts?.covered) {
     const stale = fundFactsStaleText(symbol, facts);
+    const noNav = fundFactsNavReasonText(symbol, facts);
     return (
       <>
         <StatGrid width={width} items={fundFactItems(facts)} />
         {stale ? <FundViewNotice lines={[stale]} tone="warning" /> : null}
+        {noNav ? <FundViewNotice lines={[noNav]} /> : null}
       </>
     );
   }

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

@@ -1,5 +1,5 @@
 import { apiClient } from "../../../api-client";
-import type { FundFactsPayload, FundLeverage, FundMetalHoldings } from "../../../api-client/fund-facts";
+import type { FundFactsPayload, FundLeverage, FundMetalHoldings, FundStructure } from "../../../api-client/fund-facts";
 import type { StatItem } from "../../../components/ui/stat-grid";
 import { leverageFactorLabel } from "../../../time-series/leverage";
 import { t, tf } from "../../../i18n";
@@ -7,7 +7,8 @@ import { createPluginCache } from "../../../data/plugin-cache";
 import type { HeadlessPaneEntry } from "../../../types/plugin";
 import { errorMessage } from "../../../utils/errors";
 import { formatCompact } from "../../../utils/format";
-import { bondClassText, bondFigures, isBondFactsShape } from "../../../market-data/bond-funds";
+import { bondClassText, bondFigures } from "../../../market-data/bond-funds";
+import { readFundFacts, validateFundFacts } from "../../../market-data/fund-facts";
 import { cachedCloudResource, loadCloudResource, unavailableOnServer } from "../shared/cloud-resource";
 
 /** Sponsors publish once a day, in the US evening; a copy younger than this is not asked for again. */
@@ -17,28 +18,6 @@ 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) || !leverageShape(data.leverage) || !isMetalHoldingsShape(data.metalHoldings)) {
-    throw new Error("Unreadable fund facts response");
-  }
-  return data;
-}
-
 export const FUND_FACTS_UNAVAILABLE = "Fund facts are not available on this server yet.";
 
 /** A failed load as one line: the server-not-ready message as it is, anything else after "Fund facts unavailable:". */
@@ -54,7 +33,7 @@ export function fundFactsErrorLine(error: unknown): string {
 }
 
 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); }
+  try { return await readFundFacts(ticker, client, signal); } 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);
@@ -80,6 +59,40 @@ function formatNetAssets(value: number): string {
   return `$${formatCompact(value)}`;
 }
 
+/** A NAV the sponsor published as a range: `$4.12 to $4.22`. */
+const estimateRange = (estimate: { low: number; high: number }) => `${formatNav(estimate.low)} to ${formatNav(estimate.high)}`;
+
+/** Shares created less redeemed, signed: `+12.35M`, `-3.1M`. */
+const signedCompact = (value: number) => `${value > 0 ? "+" : value < 0 ? "-" : ""}${formatCompact(Math.abs(value))}`;
+
+/** A month's flows in dollars, when every day had a NAV to value them at. */
+const flowsValue = (value: number) => `${value < 0 ? "-" : value > 0 ? "+" : ""}$${formatCompact(Math.abs(value))}`;
+
+/** A closed-end fund's NAV is a month end's (a sponsor's estimate, or the filing's period end): its normal cadence, not a lag. */
+const monthEndNav = (facts: FundFactsPayload) => facts.nav?.period === "month-end";
+
+/** The session of the close a premium was computed from, when it is before the NAV's date: a month end on a weekend. */
+const closeSession = (facts: FundFactsPayload) => {
+  const close = facts.closingPrice?.asOf;
+  const premium = facts.premiumDiscount?.asOf;
+  return close && premium && close < premium ? close : null;
+};
+
+/** A registered closed-end fund or a BDC: its NAV is a month end's or a filing's, and its price trades at its own premium to it. */
+const closedEnd = (structure: FundFactsPayload["structure"]) => structure === "closed-end" || structure === "bdc";
+
+/** Each structure by its own name in a report; one a newer server adds, by its own key rather than another's name. */
+const STRUCTURE_LABELS: Record<FundStructure, string> = {
+  registered: "Registered fund",
+  trust: "Trust or pool, not an open-end fund",
+  "closed-end": "Closed-end fund",
+  bdc: "Business development company (BDC)",
+};
+const structureLabel = (structure: FundStructure) => STRUCTURE_LABELS[structure] ?? String(structure);
+
+/** The pane's shorter names, for the funds whose figures read unlike an ETF's. */
+const PANE_STRUCTURE: Partial<Record<FundStructure, string>> = { "closed-end": "Closed-end fund", bdc: "BDC" };
+
 /** 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 })}`;
@@ -156,9 +169,19 @@ function datedFigures(facts: FundFactsPayload): Record<"nav" | "premium" | "fee"
   const prospectus = facts.expenseRatio?.document === "prospectus";
   const nport = assets?.document === "N-PORT";
   return {
-    nav: { detail: nav ? (facts.stale ? tf("{date} stale", { date: nav }) : nav) : undefined, marked: facts.stale },
+    nav: {
+      detail: nav
+        ? facts.stale ? tf("{date} stale", { date: nav }) : monthEndNav(facts) ? tf("{date} month-end", { date: nav }) : nav
+        : undefined,
+      marked: facts.stale,
+    },
     premium: {
-      detail: premium?.asOf ? (premium.basis === "computed" ? tf("{date} close", { date: premium.asOf }) : premium.asOf) : undefined,
+      // A computed premium is dated by its close's session (a weekend month end's Friday), and says when it is an estimate's.
+      detail: premium?.asOf
+        ? premium.basis === "computed"
+          ? `${tf("{date} close", { date: closeSession(facts) ?? premium.asOf })}${premium.estimate ? ` · ${t("est.")}` : ""}`
+          : premium.asOf
+        : undefined,
       marked: facts.stale || (!!premium?.asOf && !!nav && premium.asOf !== nav),
     },
     fee: {
@@ -192,10 +215,29 @@ export function fundFactItems(facts: FundFactsPayload): StatItem[] {
   const cell = (id: string, label: string, value: string, figure: DatedFigure): StatItem => ({
     id, label, value, ...(figure.detail ? { detail: figure.detail } : {}), ...(figure.marked ? { tone: "warning" as const } : {}),
   });
-  if (facts.nav) items.push(cell("nav", "NAV", formatNav(facts.nav.value), dated.nav));
+  if (facts.nav) {
+    // A sponsor's estimate is a range: its midpoint is the figure, the range follows its date.
+    const estimate = facts.nav.estimate;
+    const nav = estimate && dated.nav.detail
+      ? { ...dated.nav, detail: `${dated.nav.detail} · ${tf("est. {range}", { range: estimateRange(estimate) })}` } : dated.nav;
+    items.push(cell("nav", "NAV", formatNav(facts.nav.value), nav));
+  }
   if (facts.premiumDiscount) items.push(cell("premium", "Premium/discount", formatPremiumPercent(facts.premiumDiscount.value), dated.premium));
   if (facts.expenseRatio) items.push(cell("fee", expenseRatioLabel(facts), formatFeePercent(facts.expenseRatio.value), dated.fee));
   if (facts.netAssets) items.push(cell("assets", wholeFund(facts) ? "Fund net assets" : "Net assets", formatNetAssets(facts.netAssets.value), dated.netAssets));
+  // Shares outstanding as the sponsor states them, then the month's creations less redemptions.
+  if (facts.sharesOutstanding) {
+    items.push(cell("shares", "Shares outstanding", formatCompact(facts.sharesOutstanding.value),
+      { detail: facts.sharesOutstanding.asOf ?? undefined, marked: facts.stale }));
+  }
+  if (facts.flows) {
+    // In dollars with the shares beside them; in shares alone when a day had no NAV to value them at.
+    const flows = facts.flows;
+    const shares = tf("{count} shares", { count: signedCompact(flows.shares) });
+    const since = tf("since {date}", { date: flows.from });
+    items.push(cell("flows", "1M flows", flows.value === null ? shares : flowsValue(flows.value),
+      { detail: flows.value === null ? since : `${shares} · ${since}`, marked: facts.stale }));
+  }
   // A bond fund's yields and duration, each dated by its sponsor.
   for (const figure of facts.bond ? bondFigures(facts.bond) : []) {
     items.push(cell(figure.key, figure.label, figure.text, { detail: figure.date, marked: facts.stale }));
@@ -212,6 +254,9 @@ export function fundFactItems(facts: FundFactsPayload): StatItem[] {
         { detail: metal.change.tonnes == null ? tf("since {date}", { date: metal.change.since }) : `${change} · ${tf("since {date}", { date: metal.change.since })}`, marked: metal.stale }));
     }
   }
+  // A closed-end fund or BDC says which: its figures read unlike an ETF's.
+  const structure = facts.structure ? PANE_STRUCTURE[facts.structure] : undefined;
+  if (structure) items.push({ id: "structure", label: "Structure", value: t(structure) });
   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.
@@ -276,19 +321,23 @@ export function fundFactEntries(facts: FundFactsPayload): HeadlessPaneEntry[] {
   const add = (key: string, label: string, value: unknown, formatted: string, unit?: string) =>
     entries.push({ key, label, value, formatted, ...(unit ? { unit } : {}) });
   if (facts.name) add("name", "Name", facts.name, facts.name);
-  if (facts.structure) add("structure", "Structure", facts.structure,
-    facts.structure === "trust" ? "Trust or pool, not an open-end fund" : "Registered fund");
+  if (facts.structure) add("structure", "Structure", facts.structure, structureLabel(facts.structure));
   if (facts.expenseRatio) {
     const kind = feeBasis(facts);
     const date = facts.expenseRatio.asOf && facts.expenseRatio.document === "prospectus" ? `${facts.expenseRatio.asOf} prospectus` : facts.expenseRatio.asOf;
     add("expenseRatioPercent", expenseRatioLabel(facts), facts.expenseRatio.value,
       provenance(`${formatFeePercent(facts.expenseRatio.value)}${kind ? ` ${kind}` : ""}`, date, facts.expenseRatio.source), "%");
   }
-  if (facts.nav) add("nav", "NAV", facts.nav.value, provenance(formatNav(facts.nav.value), facts.nav.asOf, facts.nav.source), "USD");
+  if (facts.nav) {
+    const date = facts.nav.asOf && monthEndNav(facts) ? `${facts.nav.asOf} month-end` : facts.nav.asOf;
+    const estimate = facts.nav.estimate ? `estimate ${estimateRange(facts.nav.estimate)}` : null;
+    add("nav", "NAV", facts.nav.value, provenance(formatNav(facts.nav.value), date, estimate, facts.nav.source), "USD");
+  }
   if (facts.closingPrice) add("closingPrice", "Closing price", facts.closingPrice.value,
     provenance(formatNav(facts.closingPrice.value), facts.closingPrice.asOf, facts.closingPrice.source), "USD");
   if (facts.premiumDiscount) {
-    const basis = facts.premiumDiscount.basis === "computed" ? "closing price vs NAV" : null;
+    const basis = facts.premiumDiscount.basis !== "computed" ? null
+      : facts.premiumDiscount.estimate ? "closing price vs NAV estimate midpoint" : "closing price vs NAV";
     add("premiumDiscountPercent", "Premium/discount", facts.premiumDiscount.value,
       provenance(formatPremiumPercent(facts.premiumDiscount.value), facts.premiumDiscount.asOf, basis, facts.premiumDiscount.source), "%");
   }
@@ -298,6 +347,16 @@ 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");
   }
+  if (facts.sharesOutstanding) {
+    add("sharesOutstanding", "Shares outstanding", facts.sharesOutstanding.value,
+      provenance(facts.sharesOutstanding.value.toLocaleString("en-US"), facts.sharesOutstanding.asOf, facts.sharesOutstanding.source), "shares");
+  }
+  if (facts.flows) {
+    // JSON keeps the dollar figure (null when a day had no NAV); `fundFacts.flows` has the shares.
+    const flows = facts.flows;
+    add("flows1M", "1M flows", flows.value, provenance(flows.value === null ? null : flowsValue(flows.value),
+      `${signedCompact(flows.shares)} shares`, `${flows.from} to ${flows.asOf}`, flows.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`.
@@ -323,7 +382,8 @@ export function fundFactEntries(facts: FundFactsPayload): HeadlessPaneEntry[] {
   }
   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);
+  // The figures' own page: the sponsor's, or the SEC filing they were read from (a prospectus, an N-PORT, an 8-K).
+  if (url) add("url", /^https:\/\/www\.sec\.gov\//.test(url) ? "SEC filing" : "Sponsor page", url, url);
   return entries;
 }
 
@@ -338,7 +398,7 @@ 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.leverage, facts.index, facts.bond?.secYield, facts.bond?.yieldToWorst, facts.bond?.duration]
+  return [...new Set([...[facts.nav, facts.expenseRatio, facts.netAssets, facts.sharesOutstanding, facts.flows, facts.leverage, facts.index, facts.bond?.secYield, facts.bond?.yieldToWorst, facts.bond?.duration]
     .flatMap((value) => value ? [value.source] : []), ...facts.metalHoldings ? [facts.metalHoldings.source.publisher] : []])];
 }
 
@@ -352,6 +412,25 @@ export function fundFactsStaleText(symbol: string, facts: FundFactsPayload): str
   return fundFactsStaleNote(symbol, facts) ? tf("{symbol}'s newest NAV is from {date}; its sponsor has not published one since.", { symbol, date: facts.nav!.asOf! }) : null;
 }
 
+/**
+ * Why a covered fund has no NAV, in one line, translated for the pane: what
+ * Gloom reads for it and what that leaves out, as the server's `navReason`
+ * says it. Null when it has a NAV, and from servers before the reason.
+ */
+export function fundFactsNavReasonText(symbol: string, facts: FundFactsPayload): string | null {
+  if (!facts.covered || facts.nav || !facts.navReason) return null;
+  // A sponsor that publishes the fund's other figures.
+  const sponsor = fundFactPublishers(facts).find((publisher) => publisher !== "SEC EDGAR");
+  if (sponsor) return tf("No NAV for {symbol}: {publisher} publishes figures for it, but no NAV.", { symbol, publisher: sponsor });
+  if (closedEnd(facts.structure)) {
+    return tf("No NAV for {symbol}: its SEC filings state net assets but no NAV per share, and its sponsor's NAV is not one Gloom reads.", { symbol });
+  }
+  if (facts.structure === "trust") {
+    return tf("No NAV for {symbol}: its sponsor's site is not one Gloom reads, and a trust files no NAV with the SEC's fund data sets.", { symbol });
+  }
+  return tf("No NAV for {symbol}: its sponsor's site is not one Gloom reads, and the SEC's prospectus and N-PORT data sets state no NAV.", { symbol });
+}
+
 /**
  * Why a fund has no facts, in one line, and where to look instead: its SEC
  * filings, unless the caller already points there.
@@ -376,6 +455,9 @@ export function fundFactsEmptyText(symbol: string, facts: FundFactsPayload | nul
     if (facts.structure === "registered") {
       return tf("No figures for {symbol}: its sponsor's site is not one Gloom reads, and the SEC's prospectus and N-PORT data sets list none for it yet.", { symbol });
     }
+    if (closedEnd(facts.structure)) {
+      return tf("No figures for {symbol}: it files with the SEC as a closed-end fund or BDC, but neither the filings Gloom reads nor its sponsor's site state any for it yet.", { symbol });
+    }
     return tf("No figures for {symbol}: it lists as a fund, but the SEC's lists do not name it yet and its sponsor's site is not one Gloom reads.", { symbol });
   }
   if (facts.status === "not-a-fund") return tf("No fund facts for {symbol}: it is not on the SEC's lists of US-listed funds.", { symbol });

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

@@ -20,6 +20,7 @@ import { fetchFundFacts, fundFactEntries, fundFactPublishers, fundFactsEmpty, fu
 import { REPORT_ROWS } from "../shared/headless-options";
 import { fundAbroadProfile, venueAbroad, type FundAbroadProfile } from "./fund-abroad";
 import { listingAnnouncementsPage } from "../../../utils/exchange-announcements";
+import { companyDataNotes } from "../../../types/company-from";
 
 const SEC_COLUMNS: HeadlessPaneColumn[] = [
   {
@@ -140,7 +141,7 @@ export function createSecHeadless(dependencies: SecHeadlessDependencies = defaul
       return {
         rows,
         textColumns: secTextColumns(rows),
-        ...(note ? { notes: [note] } : {}),
+        ...(note || filings[0]?.companyFrom ? { notes: [...(note ? [note] : []), ...companyDataNotes(filings[0]?.companyFrom)] } : {}),
         ...(form ? { empty: `No ${form} filings found for ${symbol}.` }
           : page ? { empty: `${symbol} files no SEC reports. ${page.name}: ${page.url}` } : {}),
         metadata: {
@@ -268,7 +269,8 @@ export function createFundHeadless(dependencies: FundHeadlessDependencies = defa
           ...(factsResult.status === "rejected" ? [fundFactsErrorText(factsResult.reason)] : []),
           ...(filingsResult.status === "rejected" ? [`Fund filings: ${errorMessage(filingsResult.reason)}`] : []),
         ],
-        notes: facts ? [fundFactsStaleNote(symbol, facts)].filter((note): note is string => !!note) : [],
+        // A stale NAV says since when; a covered fund without one says why, as the server words it.
+        notes: facts ? [fundFactsStaleNote(symbol, facts), facts.covered && !facts.nav ? facts.navReason : null].filter((note): note is string => !!note) : [],
         // The facts' publisher is the source, named the same way for every fund; without facts it is the SEC.
         freshness: {
           source: listNames(publishers) || "SEC EDGAR",

package/src/plugins/builtin/sec/index.tsx

@@ -12,6 +12,7 @@ import { Box, Text, useUiCapabilities, type ScrollBoxRenderable } from "../../..
 import { FILL_REST } from "../../../components/ui/fill";
 import { t, tf } from "../../../i18n";
 import { EmptyState, ExternalLinkText, FeedDataTableStackView, PaneLinkMenu, QueryBar, Spinner, TickerBadgeList, usePaneNoticeFooter, useTableLoadMore, type FeedDataTableItem, type PaneHint, type QueryBarFilter } from "../../../components";
+import { useCompanyDataFooter } from "../../../components/layout/pane/status-footer";
 import { displayWidth } from "../../../utils/format";
 import type { DetailFact } from "../../../components/reader/detail-reader";
 import type { ThemeColors } from "../../../theme/colors";
@@ -466,6 +467,8 @@ function SecView({ width, height, focused, paneType }: { width: number; height:
     showOpenHint: !!(openFiling ? openFiling.filingUrl : factsUrl ?? abroadPage ?? announcements),
   });
 
+  // A foreign line's filings are its company's, read from the home line.
+  useCompanyDataFooter(issuerFilings[0]?.companyFrom, !openFiling);
   usePaneNoticeFooter({
     registrationId: "sec:form-filter",
     notices: filterHistoryCapped

package/src/plugins/builtin/series-inventory.ts

@@ -64,9 +64,11 @@ export const SERIES_INVENTORY: readonly SeriesInventoryEntry[] = [
   { module: "perps", chart: "Perpetual funding, open interest, premium and long/short account share", series: ["perps:*"] },
   { module: "crypto-etf-flows", chart: "The running net flow of the US spot bitcoin or ether ETFs since launch", notInCatalog: "not-yet", reason: "Daily and dated: the running total and each fund's daily flow could be crypto ETF series, and none is registered for the composer yet." },
   { module: "perps", chart: "Perpetual mark price", notInCatalog: "not-yet", reason: "The pair's price is in the catalog; the perpetual's own mark price could be a crypto series." },
+  { module: "treasury-daily", chart: "The Treasury General Account's daily closing balance", notInCatalog: "not-yet", reason: "Daily and dated, from the Daily Treasury Statement's operating cash balance table; the pane reads it with the day's cash lines, and none is registered for the composer yet." },
   { module: "primary-dealers", chart: "A primary dealer position's weekly net level, the sum of the release's series behind the row", notInCatalog: "not-yet", reason: "Weekly and dated, one series per row of the board; the pane reads each only when its row is selected, and none is registered for the composer yet." },
   { module: "short-interest", chart: "A ticker's short interest and days to cover", series: ["short-interest:*"] },
   { module: "short-volume", chart: "A ticker's daily short volume ratio", series: ["short-volume:*"] },
+  { module: "scanner", chart: "Net options premium through the session, for the market or one ticker (FLOW's Tide)", notInCatalog: "per-item", reason: "One per ticker, filter set and session, summed on request from the recorded option prints." },
   { module: "social-mentions", chart: "A ticker's daily posts", series: ["social-mentions:*"] },
   { module: "jobs", chart: "A company's open job postings", series: ["jobs:*"] },
   { module: "attention", chart: "Research hours on a ticker, hour by hour", series: ["attention:*"] },

package/src/plugins/builtin/shared/cloud-resource.ts

@@ -1,4 +1,5 @@
-import { ApiRequestError, isAccessDenied } from "../../../api-client/errors";
+import { logFailure } from "../../../utils/log-failure";
+import { ApiRequestError, isPermanentClientError } from "../../../api-client/errors";
 import type { PluginCacheResult } from "../../../data/plugin-cache";
 
 interface CloudCache<T> {
@@ -11,6 +12,8 @@ export interface CloudResource<T> {
   payload: T;
   stale: boolean;
   refreshError: string | null;
+  /** When the copy shown was saved, when it is one because its refresh failed. */
+  savedAt?: number;
 }
 
 /**
@@ -26,8 +29,8 @@ export function cachedCloudResource<T>(
   if (!cached) return null;
   try {
     return { payload: validate(cached.data), stale: false, refreshError: null };
-  } catch {
-    return null;
+  } catch (error) {
+    return logFailure("shared.cloud-resource", "Validate cached cloud payload failed", null)(error);
   }
 }
 
@@ -35,8 +38,9 @@ const isAbort = (error: unknown) => !!error && typeof error === "object" && (err
 
 /**
  * Loads through the cache, falling back to the cached copy when a refresh
- * fails. A refused session still throws, so the pane shows its sign-in wall
- * instead of data the account can no longer see.
+ * fails. A refusal asking again will not change still throws: a refused
+ * session, so the pane shows its sign-in wall instead of data the account can
+ * no longer see, and any other permanent client error (an unknown series).
  *
  * Callers of one key share the request in flight, which runs on the first
  * caller's `signal`. When that caller goes away (a tab left while it loads,
@@ -56,8 +60,13 @@ export async function loadCloudResource<T>(
     throw error;
   });
   if (!result || cancelledByOther(result.error)) result = await cache.load(key, fetch, { force });
-  if (isAccessDenied(result.error)) throw result.error;
-  return { payload: validate(result.data), stale: result.stale, refreshError: result.refreshError ?? null };
+  const saved = result.source === "stale-fallback";
+  if (saved && isPermanentClientError(result.error)) throw result.error;
+  // A copy served because its refresh failed is one by where it came from, whatever the failure said (or did not).
+  return {
+    payload: validate(result.data), stale: result.stale, refreshError: result.refreshError ?? null,
+    ...(saved ? { savedAt: result.fetchedAt } : {}),
+  };
 }
 
 /**

package/src/plugins/builtin/shared/cloud-upgrade.ts

@@ -1,3 +1,4 @@
+import { logFailure } from "../../../utils/log-failure";
 import { useCallback, useEffect, useMemo, useRef } from "react";
 import { apiClient } from "../../../api-client";
 import { recordResearchActivity, researchUpgradeUrl } from "../../../api-client/research-activity";
@@ -159,7 +160,7 @@ async function openCheckoutWithHandoff(
     .then(({ url, link }): CheckoutHandoffTarget => ({
       url,
       link: link ?? null,
-      opened: rendererHost.openExternal(url).then((result) => result !== false, () => false),
+      opened: rendererHost.openExternal(url).then((result) => result !== false, logFailure("shared.cloud-upgrade", "Open checkout in the browser failed", false)),
     }));
   void promptCheckoutHandoff(dialog, target);
   await (await target).opened;
@@ -221,10 +222,10 @@ export function useCloudUpgradeAction(placement: string): (options?: unknown) =>
         openCloudUpgradePage("cloud", async () => {
           const url = await apiClient.createBrowserHandoff()
             .then((handoff) => handoff.url)
-            .catch(() => CLOUD_UPGRADE_URL);
+            .catch(logFailure("shared.cloud-upgrade", "Create Cloud page handoff failed", CLOUD_UPGRADE_URL));
           await rendererHost.openExternal(url);
         })
-      )).catch(() => {});
+      )).catch(logFailure("shared.cloud-upgrade", "Open Cloud upgrade page failed"));
     };
     if (
       checkout.sheet === false ||

package/src/plugins/builtin/shared/earnings-calendar.ts

@@ -55,7 +55,7 @@ function calendarDateWins(calendar: EarningsDateStatus | null, other: EarningsDa
 }
 
 /** The calendar's report as a quarter on record takes it. */
-interface CalendarReport {
+export interface CalendarReport {
   date: string;
   timing: "bmo" | "amc" | null;
   dateStatus: EarningsDateStatus | null;
@@ -86,7 +86,11 @@ function consensusIsReports(event: EarningsEvent, dateStatus: EarningsDateStatus
   return periodEnd != null && periodEnd < date;
 }
 
-function calendarReport(event: EarningsEvent, today: string): CalendarReport {
+/**
+ * A calendar event read as its report, as every surface reads it: reported
+ * once out, and with a consensus only when it is that report's.
+ */
+export function calendarReport(event: EarningsEvent, today: string): CalendarReport {
   const date = calendarDay(event);
   const dateStatus = calendarStatus(event, today);
   const ownConsensus = consensusIsReports(event, dateStatus, date);

package/src/plugins/builtin/shared/earnings-report.ts

@@ -54,8 +54,8 @@ export function epsBasisShort(basis: EarningsEpsBasis | null): string {
   return basis === "gaap" ? "GAAP" : basis === "adjusted" ? "adj" : "?";
 }
 
-/** Known bases are named in row details; unknown stays in the structured data and drilldown. */
-const BASIS_TEXT: Record<EpsBasisName, string> = { GAAP: "GAAP", adjusted: "adj", unknown: "" };
+/** A reported row's detail names its basis as ERN's Basis column does, unknown included. */
+const BASIS_TEXT: Record<EpsBasisName, string> = { GAAP: "GAAP", adjusted: "adj", unknown: "unknown" };
 
 type EarningsRecord = CorporateActionsData["earnings"][number];
 

package/src/plugins/builtin/shared/headless-market-data.ts

@@ -6,7 +6,7 @@ import { clipPriceHistoryToRange } from "../../../time-series/history-window";
 import { canonicalExchange, parsePublicTickerKey } from "../../../utils/exchanges";
 import { nonUsSecListingVenue } from "../../../utils/sec";
 
-export async function resolveHeadlessInstrument(ctx: HeadlessPaneContext, symbol: string) {
+export async function resolveHeadlessInstrument(ctx: Pick<HeadlessPaneContext, "resolveInstrument">, symbol: string) {
   return ctx.resolveInstrument ? ctx.resolveInstrument(symbol) : parsePublicTickerKey(symbol);
 }
 
@@ -39,7 +39,7 @@ export async function resolveHeadlessIssuerListing(ctx: HeadlessPaneContext, key
   return resolveIssuerListing(key, exchange, ctx.marketData);
 }
 
-export async function loadHeadlessFinancials(ctx: HeadlessPaneContext, key: string) {
+export async function loadHeadlessFinancials(ctx: Pick<HeadlessPaneContext, "marketData" | "resolveInstrument">, key: string) {
   const { symbol, exchange } = await resolveHeadlessInstrument(ctx, key);
   return ctx.marketData.getTickerFinancials(symbol, exchange ?? "");
 }

package/src/plugins/builtin/shared/job-posting.ts

@@ -34,6 +34,7 @@ export function countryName(code: string | null | undefined): string | null {
   try {
     return countryNames.of(code) ?? null;
   } catch {
+    // Intentional ignore: a region code Intl cannot name is left out of the posting's place.
     return null;
   }
 }

package/src/plugins/builtin/shared/members-menu.tsx

@@ -1,3 +1,4 @@
+import { logFailure } from "../../../utils/log-failure";
 import { ChoiceDialog, TextPromptDialog, usePaneMenuItems } from "../../../components";
 import { createFormCollectionActions } from "../../../components/form-modal/deps";
 import { t, tf } from "../../../i18n";
@@ -195,7 +196,7 @@ export function useMembersMenu(registrationId: string, list: MemberList | null)
         const choice = choices.find((item) => item.id === templateId && !item.disabled);
         // CORR and RIPL resolve `arg` like the command bar; RRG and SIW read `symbols`.
         if (choice) createPaneFromTemplate(choice.id, { symbols: choice.symbols, arg: formatTickerListInput(choice.symbols) });
-      }).catch(() => {});
+      }).catch(logFailure("shared.members-menu", "Open members in a function failed"));
     };
     const saveAsWatchlist = async (requested: string) => {
       // The writes hold the app for about a second with a hundred names; let the dialog close on screen first.
@@ -253,7 +254,7 @@ export function useMembersMenu(registrationId: string, list: MemberList | null)
           saveAsWatchlist(name).catch((error: unknown) => {
             notify({ type: "error", body: error instanceof Error ? error.message : t("The watchlist was not saved.") });
           });
-        }).catch(() => {});
+        }).catch(logFailure("shared.members-menu", "Open save members as watchlist prompt failed"));
       } },
     ];
   }, [createPaneFromTemplate, dialog, disabledPlugins, dispatch, getState, list, notify]);

package/src/plugins/builtin/shared/pro-lock-note.ts

@@ -1,3 +1,4 @@
+import { createTtlCache, type TtlCache } from "../../../data/ttl-cache";
 import type { HeadlessPaneContext } from "../../../types/headless";
 import type { PaneLock } from "../../../types/plugin";
 import { settleWithin, signalWithTimeout } from "../../../utils/async-deadline";
@@ -35,8 +36,7 @@ const ANSWER_TTL_MS = 5 * 60_000;
  */
 const ROUTE_CHECK_WAIT_MS = 3_000;
 
-interface KeptAnswer { at: number; answer: Promise<boolean> }
-const answers = new WeakMap<FreeRoute, Map<string, KeptAnswer>>();
+const answers = new WeakMap<FreeRoute, TtlCache<boolean>>();
 
 /**
  * Whether the route has data for the symbol, null when its check failed or was
@@ -45,20 +45,20 @@ const answers = new WeakMap<FreeRoute, Map<string, KeptAnswer>>();
  * rather than hiding the route for minutes over one slow read.
  */
 async function routeAnswers(route: FreeRoute, check: NonNullable<FreeRoute["answers"]>, symbol: string, context: HeadlessPaneContext, deadline: number): Promise<boolean | null> {
-  const bySymbol = answers.get(route) ?? new Map<string, KeptAnswer>();
+  const bySymbol = answers.get(route) ?? createTtlCache<boolean>({ ttlMs: ANSWER_TTL_MS });
   answers.set(route, bySymbol);
   const key = symbol.trim().toUpperCase();
-  let kept = bySymbol.get(key);
-  if (!kept || Date.now() - kept.at >= ANSWER_TTL_MS) {
+  const kept = bySymbol.load(key, () => {
     // The check's own reads stop at the deadline where they take a signal.
     const signal = signalWithTimeout(context.signal, Math.max(0, deadline - Date.now()));
-    const entry: KeptAnswer = { at: Date.now(), answer: check(symbol, { ...context, signal }) };
-    entry.answer.catch(logFailure("plugins.pro-lock-note", "Check a free route's data failed"));
-    bySymbol.set(key, entry);
-    kept = entry;
-  }
-  const answer = await settleWithin(kept.answer, Math.max(0, deadline - Date.now()));
-  if (answer === null && bySymbol.get(key) === kept) bySymbol.delete(key);
+    return check(symbol, { ...context, signal }).catch((error: unknown) => {
+      logFailure("plugins.pro-lock-note", "Check a free route's data failed")(error);
+      throw error;
+    });
+  });
+  const answer = await settleWithin(kept, Math.max(0, deadline - Date.now()));
+  // Only this check is dropped: a newer one for the symbol stays.
+  if (answer === null) bySymbol.delete(key, kept);
   return answer;
 }