gloomberb 0.16.5 → 0.17.0

package/src/ask-gloom/pane-text.ts

@@ -0,0 +1,201 @@
+import type { NativeFrameCapture } from "../ui/host";
+import { displayWidth } from "../utils/format";
+
+/**
+ * At most this much of a pane's text goes with a question: a summary of what
+ * it shows, not a dump. It leaves room in the terminal context Gloom reads,
+ * which keeps 2,000 characters of it.
+ */
+export const PANE_TEXT_MAX_CHARS = 1_500;
+const PANE_TEXT_MAX_LINES = 50;
+
+export interface CellRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** The frame's sides and rules: lines of them say nothing, and an edge cell is not content. */
+const RULE_LINE = /^[\s│┃║┆┊╎─━═┄┈╌┌┐└┘├┤┬┴┼╭╮╯╰▏▕█▐▌░▒▓]*$/u;
+const LEADING_EDGE = /^[│┃║▏▕]\s?/u;
+const TRAILING_EDGE = /\s?[│┃║▏▕█▐▌░▒▓]+$/u;
+
+/**
+ * A pane's text, trimmed to what it says: no frame edges, rules or trailing
+ * blanks, runs of padding cut to two spaces so columns stay apart, blank
+ * lines folded, and the whole bounded. Null when nothing is left.
+ */
+export function normalizePaneText(raw: string): string | null {
+  const lines: string[] = [];
+  let blank = false;
+  for (const rawLine of raw.split(/\r?\n/)) {
+    if (RULE_LINE.test(rawLine)) {
+      blank = lines.length > 0;
+      continue;
+    }
+    const line = rawLine
+      .replace(LEADING_EDGE, "")
+      .replace(TRAILING_EDGE, "")
+      .replace(/\s+$/u, "")
+      .replace(/\s{3,}/gu, "  ");
+    if (!line.trim()) {
+      blank = lines.length > 0;
+      continue;
+    }
+    if (blank) lines.push("");
+    blank = false;
+    lines.push(line);
+  }
+  if (lines.length === 0) return null;
+
+  const kept: string[] = [];
+  let used = 0;
+  for (const line of lines.slice(0, PANE_TEXT_MAX_LINES)) {
+    if (used + line.length + 1 > PANE_TEXT_MAX_CHARS) break;
+    kept.push(line);
+    used += line.length + 1;
+  }
+  if (kept.length === 0) kept.push(lines[0]!.slice(0, PANE_TEXT_MAX_CHARS - 1));
+  const cut = kept.length < lines.length || kept[0] !== lines[0];
+  return cut ? `${kept.join("\n")}\n…` : kept.join("\n");
+}
+
+function covers(rect: CellRect, x: number, y: number): boolean {
+  return x >= rect.x && x < rect.x + rect.width && y >= rect.y && y < rect.y + rect.height;
+}
+
+/**
+ * A terminal pane's text from the frame on screen: the rows under its header,
+ * the columns it spans. Cells another surface covers (a floating pane above
+ * it, the menu it was asked from) are left blank, so only this pane's own
+ * text goes. `rect` and `covered` are in the pane area's cells, which starts
+ * `offsetX` columns and `offsetY` rows into the screen (under the app header).
+ */
+export function terminalPaneText(
+  frame: NativeFrameCapture,
+  rect: CellRect,
+  { offsetX = 0, offsetY = 0, covered = [] }: { offsetX?: number; offsetY?: number; covered?: readonly CellRect[] } = {},
+): string | null {
+  const rows: string[] = [];
+  const left = Math.max(0, Math.floor(rect.x + offsetX));
+  const right = Math.floor(rect.x + offsetX + rect.width);
+  const top = Math.floor(rect.y) + 1;
+  const bottom = Math.floor(rect.y + rect.height);
+  for (let row = top; row < bottom; row += 1) {
+    const spans = frame.lines[row + offsetY];
+    if (!spans) continue;
+    let column = 0;
+    let text = "";
+    for (const span of spans) {
+      // One code point per cell; a wide one is followed by an empty continuation cell.
+      for (const char of span.text) {
+        const start = column;
+        const width = displayWidth(char) >= 2 ? 2 : 1;
+        column += width;
+        if (start < left || start >= right) continue;
+        text += covered.some((other) => covers(other, start - offsetX, row)) ? " ".repeat(width) : char;
+      }
+      if (column >= right) break;
+    }
+    rows.push(text);
+  }
+  return normalizePaneText(rows.join("\n"));
+}
+
+function attributeValue(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
+}
+
+interface PixelRect {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+}
+
+function intersect(a: PixelRect, b: PixelRect): PixelRect | null {
+  const rect = {
+    left: Math.max(a.left, b.left),
+    top: Math.max(a.top, b.top),
+    right: Math.min(a.right, b.right),
+    bottom: Math.min(a.bottom, b.bottom),
+  };
+  return rect.right > rect.left && rect.bottom > rect.top ? rect : null;
+}
+
+/**
+ * Where an element's content can be seen: the pane body cut down by every box
+ * between them that clips (a scrolled list, a table body), or null when one
+ * of them hides it.
+ */
+function visibleArea(element: Element, body: HTMLElement, cache: Map<Element, PixelRect | null>): PixelRect | null {
+  const cached = cache.get(element);
+  if (cached !== undefined) return cached;
+  let area: PixelRect | null;
+  if (element === body) {
+    area = body.getBoundingClientRect();
+  } else {
+    const parent = element.parentElement;
+    area = parent ? visibleArea(parent, body, cache) : null;
+    const view = element.ownerDocument.defaultView;
+    const style = view?.getComputedStyle(element);
+    if (area && style) {
+      if (style.visibility === "hidden" || style.display === "none" || style.opacity === "0") area = null;
+      else if (style.overflowX !== "visible" || style.overflowY !== "visible") area = intersect(area, element.getBoundingClientRect());
+    }
+  }
+  cache.set(element, area);
+  return area;
+}
+
+/**
+ * A desktop or web pane's text as it is on screen: its body, without the
+ * header or footer, and only what can be seen, so rows scrolled out of a list
+ * and anything clipped stay out. Text on one line is joined in reading order.
+ */
+export function domPaneText(paneId: string): string | null {
+  const doc = (globalThis as { document?: Document }).document;
+  if (!doc) return null;
+  const pane = doc.querySelector<HTMLElement>(`[data-gloom-pane-id="${attributeValue(paneId)}"]`);
+  const body = pane?.querySelector<HTMLElement>("[data-gloom-role=pane-body]") ?? pane;
+  if (!body) return null;
+
+  const areas = new Map<Element, PixelRect | null>();
+  const pieces: Array<{ top: number; bottom: number; left: number; right: number; text: string }> = [];
+  const range = doc.createRange();
+  const walker = doc.createTreeWalker(body, 4 /* NodeFilter.SHOW_TEXT */);
+  for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+    const text = node.textContent?.replace(/\s+/g, " ").trim();
+    const parent = node.parentElement;
+    if (!text || !parent) continue;
+    const area = visibleArea(parent, body, areas);
+    if (!area) continue;
+    range.selectNodeContents(node);
+    const rects = Array.from(range.getClientRects()).filter((rect) => rect.width > 0 && intersect(area, rect));
+    const first = rects[0];
+    if (!first) continue;
+    pieces.push({ top: first.top, bottom: first.bottom, left: first.left, right: first.right, text });
+  }
+  range.detach?.();
+
+  // Pieces whose middles share a line read as one, left to right, with a
+  // gap where the pane leaves one between them.
+  pieces.sort((a, b) => (a.top + a.bottom) / 2 - (b.top + b.bottom) / 2 || a.left - b.left);
+  const lines: Array<{ middle: number; height: number; parts: typeof pieces }> = [];
+  for (const piece of pieces) {
+    const middle = (piece.top + piece.bottom) / 2;
+    const line = lines[lines.length - 1];
+    if (line && Math.abs(line.middle - middle) < Math.max(4, line.height / 2)) line.parts.push(piece);
+    else lines.push({ middle, height: piece.bottom - piece.top, parts: [piece] });
+  }
+  const text = lines.map((line) => {
+    const parts = [...line.parts].sort((a, b) => a.left - b.left);
+    return parts.reduce((out, part, index) => {
+      if (index === 0) return part.text;
+      const gap = part.left - parts[index - 1]!.right;
+      return `${out}${gap > 6 ? "  " : gap > 0.5 ? " " : ""}${part.text}`;
+    }, "");
+  }).join("\n");
+  return normalizePaneText(text);
+}

