@gloom-sh/terminal 0.18.5 → 0.19.0

package/src/i18n/zh-cn.ts

@@ -1129,6 +1129,19 @@ export const zhCN: Record<string, string> = {
   "{symbol}'s figures are not collected yet; the next read stores them.": "尚未采集 {symbol} 的数据；下次读取时会保存。",
   "{symbol} files with the SEC as a trust or pool, not as an open-end fund, and its sponsor's site is not one Gloom reads.": "{symbol} 在 SEC 登记为信托或资金池，而非开放式基金，且 Gloom 不读取其发起人的网站。",
   "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} 的数据：Gloom 不读取其发起人的网站，SEC 的招募说明书和 N-PORT 数据集中也尚未列出。",
+  "est. {range}": "估计 {range}",
+  "Shares outstanding": "流通份额",
+  "1M flows": "1个月资金流",
+  "Structure": "结构",
+  "Closed-end fund": "封闭式基金",
+  "BDC": "BDC",
+  "est.": "估计",
+  "{count} shares": "{count} 份",
+  "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} 的数据：它以封闭式基金或 BDC 身份向 SEC 申报，但 Gloom 读取的申报文件和其发起人的网站均尚未列出任何数据。",
+  "No NAV for {symbol}: {publisher} publishes figures for it, but no NAV.": "暂无 {symbol} 的资产净值：{publisher} 公布了其数据，但未公布资产净值。",
+  "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} 的资产净值：其 SEC 申报文件列出了净资产，但未列出每股资产净值，Gloom 也不读取其发起人公布的资产净值。",
+  "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} 的资产净值：Gloom 不读取其发起人的网站，信托也不在 SEC 的基金数据集中申报资产净值。",
+  "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} 的资产净值：Gloom 不读取其发起人的网站，SEC 的招募说明书和 N-PORT 数据集中也没有资产净值。",
   "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} 的数据：它以基金身份上市，但 SEC 的名单尚未收录，且 Gloom 不读取其发起人的网站。",
   "No fund facts for {symbol}: it is not on the SEC's lists of US-listed funds.": "{symbol} 没有基金概况：它不在 SEC 的美国上市基金名单中。",
   "No fund facts for {symbol} yet.": "{symbol} 暂无基金概况。",
@@ -1474,8 +1487,11 @@ export const zhCN: Record<string, string> = {
   "Answers cite filings, calls and news.": "回答引用公告、电话会议和新闻。",
   "{ticker} is open. {shortcut}, then AP, adds more.": "{ticker} 已打开。{shortcut} 然后输入 AP 可添加更多。",
   "Later: {shortcut}, then AP.": "之后：{shortcut}，然后输入 AP。",
-  "Enter: next field, then add.": "Enter：下一字段，最后添加。",
-  "Enter to add a ticker.": "按 Enter 添加代码。",
+  "Enter: next field, then add": "Enter：下一字段，最后添加",
+  "Add one ticker to continue": "添加一个代码即可继续",
+  "Add one ticker to continue.": "添加一个代码即可继续。",
+  "Esc, then Enter: continue": "Esc，然后 Enter：继续",
+  "Enter to add a ticker": "按 Enter 添加代码",
   "  already added": "  已添加",
   "Credentials stay on this device.": "凭据仅保存在此设备上。",
   "Ask Gloom": "Ask Gloom",

package/src/i18n/zh-tw.ts

@@ -1129,6 +1129,19 @@ export const zhTW: Record<string, string> = {
   "{symbol}'s figures are not collected yet; the next read stores them.": "尚未蒐集 {symbol} 的數據；下次讀取時會儲存。",
   "{symbol} files with the SEC as a trust or pool, not as an open-end fund, and its sponsor's site is not one Gloom reads.": "{symbol} 在 SEC 登記為信託或資金池，而非開放式基金，且 Gloom 不讀取其發起人的網站。",
   "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} 的數據：Gloom 不讀取其發起人的網站，SEC 的公開說明書與 N-PORT 資料集中也尚未列出。",
+  "est. {range}": "估計 {range}",
+  "Shares outstanding": "流通單位數",
+  "1M flows": "1個月資金流",
+  "Structure": "結構",
+  "Closed-end fund": "封閉式基金",
+  "BDC": "BDC",
+  "est.": "估計",
+  "{count} shares": "{count} 單位",
+  "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} 的數據：它以封閉式基金或 BDC 身分向 SEC 申報，但 Gloom 讀取的申報文件與其發起人的網站均尚未列出任何數據。",
+  "No NAV for {symbol}: {publisher} publishes figures for it, but no NAV.": "暫無 {symbol} 的資產淨值：{publisher} 公布了其數據，但未公布資產淨值。",
+  "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} 的資產淨值：其 SEC 申報文件列出了淨資產，但未列出每股資產淨值，Gloom 也不讀取其發起人公布的資產淨值。",
+  "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} 的資產淨值：Gloom 不讀取其發起人的網站，信託也不在 SEC 的基金資料集中申報資產淨值。",
+  "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} 的資產淨值：Gloom 不讀取其發起人的網站，SEC 的公開說明書與 N-PORT 資料集中也沒有資產淨值。",
   "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} 的數據：它以基金身分上市，但 SEC 的名單尚未收錄，且 Gloom 不讀取其發起人的網站。",
   "No fund facts for {symbol}: it is not on the SEC's lists of US-listed funds.": "{symbol} 沒有基金概況：它不在 SEC 的美國上市基金名單中。",
   "No fund facts for {symbol} yet.": "{symbol} 暫無基金概況。",
@@ -1474,8 +1487,11 @@ export const zhTW: Record<string, string> = {
   "Answers cite filings, calls and news.": "回答引用申報、法說會和新聞。",
   "{ticker} is open. {shortcut}, then AP, adds more.": "{ticker} 已開啟。{shortcut} 然後輸入 AP 可新增更多。",
   "Later: {shortcut}, then AP.": "之後：{shortcut}，然後輸入 AP。",
-  "Enter: next field, then add.": "Enter：下一欄位，最後新增。",
-  "Enter to add a ticker.": "按 Enter 新增代號。",
+  "Enter: next field, then add": "Enter：下一欄位，最後新增",
+  "Add one ticker to continue": "新增一個代號即可繼續",
+  "Add one ticker to continue.": "新增一個代號即可繼續。",
+  "Esc, then Enter: continue": "Esc，然後 Enter：繼續",
+  "Enter to add a ticker": "按 Enter 新增代號",
   "  already added": "  已新增",
   "Credentials stay on this device.": "憑證僅保存在此裝置上。",
   "Ask Gloom": "Ask Gloom",

package/src/market-data/depositary-pair.ts

@@ -41,9 +41,9 @@ export function ratioCount(ratio: number): string {
   return Number.isInteger(ratio) ? String(ratio) : String(Number(ratio.toPrecision(6)));
 }
 
-/** What a home line says of its receipt: `1 GGAL ADR = 10 of these shares`. */
+/** What a home line says of its receipt: `1 GGAL ADR = 10 of these shares`, and `1 of these shares` for one. */
 function homeLineRatioText(pair: DepositaryPair): string {
-  return `1 ${pair.receipt} ADR = ${ratioCount(pair.ratio)} of these share${pair.ratio === 1 ? "" : "s"}`;
+  return `1 ${pair.receipt} ADR = ${ratioCount(pair.ratio)} of these shares`;
 }
 
 /**

package/src/market-data/fund-facts.ts

@@ -0,0 +1,50 @@
+import { apiClient } from "../api-client";
+import type { FundFactsPayload, FundFlows } from "../api-client/fund-facts";
+import { isBondFactsShape } from "./bond-funds";
+
+/**
+ * A fund facts answer as every reader takes it (the ETF pane, DES, CMP,
+ * `ticker`, `fundamentals`): each figure dated and published, the parts a
+ * server before them leaves out still readable, anything malformed refused.
+ */
+
+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"));
+
+/** A NAV's estimate range, when the sponsor published one: absent, or two ends in order. */
+const estimateShape = (nav: FundFactsPayload["nav"]) => !nav?.estimate
+  || (finite(nav.estimate.low) && finite(nav.estimate.high) && nav.estimate.low <= nav.estimate.high);
+
+/** Absent from servers before them; otherwise a dated count, and a change between two dated counts. */
+const sharesShape = (value: FundFactsPayload["sharesOutstanding"]) => value == null || (fact(value) && finite(value.value));
+const flowsShape = (value: FundFlows | null | undefined) => value == null
+  || (finite(value.shares) && (value.value === null || finite(value.value)) && typeof value.from === "string" && typeof value.asOf === "string");
+
+export 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)
+    || !estimateShape(data.nav) || !sharesShape(data.sharesOutstanding) || !flowsShape(data.flows)
+    || !isBondFactsShape(data.bond) || !leverageShape(data.leverage) || !isMetalHoldingsShape(data.metalHoldings)) {
+    throw new Error("Unreadable fund facts response");
+  }
+  return data;
+}
+
+/** `GET /cloud/fund-facts/:ticker`, read and checked. */
+export async function readFundFacts(
+  symbol: string,
+  client: Pick<typeof apiClient, "getFundFacts"> = apiClient,
+  signal?: AbortSignal,
+): Promise<FundFactsPayload> {
+  return validateFundFacts(await (signal ? client.getFundFacts(symbol, { signal }) : client.getFundFacts(symbol)));
+}

package/src/market-data/market/change-basis.ts

@@ -4,6 +4,7 @@ import type { Quote } from "../../types/financials";
 import { canonicalExchange } from "../../utils/exchanges";
 import { isFiniteNumber } from "../../utils/guards";
 import { formatUtcDayTime } from "../../utils/utc-time";
+import { fxPrintTradingDay } from "../../utils/fx-market-hours";
 import { zonedDateKey } from "../../utils/zoned-date-time";
 import { futuresChangeBasis, futuresSettleText, isFuturesInstrument } from "../futures-contract";
 import { quoteTradingDay } from "../quotes/day-range";
@@ -94,6 +95,18 @@ function isCurrencyPair(quote: Quote): boolean {
     || kindFromListingSyntax(quote.symbol, quote.listingExchangeName || quote.exchangeName) === "currency";
 }
 
+/**
+ * The trading day a quote describes (quoteTradingDay); for a currency pair,
+ * whose venue has no clock, the FX trading day of its print, which turns at
+ * 17:00 New York, so every pair on a board is dated alike. Null for a pair's
+ * print made while FX is shut, which belongs to no trading day.
+ */
+function tradingDayOf(quote: Quote): string | null {
+  const day = quoteTradingDay(quote);
+  if (day || !isCurrencyPair(quote) || !Number.isFinite(quote.lastUpdated) || quote.lastUpdated <= 0) return day;
+  return fxPrintTradingDay(quote.lastUpdated);
+}
+
 /** A coin on the spot crypto venue: its day is the UTC day. */
 function isSpotCoin(quote: Quote): boolean {
   return quoteVenue(quote) === "CCC";
@@ -154,7 +167,7 @@ export function isChangeBasisDatedWithoutCloses(quote: Quote, now = Date.now()):
  * nothing dates it.
  */
 export function changeBasisSessionDate(quote: Quote): string | null {
-  const date = regularSessionDisplayDate(quote) ?? quoteTradingDay(quote);
+  const date = regularSessionDisplayDate(quote) ?? tradingDayOf(quote);
   return date && ISO_DATE.test(date) ? date : null;
 }
 
@@ -179,7 +192,7 @@ export function quoteChangeBasis(
   if (!display || !isFiniteNumber(display.change)) return null;
   if (quote.changeBasis === "24h" || isPerpetualExchange(quote.listingExchangeName || quote.exchangeName)) return { kind: "24h" };
   if (isSpotCoin(quote)) return { kind: "utc day" };
-  const sessionDate = (session === "active" ? quote.changeSessionDate : regularSessionDisplayDate(quote)) ?? quoteTradingDay(quote);
+  const sessionDate = (session === "active" ? quote.changeSessionDate : regularSessionDisplayDate(quote)) ?? tradingDayOf(quote);
   if (isFuturesInstrument(quote.symbol, quote.instrumentType)) {
     const basis = futuresChangeBasis(terms ?? { settlement: null }, { ...display, sessionDate }, quoteVenue(quote));
     return basis ? { kind: basis.kind, date: basis.session } : { kind: "previous close" };
@@ -211,7 +224,7 @@ export function quoteSettleText(
 export function quotePreviousCloseDate(quote: Quote | null | undefined): string | null {
   if (!quote || !isFiniteNumber(quote.previousClose) || quote.changeBasis != null) return null;
   if (isPerpetualExchange(quote.listingExchangeName || quote.exchangeName)) return null;
-  const sessionDate = quote.changeSessionDate ?? quoteTradingDay(quote);
+  const sessionDate = quote.changeSessionDate ?? tradingDayOf(quote);
   if (!sessionDate || !ISO_DATE.test(sessionDate)) return null;
   if (isSpotCoin(quote)) return dayBefore(sessionDate);
   if (isFuturesInstrument(quote.symbol, quote.instrumentType)) {

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

@@ -628,6 +628,31 @@ function currencyMarks(currency: string, normalizedCurrency: string, code = fals
   return code ? { prefix: "", suffix: ` ${normalizedCurrency}` } : { prefix: getCurrencySymbol(normalizedCurrency), suffix: "" };
 }
 
+/**
+ * A London line shown in pounds and served in the pence it trades in. The
+ * code is compared in its own case: `GBp` (and `GBX`) is a price already in
+ * pence, which says so itself (630.8p) and needs no pence figure beside it.
+ */
+export function isPenceQuotedLine(quote: Pick<Quote, "currency" | "providerPriceDivisor"> | null | undefined): boolean {
+  return quote?.currency?.trim() === "GBP" && quote.providerPriceDivisor === 100;
+}
+
+/**
+ * A London line's price in the pence it trades in, as the exchange and its
+ * announcements write it: `630.8p` for £6.308, with the decimals of a penny
+ * the pounds are shown to (`poundDecimals`) beyond two. Null for a price not
+ * quoted in pence.
+ */
+export function penceFigure(
+  value: number | null | undefined,
+  quote: Pick<Quote, "currency" | "providerPriceDivisor"> | null | undefined,
+  poundDecimals: number,
+): string | null {
+  if (value == null || !Number.isFinite(value) || !isPenceQuotedLine(quote)) return null;
+  const digits = Math.max(0, Math.min(4, poundDecimals - 2));
+  return `${getNumberFormatter(digits, digits, true).format(value * 100)}${minorUnitSign("GBp")}`;
+}
+
 export function formatMarketPriceWithCurrency(
   value: number | undefined,
   currency = "USD",

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

@@ -32,7 +32,8 @@ const REGULAR_OPEN_MINUTES: Record<string, number> = {
   TSXV: 9 * 60 + 30,
   CSE: 9 * 60 + 30,
   FWB2: 8 * 60,
-  XETRA: 8 * 60,
+  // Continuous trading opens at 09:00 Berlin time, after the opening auction; before it is pre-trading.
+  XETRA: 9 * 60,
   LSE: 8 * 60,
   EPA: 9 * 60,
   AMS: 9 * 60,

package/src/market-data/options-alternatives.ts

@@ -1,4 +1,5 @@
 import { isRoundTheClockCoin } from "../utils/crypto-pair";
+import { currencyPairCode, isCurrencyCode } from "../utils/currency-pair";
 import { parsePublicTickerKey } from "../utils/exchanges";
 import { parseFuturesGeneric } from "../utils/futures-generic";
 
@@ -34,23 +35,24 @@ const FUTURES_ALTERNATIVES: Readonly<Record<string, ListedOptionsAlternative>> =
   ZN: { symbol: "IEF", name: "iShares 7-10 Year Treasury Bond ETF" },
   "6E": { symbol: "FXE", name: "Invesco CurrencyShares Euro Trust" },
   "6J": { symbol: "FXY", name: "Invesco CurrencyShares Japanese Yen Trust" },
+  "6B": { symbol: "FXB", name: "Invesco CurrencyShares British Pound Sterling Trust" },
   BTC: { symbol: "IBIT", name: "iShares Bitcoin Trust" },
   ETH: { symbol: "ETHA", name: "iShares Ethereum Trust" },
 };
 
 const MONTH_CODE_CONTRACT = /^([A-Z0-9]{1,3}?)[FGHJKMNQUVXZ]\d{1,4}$/;
 
-/** The futures root a symbol names: GC=F, GCZ26 and the generic GC1 all give GC. */
-function futuresRoot(symbol: string): string | null {
+/** The futures root a symbol names: GC=F, GCZ26 and the generic GC1 all give GC. `known` says which roots a bare contract may carry. */
+function futuresRoot(symbol: string, known: (root: string) => boolean = (root) => !!FUTURES_ALTERNATIVES[root]): string | null {
   const ticker = symbol.trim().toUpperCase().replace(/[.:][A-Z]+$/, "");
   if (ticker.endsWith("=F")) {
     const body = ticker.slice(0, -2);
-    return FUTURES_ALTERNATIVES[body] ? body : MONTH_CODE_CONTRACT.exec(body)?.[1] ?? body;
+    return known(body) ? body : MONTH_CODE_CONTRACT.exec(body)?.[1] ?? body;
   }
   const generic = parseFuturesGeneric(ticker);
   if (generic) return generic.root;
   const contract = MONTH_CODE_CONTRACT.exec(ticker)?.[1];
-  return contract && FUTURES_ALTERNATIVES[contract] ? contract : null;
+  return contract && known(contract) ? contract : null;
 }
 
 /** The listed fund whose options stand in for an instrument with no chain, if there is one. */
@@ -127,3 +129,78 @@ export function coinOptionsAlias(code: string) {
     return pair ? { symbol: pair, note: `${key} read as ${pair}, the coin's options. For the US fund that trades as ${key}: gloomberb fn ${code} ${key}:ARCA` } : null;
   };
 }
+
+/**
+ * The CME currency futures, each as the pair it settles on, in the order the
+ * pair is quoted: 6E is EUR/USD, 6J USD/JPY. No chain of options on any of
+ * them is served here, as none is on the spot pair.
+ */
+const FX_FUTURES_PAIRS: Readonly<Record<string, string>> = {
+  "6E": "EURUSD", "6J": "USDJPY", "6B": "GBPUSD", "6A": "AUDUSD", "6C": "USDCAD", "6S": "USDCHF", "6N": "NZDUSD", "6M": "USDMXN",
+};
+
+/** The US-listed currency funds whose options stand in for an FX pair's volatility, by the currency they hold. */
+const FX_VOL_FUNDS: Readonly<Record<string, string>> = { EUR: "FXE", JPY: "FXY", GBP: "FXB" };
+/** The fund that holds the dollar against a basket, for a pair none of the single-currency funds holds. */
+const DOLLAR_FUND = "UUP";
+const FX_VOL_FUND_LIST = [...Object.values(FX_VOL_FUNDS), DOLLAR_FUND];
+
+/** The pair a symbol is: a spot pair in any spelling (EURUSD=X, EUR/USD), or a currency future (6E=F, 6EZ26, 6E1) as the pair it settles on; null for anything else. */
+export function fxVolatilityPair(symbol: string, exchange?: string): string | null {
+  const spot = currencyPairCode(symbol, exchange);
+  // Metals quoted against a currency (XAUUSD=X) are no currency pair.
+  if (spot) return isCurrencyCode(spot.slice(0, 3)) && isCurrencyCode(spot.slice(3)) ? spot : null;
+  const root = futuresRoot(symbol, (candidate) => !!FX_FUTURES_PAIRS[candidate]);
+  return root ? FX_FUTURES_PAIRS[root] ?? null : null;
+}
+
+/**
+ * The listed fund that stands in for an FX pair's volatility: the one that
+ * holds the pair's euro, yen or pound, else the dollar index fund.
+ */
+function fxVolatilityFunds(pair: string): string[] {
+  const held = [pair.slice(0, 3), pair.slice(3)].map((code) => FX_VOL_FUNDS[code]).filter((fund): fund is string => !!fund);
+  return held.length > 0 ? held : FX_VOL_FUND_LIST;
+}
+
+/**
+ * What exists instead for the volatility of an FX pair or currency future,
+ * worded as one line for the CLI: OTC FX volatility is not served, the
+ * currency funds' options are the nearest listed thing (the one that holds
+ * the pair's euro, yen or pound, else any of them), and HVT reads the pair's
+ * realized volatility. Null for anything that is no FX pair. `code` is the
+ * function asked (OVDV), `symbol` as typed.
+ */
+function fxVolatilityAnswer(code: string, symbol: string): string | null {
+  const pair = fxVolatilityPair(symbol);
+  if (!pair) return null;
+  const typed = symbol.trim().toUpperCase();
+  const funds = fxVolatilityFunds(pair);
+  // VCA screens every fund; the others read the pair's own, or the dollar's when it has none.
+  const read = code === "VCA" ? funds.join(",") : funds === FX_VOL_FUND_LIST ? DOLLAR_FUND : funds[0]!;
+  return `OTC FX volatility is not covered for ${typed}. Currency-ETF options are the listed proxy: `
+    + `${funds.join(", ")} (gloom fn ${code} ${read}). Realized volatility: gloom fn HVT ${typed}.`;
+}
+
+/**
+ * The same for a pane, which has no commands to give: what is not covered,
+ * the funds whose options stand in, and HVT for realized volatility.
+ */
+export function fxVolatilityNote(symbol: string, exchange?: string): string | null {
+  const pair = fxVolatilityPair(symbol, exchange);
+  if (!pair) return null;
+  return `OTC FX volatility is not covered for ${symbol.trim().toUpperCase()}. Currency-ETF options are the listed proxy: `
+    + `${fxVolatilityFunds(pair).join(", ")}. HVT shows the pair's realized volatility.`;
+}
+
+/**
+ * A volatility function's `refuseSymbol` for FX (OVDV, VCA, HIVG): an FX pair
+ * or currency future is answered before any request, with one line saying
+ * OTC FX volatility is not covered and what to read instead.
+ */
+export function fxVolatilityRefusal(code: string) {
+  return (key: string): { message: string; details?: string } | null => {
+    const message = fxVolatilityAnswer(code, key);
+    return message ? { message } : null;
+  };
+}

package/src/news/aggregator.ts

@@ -1,7 +1,7 @@
 import { logFailure } from "../utils/log-failure";
 import type { NewsCapability } from "../capabilities";
 import type { ConnectionHealthRegistry } from "../core/connection-health";
-import type { NewsArticle, NewsQuery, NewsQueryState } from "./types";
+import type { NewsAccess, NewsArticle, NewsQuery, NewsQueryState } from "./types";
 import { isAppVisible, subscribeAppVisibility } from "../state/app/activity";
 import {
   DEFAULT_GLOBAL_QUERY,
@@ -28,6 +28,18 @@ export interface NewsServiceOptions {
   connectionHealth?: ConnectionHealthRegistry;
   /** Defaults to the app's visibility; injectable for tests. */
   visibility?: { isVisible(): boolean; subscribe(listener: () => void): () => void };
+  /**
+   * The session the sources read news with. Its key changes when what the
+   * service answers changes: a session restored at launch, a sign-in or
+   * sign-out, an upgrade. Every open query is then read again and its stories
+   * replaced, so a feed read without the session is not left on screen.
+   */
+  session?: NewsSessionSignal;
+}
+
+export interface NewsSessionSignal {
+  key(): string;
+  subscribe(listener: () => void): () => void;
 }
 
 export type NewsQueryListener = (state: NewsQueryState) => void;
@@ -50,17 +62,30 @@ interface SourceFetchResult {
   failedSourceIds: string[];
   errors: string[];
   nextCursor: string | null;
+  access: NewsAccess | null;
 }
 
 interface NewsQueryEntry {
   query: NewsQuery;
   state: NewsQueryState;
   inFlight: Promise<NewsQueryState> | null;
+  /** The session generation the read in flight went out under. */
+  inFlightGeneration: number;
   loadMoreInFlight: Promise<void> | null;
+  loadMoreGeneration: number;
+  /** The session generation the stories on screen were read under. */
+  generation: number;
   refs: number;
   lastAccessedAt: number;
 }
 
+/** Held back beats live: one source the service held back is enough to say the list is not the live wire. */
+function combineNewsAccess(values: ReadonlyArray<NewsAccess | null | undefined>): NewsAccess | null {
+  if (values.includes("delayed")) return "delayed";
+  if (values.includes("realtime")) return "realtime";
+  return null;
+}
+
 function newsCapabilityPriority(source: NewsCapability): number {
   return source.priority ?? 1000;
 }
@@ -85,6 +110,12 @@ export class NewsService {
   private readonly visibility: NonNullable<NewsServiceOptions["visibility"]>;
   private lastPollAt = 0;
   private unsubscribeVisibility: (() => void) | null = null;
+  private readonly session?: NewsSessionSignal;
+  private sessionKey: string | null = null;
+  /** Bumped when the session changes; a read from an older generation is dropped. */
+  private sessionGeneration = 0;
+  private sessionRefetchQueued = false;
+  private unsubscribeSession: (() => void) | null = null;
 
   constructor(options: NewsServiceOptions = {}) {
     const pollInterval = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
@@ -94,6 +125,7 @@ export class NewsService {
     this.now = options.now ?? Date.now;
     this.connectionHealth = options.connectionHealth;
     this.visibility = options.visibility ?? { isVisible: isAppVisible, subscribe: subscribeAppVisibility };
+    this.session = options.session;
   }
 
   register(source: NewsCapability): () => void {
@@ -125,6 +157,10 @@ export class NewsService {
       this.clearPollTimer();
       this.scheduleNextPoll();
     });
+    if (this.session) {
+      this.sessionKey = this.session.key();
+      this.unsubscribeSession = this.session.subscribe(() => this.handleSessionChange());
+    }
     this.scheduleNextPoll();
   }
 
@@ -132,9 +168,46 @@ export class NewsService {
     this.polling = false;
     this.unsubscribeVisibility?.();
     this.unsubscribeVisibility = null;
+    this.unsubscribeSession?.();
+    this.unsubscribeSession = null;
     this.clearPollTimer();
   }
 
+  /**
+   * A new session answers with other news: the live wire once a Pro session
+   * is in place, the held-back one after signing out. Reads still out under
+   * the old session are dropped, open queries are read again and replace
+   * their stories rather than merge into them, and closed ones are forgotten.
+   * A token and its user arrive as separate changes, so the reads wait for
+   * the end of the tick and go out once.
+   */
+  private handleSessionChange(): void {
+    if (!this.session) return;
+    const key = this.session.key();
+    if (key === this.sessionKey) return;
+    this.sessionKey = key;
+    this.sessionGeneration++;
+    if (this.sessionRefetchQueued) return;
+    this.sessionRefetchQueued = true;
+    queueMicrotask(() => {
+      this.sessionRefetchQueued = false;
+      if (!this.polling) return;
+      let dropped = false;
+      for (const [queryKey, entry] of this.queries) {
+        if (entry.refs > 0) continue;
+        this.queries.delete(queryKey);
+        dropped = true;
+      }
+      if (dropped) {
+        this.rebuildArticlePool();
+        this.notify();
+      }
+      for (const entry of this.queries.values()) {
+        void this.refreshQuery(entry.query, true);
+      }
+    });
+  }
+
   private pollInFlight = false;
 
   private clearPollTimer(): void {
@@ -226,6 +299,7 @@ export class NewsService {
       return;
     }
 
+    const generation = this.sessionGeneration;
     const request = (async () => {
       entry.state = { ...entry.state, loadingMore: true };
       this.notify();
@@ -234,6 +308,12 @@ export class NewsService {
           ...normalized,
           cursor: entry.state.nextCursor ?? undefined,
         });
+        // An older page from another session must not join the list the new session read.
+        if (generation !== this.sessionGeneration || entry.generation !== generation) {
+          entry.state = { ...entry.state, loadingMore: false };
+          this.notify();
+          return;
+        }
         entry.state = {
           ...entry.state,
           loadingMore: false,
@@ -253,6 +333,7 @@ export class NewsService {
       }
     })();
     entry.loadMoreInFlight = request;
+    entry.loadMoreGeneration = generation;
     await request;
   }
 
@@ -318,7 +399,9 @@ export class NewsService {
     showLoading: boolean,
   ): Promise<NewsQueryState> {
     const entry = this.getOrCreateQueryEntry(query);
-    if (entry.inFlight) return entry.inFlight;
+    const generation = this.sessionGeneration;
+    // A read that went out under an older session answers for that session: a new one goes out beside it.
+    if (entry.inFlight && entry.inFlightGeneration === generation) return entry.inFlight;
 
     const current = entry.state;
     if (showLoading) {
@@ -333,14 +416,17 @@ export class NewsService {
     const promise = (async () => {
       try {
         const result = await this.fetchFromSources(query);
+        if (generation !== this.sessionGeneration) return this.currentRead(entry);
         if (result.sourceIds.length === 0 && result.failedSourceIds.length > 0) {
           throw new Error("News sources unavailable.");
         }
-        if (entry.loadMoreInFlight) return entry.state;
+        if (entry.loadMoreInFlight && entry.loadMoreGeneration === generation) return entry.state;
         const incoming = filterNewsArticlesForQuery(dedupeNewsArticles(result.articles), query);
+        // Stories read under another session are another feed (held back, or live): the new read replaces them.
+        const sameSession = entry.generation === generation;
         // The stories a coin's fallback found are not the pair's own: once stories are filed under it, they replace them.
-        const existing = incoming.length > 0 && entry.state.articles.length > 0
-          && (incoming[0]!.searchedFor ?? null) !== (entry.state.articles[0]!.searchedFor ?? null)
+        const existing = !sameSession || (incoming.length > 0 && entry.state.articles.length > 0
+          && (incoming[0]!.searchedFor ?? null) !== (entry.state.articles[0]!.searchedFor ?? null))
           ? []
           : entry.state.articles;
         const incomingIds = new Set(incoming.map((article) => article.id));
@@ -363,13 +449,17 @@ export class NewsService {
           sourceIds: result.sourceIds,
           nextCursor: hasOlderPages ? entry.state.nextCursor : result.nextCursor,
           loadingMore: entry.state.loadingMore,
+          // A page that does not say keeps what this session's earlier answer said.
+          access: result.access ?? (sameSession ? entry.state.access ?? null : null),
         };
         entry.state = state;
+        entry.generation = generation;
         entry.lastAccessedAt = this.now();
         this.rebuildArticlePool();
         this.notify();
         return state;
       } catch (error) {
+        if (generation !== this.sessionGeneration) return this.currentRead(entry);
         const state: NewsQueryState = {
           ...current,
           phase: "error",
@@ -380,15 +470,21 @@ export class NewsService {
         this.notify();
         return state;
       } finally {
-        entry.inFlight = null;
+        if (entry.inFlightGeneration === generation) entry.inFlight = null;
         this.pruneInactiveQueries();
       }
     })();
 
     entry.inFlight = promise;
+    entry.inFlightGeneration = generation;
     return promise;
   }
 
+  /** What a dropped read answers its caller: the current session's read when one is out, else the state as it is. */
+  private currentRead(entry: NewsQueryEntry): Promise<NewsQueryState> | NewsQueryState {
+    return entry.inFlight && entry.inFlightGeneration === this.sessionGeneration ? entry.inFlight : entry.state;
+  }
+
   private getOrCreateQueryEntry(query: NewsQuery): NewsQueryEntry {
     const key = buildNewsQueryKey(query);
     const now = this.now();
@@ -402,7 +498,10 @@ export class NewsService {
       query,
       state: createIdleNewsQueryState(),
       inFlight: null,
+      inFlightGeneration: this.sessionGeneration,
       loadMoreInFlight: null,
+      loadMoreGeneration: this.sessionGeneration,
+      generation: this.sessionGeneration,
       refs: 0,
       lastAccessedAt: now,
     };
@@ -451,7 +550,7 @@ export class NewsService {
   private async readSourcePage(
     source: NewsCapability,
     query: NewsQuery,
-  ): Promise<{ articles: NewsArticle[]; nextCursor: string | null; error?: string | null }> {
+  ): Promise<{ articles: NewsArticle[]; nextCursor: string | null; error?: string | null; access?: NewsAccess | null }> {
     if (source.provider.fetchNewsPage) {
       const page = await this.trackSourceRequest(
         source,
@@ -462,6 +561,7 @@ export class NewsService {
         articles: page.articles.map((article) => markDetailCapableArticle(source, article)),
         nextCursor: page.nextCursor ?? null,
         error: page.error,
+        access: page.access,
       };
     }
     const articles = (await this.trackSourceRequest(
@@ -484,6 +584,7 @@ export class NewsService {
           failedSourceIds,
           errors: page.error ? [page.error] : [],
           nextCursor: page.nextCursor,
+          access: page.access ?? null,
         };
         if (page.articles.length > 0) return result;
         firstEmpty ??= result;
@@ -491,7 +592,7 @@ export class NewsService {
         failedSourceIds.push(newsCapabilitySourceId(source));
       }
     }
-    return firstEmpty ?? { articles: [], sourceIds: [], failedSourceIds, errors: [], nextCursor: null };
+    return firstEmpty ?? { articles: [], sourceIds: [], failedSourceIds, errors: [], nextCursor: null, access: null };
   }
 
   private async fetchMergedNews(query: NewsQuery, sources: NewsCapability[]): Promise<SourceFetchResult> {
@@ -505,6 +606,7 @@ export class NewsService {
     const errors: string[] = [];
     const sourceIds: string[] = [];
     const failedSourceIds: string[] = [];
+    const access: Array<NewsAccess | null | undefined> = [];
     let nextCursor: string | null = null;
     settled.forEach((result, index) => {
       if (result.status !== "fulfilled") {
@@ -515,9 +617,10 @@ export class NewsService {
       articles.push(...result.value.page.articles);
       if (result.value.page.error) errors.push(result.value.page.error);
       sourceIds.push(newsCapabilitySourceId(result.value.source));
+      access.push(result.value.page.access);
       nextCursor ??= result.value.page.nextCursor;
     });
-    return { articles, sourceIds, failedSourceIds, errors, nextCursor };
+    return { articles, sourceIds, failedSourceIds, errors, nextCursor, access: combineNewsAccess(access) };
   }
 
   private trackSourceRequest<T>(
@@ -550,6 +653,7 @@ export class NewsService {
         sourceIds: [...new Set([...entry.state.sourceIds, newsCapabilitySourceId(source)])],
         nextCursor: entry.state.nextCursor,
         loadingMore: false,
+        access: entry.state.access ?? null,
       };
       changed = true;
     }