package/src/capabilities/chart-series.ts

@@ -202,7 +202,7 @@ function resolvedOutput(value: unknown): ResolvedSeries {
   const input = object(value, "resolve output");
   onlyKeys(input, "resolve output", [
     "id", "label", "color", "unit", "unitGroup", "nativeFrequency", "timestampMode", "dataShape", "style", "transform",
-    "axis", "panelId", "interpolation", "timeBasis", "latestChangePercent", "points", "warning", "hidden",
+    "axis", "panelId", "interpolation", "timeBasis", "latestChangePercent", "points", "warning", "hidden", "attribution",
   ]);
   if (!Array.isArray(input.points)) fail("resolve output points", "expected an array.");
   if (input.points.length > MAX_CHART_SERIES_POINTS) {
@@ -212,6 +212,9 @@ function resolvedOutput(value: unknown): ResolvedSeries {
   if (timeBasis) onlyKeys(timeBasis, "resolve output time basis", ["kind", "timeZone", "cadenceMs"]);
   const kind = timeBasis?.kind === undefined ? undefined : enumValue<"market">(timeBasis.kind, "time basis kind", new Set(["market"]));
   const warning = optionalString(input.warning, "resolve output warning", 500);
+  const attribution = input.attribution === undefined ? undefined : object(input.attribution, "resolve output attribution");
+  if (attribution) onlyKeys(attribution, "resolve output attribution", ["source", "publisher"]);
+  const publisher = attribution ? optionalString(attribution.publisher, "resolve output publisher", 160) : undefined;
   return {
     id: boundedString(input.id, "resolve output ID", 160),
     label: boundedString(input.label, "resolve output label", 160),
@@ -242,6 +245,10 @@ function resolvedOutput(value: unknown): ResolvedSeries {
       : {}),
     points: input.points.map(point),
     ...(warning !== undefined ? { warning } : {}),
+    ...(attribution ? { attribution: {
+      source: boundedString(attribution.source, "resolve output source", 160),
+      ...(publisher !== undefined ? { publisher } : {}),
+    } } : {}),
     ...(input.hidden !== undefined
       ? typeof input.hidden === "boolean" ? { hidden: input.hidden } : fail("resolve output hidden", "expected a boolean.")
       : {}),

package/src/capabilities/factories.ts

@@ -61,6 +61,7 @@ export function assetDataProvider(provider: AssetDataProvider): AssetDataCapabil
         if (!provider.getCorporateActions) throw new Error(`${provider.name} does not provide corporate actions.`);
         return provider.getCorporateActions(input.ticker, input.exchange, input.context);
       }, "query"),
+      getTickerChanges: op((input: any) => provider.getTickerChanges?.(input.symbol) ?? Promise.resolve(null), "query"),
       getEarningsCalendar: op((input: any) => {
         if (!provider.getEarningsCalendar) throw new Error(`${provider.name} does not provide earnings calendar.`);
         return provider.getEarningsCalendar(input.symbols ?? [], input.context);

package/src/cli/central-bank-events.ts

@@ -0,0 +1,23 @@
+import { centralBankNamed } from "../utils/central-banks";
+
+/**
+ * Central bank acronyms that are also the symbol of a listing people ask
+ * about (BOE is a NYSE fund, RBI Raiffeisen Bank in Vienna), so `events BOE`
+ * stays that listing's. ECB S.A. in Warsaw is reached as ECB:WSE.
+ */
+const LISTED_SYMBOLS = new Set(["BOE", "BOC", "RBA", "PBOC", "RBI", "BOK"]);
+
+/**
+ * What `events` says for a central bank named on its own ("ECB", "Norges
+ * Bank"): its meetings are no company's corporate events, and CBR has its
+ * rate and the next decision from the bank's own calendar (China's next LPR
+ * fixing; SAMA publishes none). Null for anything else, a symbol with a venue
+ * included.
+ */
+export function centralBankEventsMessage(typed: string): string | null {
+  const bank = centralBankNamed(typed);
+  if (!bank || LISTED_SYMBOLS.has(typed.trim().replace(/^\$/, "").toUpperCase())) return null;
+  const next = bank.id === "US" ? " and the next FOMC date" : bank.id === "CN" ? " and the next LPR fixing"
+    : bank.id === "SA" ? "" : " and the next decision";
+  return `${bank.id === "US" ? "Fed" : bank.short} meetings are not listed; CBR shows the rate${next} (gloomberb fn CBR).`;
+}

package/src/cli/command-options.ts

@@ -4,8 +4,11 @@ import { suggestCliOption } from "./help";
 
 /** A built-in command, which may say more about an option it does not take than the list of those it does. */
 export interface BuiltinCliCommandDef extends CliCommandDef {
-  /** A sentence for an unknown option people reach for, such as `--from` on `history`; null for the rest. */
-  unknownOptionHint?(flag: string): string | null;
+  /**
+   * A sentence for an unknown option people reach for, such as `--from` on
+   * `history`; null for the rest. `args` are the command's, to name what it was given.
+   */
+  unknownOptionHint?(flag: string, args: readonly string[]): string | null;
 }
 
 interface DeclaredOption {
@@ -34,12 +37,21 @@ function declaredOptions(command: CliCommandDef): Map<string, DeclaredOption> |
   return declared;
 }
 
-function failUnknownOption(command: BuiltinCliCommandDef, flag: string, declared: Map<string, DeclaredOption>): never {
+/** `--explain` on a command that has no glossary of its own points at the commands that do, and at the glossary. */
+const EXPLAIN_HINT = "--explain follows the reports of fn <function> and portfolio show. "
+  + "gloomberb catalog explain <term> prints what one term means; gloomberb catalog glossary lists every term.";
+
+function failUnknownOption(
+  command: BuiltinCliCommandDef,
+  flag: string,
+  declared: Map<string, DeclaredOption>,
+  args: readonly string[],
+): never {
   const flags = [...declared.keys()];
   const suggestion = suggestCliOption(flag, flags);
   const help = `See gloomberb help ${command.name}.`;
   fail(`Unknown option ${flag} for ${command.name}.`, [
-    command.unknownOptionHint?.(flag) ?? "",
+    command.unknownOptionHint?.(flag, args) ?? (flag === "--explain" ? EXPLAIN_HINT : ""),
     suggestion ? `Did you mean ${suggestion}?` : "",
     flags.length > 0 ? `Options: ${flags.join(", ")}. ${help}` : `${command.name} takes no options. ${help}`,
   ].filter(Boolean).join("\n"));
@@ -65,7 +77,7 @@ export function checkCliCommandOptions(
     const equals = arg.indexOf("=");
     const flag = equals >= 0 ? arg.slice(0, equals) : arg;
     const option = declared.get(flag);
-    if (!option) failUnknownOption(command, flag, declared);
+    if (!option) failUnknownOption(command, flag, declared, args);
     if (!option.takesValue && equals >= 0) {
       fail(`${flag} takes no value.`, `Write it alone, as ${flag}. See gloomberb help ${command.name}.`);
     }

package/src/cli/commands/crypto-hints.ts

@@ -3,6 +3,8 @@ import { isCryptoVenuePerpetual } from "../../tickers/instrument-kind";
 import type { Quote } from "../../types/financials";
 import { isCryptoPairSymbol } from "../../utils/crypto-pair";
 import { isNotATickerMessage } from "../not-a-ticker";
+import { groupByCompany } from "../../tickers/company-name";
+import type { TickerRecord } from "../../types/ticker";
 
 /** Where a crypto pair that will not load can still be read. `fn CRYP` takes no argument. */
 export const CRYPTO_BOARD_HINT = "Crypto prices may be briefly unavailable; the CRYP function (gloomberb fn CRYP) shows the crypto board.";
@@ -27,9 +29,10 @@ const MAJOR_COINS = new Map([
 /**
  * A bare coin ticker usually resolves to a listed fund, not the coin. The note applies only when
  * the listing is not crypto and its own name says the coin (a "Bitcoin" trust), so a company that
- * happens to share the letters (Interlink Electronics on LINK) is left alone.
+ * happens to share the letters (Interlink Electronics on LINK) is left alone. Every command that
+ * reads a bare symbol as a listing says it: quote, ticker, and the portfolio and watchlist adds.
  */
-function notTheCoinNote(symbol: string, quote: Pick<Quote, "name" | "instrumentType"> | null | undefined): string | null {
+export function notTheCoinNote(symbol: string, quote: Pick<Quote, "name" | "instrumentType"> | null | undefined): string | null {
   const coin = MAJOR_COINS.get(symbol);
   const type = quote?.instrumentType?.trim();
   const name = quote?.name?.trim();
@@ -38,6 +41,29 @@ function notTheCoinNote(symbol: string, quote: Pick<Quote, "name" | "instrumentT
   return `${symbol} is ${name}, not ${coin}. For ${coin} use ${symbol}-USD.`;
 }
 
+/** `notTheCoinNote` for a saved listing, by the name and asset category it was saved with. */
+export function savedListingCoinNote(symbol: string, ticker: Pick<TickerRecord, "metadata">): string | null {
+  return notTheCoinNote(symbol, { name: ticker.metadata.name, instrumentType: ticker.metadata.assetCategory });
+}
+
+/**
+ * A bare coin ticker several companies list asks which listing; when none of them is the coin
+ * (SOL: Solvay, Washington H. Soul Pattinson), the coin is where the user may have meant:
+ * "SOL is Solvay SA or Washington H. Soul Pattinson and Company Limited, not solana. For
+ * solana use SOL-USD." Null for any other symbol, or when a listing is a crypto pair.
+ */
+export function coinElsewhereNote(symbol: string, listings: ReadonlyArray<{ key: string; name: string }>): string | null {
+  const coin = MAJOR_COINS.get(symbol);
+  if (!coin || listings.some((listing) => isCryptoPairSymbol(listing.key))) return null;
+  const names = groupByCompany(listings.filter((listing) => listing.name.trim()), (listing) => listing.name.trim())
+    .map((group) => group[0]!.name.trim());
+  if (names.length === 0) return null;
+  const named = names.length === 1 ? names[0]!
+    : names.length === 2 ? `${names[0]} or ${names[1]}`
+    : `${names[0]}, ${names[1]} or another company`;
+  return `${symbol} is ${named}, not ${coin}. For ${coin} use ${symbol}-USD.`;
+}
+
 interface QuoteNoteResult {
   target: { symbol: string };
   quote: Pick<Quote, "name" | "instrumentType"> | null;

package/src/cli/commands/fred-series.ts

@@ -1,4 +1,6 @@
+import { ICE_SPREAD_SERIES } from "../../time-series/ice-credit";
 import { toBasisPoints } from "../../utils/basis-points";
+import { parseReportTime } from "../../utils/utc-time";
 
 /** Where `fred` starts when `--start` is not given. */
 export const DEFAULT_FRED_START = "2021-01-01";
@@ -9,16 +11,125 @@ export const DEFAULT_FRED_START = "2021-01-01";
  */
 const SPREAD_SERIES: ReadonlySet<string> = new Set([
   "T10Y2Y", "T10Y3M",
-  "BAMLC0A0CM", "BAMLC0A1CAAA", "BAMLC0A2CAA", "BAMLC0A3CA", "BAMLC0A4CBBB", "BAMLH0A0HYM2",
+  ...ICE_SPREAD_SERIES.map((series) => series.seriesId),
 ]);
 
 export function isSpreadSeries(seriesId: string): boolean {
   return SPREAD_SERIES.has(seriesId.toUpperCase());
 }
 
-/** A spread in percentage points as the bp a text table prints: 0.44 is `44`, -0.125 is `-12.5`. */
-export function spreadBasisPointsCell(value: unknown): string {
-  return typeof value === "number" && Number.isFinite(value) ? String(toBasisPoints(value, 1)) : "";
+/**
+ * The unit a series' observations export in, for the `currency_or_unit`
+ * column beside its bare `value`: `bp` for a spread (exported in basis
+ * points), `pct` for a percent, otherwise FRED's own units, with "annual
+ * rate" as the text header says it. Null when FRED's metadata did not come
+ * back.
+ */
+export function fredUnit(seriesId: string, info: { units?: string | null; seasonalAdjustment?: string | null } | null | undefined): string | null {
+  if (isSpreadSeries(seriesId)) return "bp";
+  const units = info?.units?.trim();
+  if (!units) return null;
+  if (/^percent$/i.test(units)) return "pct";
+  const annualRate = /annual rate/i.test(info?.seasonalAdjustment ?? "") && !/annual rate/i.test(units);
+  return `${units}${annualRate ? ", annual rate" : ""}`;
+}
+
+/** How often a series observes, in FRED's word lower-cased: `Weekly, Ending Friday` is `weekly`. Null when FRED does not say. */
+export function fredInterval(frequency: string | null | undefined): string | null {
+  const word = frequency?.split(",")[0]?.trim().toLowerCase();
+  return word || null;
+}
+
+/**
+ * The observations from the series' first one on: Gloom Cloud answers a
+ * `--start` before a series begins with a blank row for every day in between
+ * (DEXSFUS from 1975 has five years of them before 1980-01-02). FRED's
+ * `observationStart` says where it begins; without it the blank rows before
+ * the first value go. Blank rows after it (a holiday's ".") stay.
+ */
+export function fredObservationsFromStart<T extends { date: string; value: number | null }>(
+  observations: readonly T[],
+  seriesStart: string | null | undefined,
+): T[] {
+  const first = seriesStart && /^\d{4}-\d{2}-\d{2}$/.test(seriesStart)
+    ? seriesStart
+    : observations.reduce<string | null>((earliest, observation) => (
+      observation.value != null && Number.isFinite(observation.value) && (!earliest || observation.date < earliest) ? observation.date : earliest
+    ), null);
+  return first ? observations.filter((observation) => observation.date >= first) : [...observations];
+}
+
+/**
+ * The value column's header: FRED's units, and "annual rate" when a monthly or
+ * quarterly flow is stated at a seasonally adjusted annual rate (GDP, FDEFX),
+ * so a quarter's 1,100 billion does not read as spent in that quarter.
+ */
+export function fredValueHeader(info: { units?: string | null; seasonalAdjustment?: string | null } | null | undefined): string {
+  const units = info?.units?.trim();
+  if (!units) return "Value";
+  const annualRate = /annual rate/i.test(info?.seasonalAdjustment ?? "") && !/annual rate/i.test(units);
+  return `Value (${units}${annualRate ? ", annual rate" : ""})`;
+}
+
+/** An observation in the unit it exports in: a spread's percentage points as basis points (3.15 is 315), anything else as FRED gives it. */
+export function fredExportValue(seriesId: string, value: number | null): number | null {
+  if (value == null || !Number.isFinite(value)) return null;
+  return isSpreadSeries(seriesId) ? toBasisPoints(value, 4) : value;
+}
+
+/** Basis points as a text table prints them, to a tenth: 44 is `44`, -12.5 is `-12.5`. */
+export function basisPointsCell(value: unknown): string {
+  if (typeof value !== "number" || !Number.isFinite(value)) return "";
+  const rounded = Math.round(value * 10) / 10;
+  return String(rounded === 0 ? 0 : rounded);
+}
+
+/**
+ * When FRED last updated a series, its `last_updated` (`2026-10-09 08:08:04-05`),
+ * as an ISO instant in UTC: the publication time an export cites. Only when
+ * that update covers the newest observation shown (`observationEnd` reaches
+ * it): metadata from before it says nothing about when it was published.
+ * Null when it does not, or when FRED's metadata does not say.
+ */
+export function fredPublicationTime(
+  info: { lastUpdated?: string | null; observationEnd?: string | null } | null | undefined,
+  newestDate: string | null | undefined,
+): string | null {
+  if (newestDate && !(info?.observationEnd && info.observationEnd >= newestDate)) return null;
+  const iso = (info?.lastUpdated ?? "").trim().replace(/^(\d{4}-\d{2}-\d{2}) /, "$1T").replace(/([+-]\d{2})$/, "$1:00");
+  const time = parseReportTime(iso);
+  return time && !time.dateOnly ? new Date(time.time).toISOString() : null;
+}
+
+/** Where a FRED report's figures come from, as its source line names them. */
+export interface FredProvenance {
+  source: string;
+  publisher?: string;
+  publishedAt?: string;
+}
+
+/**
+ * Where the newest of these observations comes from: FRED, unless Gloom
+ * Cloud carried a value FRED does not list yet and named its publisher. Then
+ * the source line names that publisher and when it published, so a reader
+ * looking for the figure in FRED's own data knows it is not there yet:
+ * `U.S. Treasury via FRED, published 2026-10-09`. Null for FRED's own.
+ */
+export function fredProvenance(observations: ReadonlyArray<{ date: string; publisher?: string; publishedAt?: string }>): FredProvenance | null {
+  const ahead = observations.filter((observation) => observation.publisher?.trim());
+  if (ahead.length === 0) return null;
+  const publishers = [...new Set(ahead.map((observation) => observation.publisher!.trim()))];
+  const times = ahead.flatMap((observation) => {
+    const time = parseReportTime(observation.publishedAt);
+    return time ? [new Date(time.time).toISOString()] : [];
+  }).sort();
+  const publishedAt = times.at(-1);
+  const publisher = publishers.join(" and ");
+  return {
+    source: `${publisher} via FRED${publishedAt ? `, published ${publishedAt.slice(0, 10)}` : ""}`,
+    publisher,
+    ...(publishedAt ? { publishedAt } : {}),
+  };
 }
 
 /**
@@ -59,3 +170,43 @@ export function fredEmptyMessage(startDate: string, latest: { date: string; valu
     ? `Latest observation: ${latest.date}${latest.value == null ? "" : ` (${latest.value})`}. Nothing on or after ${startDate}.`
     : "No results.";
 }
+
+/** What an export of nothing on or after `--start` says to try instead: a start that reaches the latest observation. */
+export function fredEmptyAdvice(seriesId: string, latest: { date: string } | null): string {
+  return latest
+    ? `Latest observation: ${latest.date}. Try: gloomberb fred ${seriesId} --start ${latest.date.slice(0, 4)}`
+    : `No observations came back for ${seriesId}. Try an earlier --start, or gloomberb fred --list for the series served.`;
+}
+
+/** A series as `fred --list` shows it. */
+export interface FredListRow {
+  id: string;
+  title: string;
+  group: string;
+}
+
+/** How well a word of the filter matches a series, best first: its id or group name, a word of its group or title, the start of its id, then any text. */
+function matchTier(term: string, row: FredListRow, words: readonly string[]): number {
+  if (row.id.toLowerCase() === term || row.group.toLowerCase() === term) return 0;
+  if (words.some((word) => word.startsWith(term))) return 1;
+  if (row.id.toLowerCase().startsWith(term)) return 2;
+  return 3;
+}
+
+/**
+ * The series that carry every word of the filter in their id, title or group,
+ * the ones it names first: a group or a word of the title ahead of the id that
+ * only has it inside (`fx` is the FX group, not FDEFX, whose id spells it).
+ * Catalog order breaks ties; an empty filter keeps the catalog as it is.
+ */
+export function filterFredSeries(rows: readonly FredListRow[], filter: string): FredListRow[] {
+  const terms = filter.toLowerCase().split(/\s+/).filter(Boolean);
+  const ranked = rows.flatMap((row, index) => {
+    const text = `${row.id} ${row.title} ${row.group}`.toLowerCase();
+    if (!terms.every((term) => text.includes(term))) return [];
+    const words = `${row.title} ${row.group}`.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+    const tiers = terms.map((term) => matchTier(term, row, words));
+    return [{ row, index, worst: Math.max(0, ...tiers), total: tiers.reduce((sum, tier) => sum + tier, 0) }];
+  });
+  return ranked.sort((a, b) => a.worst - b.worst || a.total - b.total || a.index - b.index).map((entry) => entry.row);
+}