gloomberb 0.16.6 → 0.17.0

package/src/cli/history-rows.ts

@@ -15,6 +15,7 @@ import { currencyUnitLabel } from "../utils/currency-units";
 import { getPricePointTimestamp } from "../utils/price-history";
 import { pricePointIntegrityFlags, pricePointValues } from "../utils/price-history-integrity";
 import { formatUtcTime } from "../utils/utc-time";
+import { historyCoverageNotice } from "../sources/history-coverage";
 
 const PRICE_KEYS = ["open", "high", "low", "close"] as const;
 const DAY_MS = 24 * 60 * 60 * 1000;
@@ -24,6 +25,13 @@ const INTRADAY_RESOLUTIONS = ["1m", "5m", "15m", "30m", "45m", "1h"] as const;
 /** A first bar later than this after the range's start is a late start, not a weekend or holiday. */
 const LATE_START_MIN_MS = 10 * DAY_MS;
 const LATE_START_MIN_BARS = 3;
+/** A bar with more than this many calendar periods (`barPeriod`) since the one before follows a gap in the series. */
+const BREAK_GAP_PERIODS = 3;
+/** A close more than this many times the close before it, or less than its hundredth, follows a jump. */
+const BREAK_JUMP_RATIO = 100;
+/** Flag codes for a break before a bar, whose prices stay as served; every other code blanks them. */
+const BREAK_FLAGS: ReadonlySet<string> = new Set(["gap", "jump"]);
+const FIRST_MONDAY_MS = Date.UTC(1970, 0, 5);
 
 const BAR_INTERVAL_LABELS: Record<ManualChartResolution, string> = {
   "1m": "1-minute",
@@ -50,7 +58,10 @@ export interface HistoryRow {
   unit: string | null;
   /** Bar size, in the codes of `resolution`: 5m, 1h, 1d, 1wk, 1mo. */
   interval: ManualChartResolution | null;
-  /** Each way the bar's prices contradict each other, such as `high<open`; null when they agree. */
+  /**
+   * Each way the bar's prices contradict each other, such as `high<open`, and
+   * `gap` or `jump` for a break in the series just before it; null when none.
+   */
   flag: string | null;
   /** The bar's period had not ended when it was served: the close is the latest price. */
   partial?: true;
@@ -122,10 +133,59 @@ function historyInterval(times: readonly number[], resolution: ManualChartResolu
   return days >= 25 ? "1mo" : days >= 6 ? "1wk" : "1d";
 }
 
+/**
+ * The calendar period a bar falls in, numbered so that consecutive periods
+ * differ by one: its month for monthly bars, its week (Monday to Sunday, UTC)
+ * for weekly and anything finer. Daily and intraday bars are counted in weeks
+ * because a market's own closures leave holes that are no break in the
+ * series: nights, weekends, holidays (Lunar New Year and Golden Week close
+ * Chinese markets for up to nine days, Eid the Gulf markets about as long),
+ * and a thin listing that goes a week or two without a trade. A daily series
+ * then breaks exactly where its weekly bars would.
+ */
+function barPeriod(time: number, interval: ManualChartResolution): number {
+  if (interval !== "1mo") return Math.floor((time - FIRST_MONDAY_MS) / (7 * DAY_MS));
+  const date = new Date(time);
+  return date.getUTCFullYear() * 12 + date.getUTCMonth();
+}
+
+/**
+ * The breaks before each bar: `gap` after more than three calendar periods
+ * with no bar (`barPeriod`), `jump` when its close is over 100 times the last
+ * close before it, or under a hundredth of it. Closes that are blank, zero or
+ * negative are skipped.
+ */
+function historyBreakFlags(
+  times: readonly number[],
+  closes: readonly (number | null)[],
+  interval: ManualChartResolution | null,
+): string[][] {
+  let previousTime: number | null = null;
+  let previousClose: number | null = null;
+  return times.map((time, index) => {
+    const flags: string[] = [];
+    if (interval && Number.isFinite(time)) {
+      if (previousTime != null && barPeriod(time, interval) - barPeriod(previousTime, interval) > BREAK_GAP_PERIODS) flags.push("gap");
+      previousTime = time;
+    }
+    const close = closes[index];
+    if (close != null && close > 0) {
+      if (previousClose != null && Math.max(close / previousClose, previousClose / close) > BREAK_JUMP_RATIO) flags.push("jump");
+      previousClose = close;
+    }
+    return flags;
+  });
+}
+
+function flagCodes(row: Pick<HistoryRow, "flag">): string[] {
+  return row.flag ? row.flag.split(",") : [];
+}
+
 /**
  * Intraday bars keep their UTC time; daily and longer bars are trading dates.
  * A bar whose prices contradict each other is blanked exactly as HP blanks it,
- * and says why in `flag`.
+ * and says why in `flag`. A bar after a gap or a jump in the series keeps its
+ * prices and is flagged `gap` or `jump`.
  */
 export function historyRows(
   points: readonly PricePoint[],
@@ -137,7 +197,7 @@ export function historyRows(
   const times = points.map(getPricePointTimestamp);
   const intraday = resolution ? isIntradayResolution(resolution) : looksIntraday(times);
   const interval = historyInterval(times, resolution);
-  return points.map((point, index) => {
+  const rows = points.map((point, index) => {
     const time = times[index]!;
     const iso = Number.isFinite(time) ? new Date(time).toISOString() : "";
     const values = pricePointValues(point);
@@ -163,6 +223,11 @@ export function historyRows(
         : {}),
     };
   });
+  const breaks = historyBreakFlags(times, rows.map((row) => row.close), interval);
+  return rows.map((row, index) => {
+    const flags = [...flagCodes(row), ...breaks[index]!];
+    return flags.length > 0 ? { ...row, flag: flags.join(",") } : row;
+  });
 }
 
 /**
@@ -292,16 +357,28 @@ function historyDate(value: string): string {
   return value.length > 10 ? formatUtcTime(value) : value;
 }
 
-/** The facts line under a history heading: "Currency USD", "daily bars", "2025-10-09 to 2026-10-08", "251 bars". */
-export function historyFacts(unit: HistoryUnit, rows: readonly Pick<HistoryRow, "date" | "interval">[]): string[] {
+/** The first bar after the series' last gap or jump, which reads on without a break; null when it has none. */
+export function historyUnbrokenFrom(rows: readonly Pick<HistoryRow, "date" | "flag">[]): string | null {
+  const last = rows.findLastIndex((row) => flagCodes(row).some((code) => BREAK_FLAGS.has(code)));
+  return last >= 0 ? rows[last]!.date : null;
+}
+
+/**
+ * The facts line under a history heading: "Currency USD", "daily bars",
+ * "2025-10-09 to 2026-10-08", "251 bars", and "unbroken from 1992-12-01"
+ * after a gap or jump.
+ */
+export function historyFacts(unit: HistoryUnit, rows: readonly Pick<HistoryRow, "date" | "interval" | "flag">[]): string[] {
   const first = rows[0]?.date;
   const last = rows.at(-1)?.date;
   const interval = rows[0]?.interval;
+  const unbroken = historyUnbrokenFrom(rows);
   return [
     unit.kind === "pair" ? unit.unit! : unit.kind === "points" ? "Index points" : `Currency ${unit.unit ?? "unknown"}`,
     interval ? `${BAR_INTERVAL_LABELS[interval]} bars` : "",
     first && last ? (first === last ? historyDate(first) : `${historyDate(first)} to ${historyDate(last)}`) : "",
     `${rows.length} ${rows.length === 1 ? "bar" : "bars"}`,
+    unbroken ? `unbroken from ${historyDate(unbroken)}` : "",
   ].filter(Boolean);
 }
 
@@ -333,22 +410,102 @@ export function historyNotes(
   return notes;
 }
 
+/**
+ * "Price history starts 1992-12-01; old-shekel quotes before 1992 are not
+ * served.": the source serves nothing before a date the range reaches back
+ * past, and why when it says. Null for a range that starts after it.
+ */
+export function historyCoverageWarning(
+  range: TimeRange,
+  coverage: { coverageStart?: string; coverageNote?: string },
+  now = Date.now(),
+): string | null {
+  return historyCoverageNotice(coverage.coverageStart, subtractTimeRange(new Date(now), range).getTime(), coverage.coverageNote);
+}
+
 /** Gaps listed by date before the rest are only counted. */
 const LISTED_GAPS = 3;
 
+function listItems(items: readonly string[]): string {
+  return items.length > 1 ? `${items.slice(0, -1).join(", ")} and ${items.at(-1)}` : items[0] ?? "";
+}
+
+function utcDay(time: number): string {
+  return new Date(time).toISOString().slice(0, 10);
+}
+
+/** The bars flagged `code`, each with the bar before it. */
+function breaksFlagged<Row extends Pick<HistoryRow, "flag">>(rows: readonly Row[], code: string): Array<[Row, Row]> {
+  return rows.flatMap((row, index) => index > 0 && flagCodes(row).includes(code) ? [[rows[index - 1]!, row] as [Row, Row]] : []);
+}
+
+/**
+ * "No bars for 1980-08 to 1992-11 (148 months)": the periods with no bar
+ * before each bar flagged `gap`, the latest few by date and the rest counted.
+ */
+function historyBreakGapNote(rows: readonly Pick<HistoryRow, "date" | "interval" | "flag">[]): string | null {
+  const interval = rows[0]?.interval;
+  const gaps = interval ? breaksFlagged(rows, "gap") : [];
+  if (!interval || gaps.length === 0) return null;
+  const monthly = interval === "1mo";
+  const spans = gaps.map(([before, after]) => {
+    const [from, to] = [Date.parse(before.date), Date.parse(after.date)];
+    const periods = barPeriod(to, interval) - barPeriod(from, interval) - 1;
+    const length = `${periods} ${monthly ? "month" : "week"}${periods === 1 ? "" : "s"}`;
+    if (monthly) {
+      const month = (time: number, step: number) => {
+        const date = new Date(time);
+        return utcDay(Date.UTC(date.getUTCFullYear(), date.getUTCMonth() + step, 1)).slice(0, 7);
+      };
+      return `${month(from, 1)} to ${month(to, -1)} (${length})`;
+    }
+    return `${utcDay(from + (interval === "1wk" ? 7 : 1) * DAY_MS)} to ${utcDay(to - DAY_MS)} (${length})`;
+  });
+  const shown = spans.slice(-LISTED_GAPS);
+  const earlier = spans.length - shown.length;
+  return `No bars for ${listItems([...earlier > 0 ? [`${earlier} earlier ${earlier === 1 ? "gap" : "gaps"}`] : [], ...shown])}`;
+}
+
+const closeFormat = new Intl.NumberFormat("en-US", { maximumSignificantDigits: 7, useGrouping: false });
+
+/**
+ * "Close rises 564x from 0.0049 on 1980-07-01 to 2.763 on 1992-12-01": each
+ * bar flagged `jump`, against the last close before it. Neutral on the cause,
+ * which can be a change of unit, a different series or a real collapse.
+ */
+export function historyJumpNote(rows: readonly Pick<HistoryRow, "date" | "close" | "flag">[]): string | null {
+  const jumps: string[] = [];
+  let previous: { date: string; close: number } | null = null;
+  for (const row of rows) {
+    if (row.close == null || !(row.close > 0)) continue;
+    if (previous && flagCodes(row).includes("jump")) {
+      const rises = row.close > previous.close;
+      const ratio = Math.round(rises ? row.close / previous.close : previous.close / row.close).toLocaleString("en-US");
+      jumps.push(`${rises ? "rises" : "falls"} ${ratio}x from ${closeFormat.format(previous.close)} on ${historyDate(previous.date)}`
+        + ` to ${closeFormat.format(row.close)} on ${historyDate(row.date)}`);
+    }
+    previous = { date: row.date, close: row.close };
+  }
+  if (jumps.length === 0) return null;
+  const shown = jumps.slice(-LISTED_GAPS);
+  const earlier = jumps.length - shown.length;
+  return `Close ${earlier > 0 ? `jumps over 100x at ${earlier} earlier ${earlier === 1 ? "bar" : "bars"}, then ` : ""}${listItems(shown)}`;
+}
+
 /**
  * "No bar for 2026-10-10": the days a coin, which trades every day, has no
  * daily bar for between its first and last bar. Days before the first bar are
  * before the listing. A market that closes skips weekends and holidays, so its
- * gaps say nothing and get no note.
+ * gaps say nothing on their own: for it, and for a coin's other bar sizes, the
+ * note names the gaps flagged `gap`, "No bars for 1980-08 to 1992-11 (148 months)".
  */
 export function historyGapNote(
-  rows: readonly Pick<HistoryRow, "date" | "interval">[],
+  rows: readonly Pick<HistoryRow, "date" | "interval" | "flag">[],
   market: { listing: string; exchange?: string; instrumentType?: string },
 ): string | null {
   const everyDay = isRoundTheClockCoin(market.listing, market.exchange)
     || classifyInstrumentType(market.instrumentType) === "crypto";
-  if (!everyDay || rows[0]?.interval !== "1d") return null;
+  if (!everyDay || rows[0]?.interval !== "1d") return historyBreakGapNote(rows);
   const days = new Set(rows.map((row) => Date.parse(`${row.date.slice(0, 10)}T00:00:00Z`)).filter(Number.isFinite));
   const sorted = [...days].sort((left, right) => left - right);
   const gaps: Array<[number, number]> = [];
@@ -366,15 +523,19 @@ export function historyGapNote(
     ...earlier > 0 ? [`${earlier} earlier ${earlier === 1 ? "day" : "days"}`] : [],
     ...shown.map(([from, to]) => from === to ? date(from) : `${date(from)} to ${date(to)}`),
   ];
-  const list = listed.length > 1 ? `${listed.slice(0, -1).join(", ")} and ${listed.at(-1)}` : listed[0];
-  return `${length(gaps) === 1 ? "No bar" : "No bars"} for ${list}`;
+  return `${length(gaps) === 1 ? "No bar" : "No bars"} for ${listItems(listed)}`;
 }
 
-/** "37 of 251 bars have high below open or close in the source data; ...", or null when every bar agrees. */
+/**
+ * "37 of 251 bars have high below open or close in the source data; ...", or
+ * null when every bar agrees. Bars flagged only for a gap or jump before them
+ * keep their prices and are not counted.
+ */
 export function historyFlagNote(rows: readonly Pick<HistoryRow, "flag">[]): string | null {
-  const flagged = rows.filter((row) => row.flag);
+  const contradictions = (row: Pick<HistoryRow, "flag">) => flagCodes(row).filter((code) => !BREAK_FLAGS.has(code));
+  const flagged = rows.filter((row) => contradictions(row).length > 0);
   if (flagged.length === 0) return null;
-  const codes = new Set(flagged.flatMap((row) => row.flag!.split(",")));
+  const codes = new Set(flagged.flatMap(contradictions));
   const kinds = [
     codes.has("high<open") || codes.has("high<close") ? "high below open or close" : "",
     codes.has("low>open") || codes.has("low>close") ? "low above open or close" : "",

package/src/cli/known-gaps.ts

@@ -1,10 +1,16 @@
 /**
  * Where data finer than a minute is: nowhere as bars. GIP draws 1-minute
- * bars and QR lists each trade, timestamped to the millisecond.
+ * bars, and QR lists each trade of a US listing. `history --interval`, GIP's
+ * `--chartResolution 1s` and QR on a listing abroad all say this.
  */
 export function subMinuteDataMessage(symbol = "<ticker>"): string {
-  return `No second or tick bars; spread series are daily. 1-minute bars: gloomberb fn GIP ${symbol}. `
-    + `Individual trades with ms timestamps: gloomberb fn QR ${symbol}.`;
+  return `No second or tick bars; 1-minute bars: fn GIP ${symbol}; trades exist for US listings only.`;
+}
+
+/** A bar size finer than a minute, as people type one: 1s, 30s, 5sec, 500ms, tick, ticks, tick-by-tick, seconds. */
+export function isSubMinuteInterval(value: string): boolean {
+  return /^(\d+(\.\d+)?\s*(ms|msecs?|millis(econds?)?|s|secs?|seconds?)|\d*\s*ticks?|tick[\s-]*by[\s-]*tick|seconds?|sub[\s-]*(minute|second)s?)$/i
+    .test(value.trim());
 }
 
 /**
@@ -22,6 +28,11 @@ const KNOWN_GAPS: ReadonlyArray<{ terms: readonly string[]; message: string }> =
       "carbon price", "carbon prices", "carbon credits", "emission allowances", "emissions allowances"],
     message: "EU carbon (EUA): the auction price is in EPWR, chart CAP:carbon:eua. Traded proxies: CO2:LSE, KRBN.",
   },
+  {
+    terms: ["EU gas storage", "European gas storage", "Europe gas storage", "EU gas inventories", "European gas inventories",
+      "AGSI", "AGSI+", "GIE AGSI", "gas storage Europe"],
+    message: "European gas storage: EPWR GAS, or EPWR GAS DE for one country; chart CAP:gas-storage:eu. US storage is NGS.",
+  },
   {
     terms: ["tick", "ticks", "tick data", "tick bars", "tick by tick", "second", "seconds", "second bars", "1s", "1 second",
       "1 second bars", "sub-minute", "sub minute bars", "subsecond"],

package/src/cli/listing-arg.ts

@@ -3,7 +3,15 @@ import type { Quote } from "../types/financials";
 import type { CliCommandContext } from "../types/plugin";
 import type { TickerRecord } from "../types/ticker";
 import { perpetualListingOfMarket, typedPerpetualListing } from "../tickers/perpetual-listing";
-import { listingVenues, quotedOnVenue, readSharedCode, type ListingDeps, type ListingStore, type ListingVenue } from "../tickers/listing-venues";
+import {
+  listingVenues,
+  quotedOnVenue,
+  readAmbiguousCurrencyPair,
+  readSharedCode,
+  type ListingDeps,
+  type ListingStore,
+  type ListingVenue,
+} from "../tickers/listing-venues";
 import { findUsListingOfCompany, type UsListing } from "../tickers/us-listing";
 import {
   describeTickerChange,
@@ -33,6 +41,7 @@ import {
 import { withMarketData } from "./scoped-context";
 import { isNoProviderMessage } from "../sources/provider-errors";
 import { dashedCoinPair } from "../utils/crypto-pair";
+import { currencyPairSpelling } from "../utils/currency-pair";
 import { isQuoteStaleForCurrentSession } from "../market-data/quotes/freshness";
 import { formatMarketPriceWithCurrency, quoteFormatOptions } from "../market-data/market/format";
 import { zonedDateKey } from "../utils/zoned-date-time";
@@ -75,7 +84,11 @@ export interface ListingArg {
  * the command takes several symbols and `--exchange` only fills in the ones
  * without an exchange of their own. A code that names several venues (TSE)
  * agrees with any of them. A futures board code no listed security uses is
- * its future: TTF is TTF=F, while NG stays NovaGold.
+ * its future: TTF is TTF=F, while NG stays NovaGold. A currency pair is the
+ * one listing the service has for it, however it is written: EUR/USD,
+ * EURUSD:CCY and JPY=X are EURUSD=X and USDJPY=X, so every spelling asks for
+ * the same quote. USD-NGN and USDNGN could be a security's symbol, so
+ * `resolveCliListing` asks search before reading them as USDNGN=X.
  */
 export function parseListingArg(
   raw: string,
@@ -106,6 +119,8 @@ export function parseListingArg(
     // TSE and --exchange JPX agree on Tokyo.
     if (agreed.length === 1) [exchange, code] = [agreed[0]!, agreed[0]!];
   }
+  const pair = currencyPairSpelling(parsed.symbol, exchange);
+  if (pair && !pair.ambiguous) return { symbol: pair.symbol, exchange: "", key: pair.symbol };
   const shared = isSharedExchangeCode(code) ? { sharedCode: code } : {};
   if (exchange) return { symbol: parsed.symbol, exchange, key: `${parsed.symbol}:${exchange}`, ...shared };
   // A futures board code no security uses is its future: TTF is TTF=F.
@@ -855,6 +870,9 @@ export async function resolveCliListing(
 ): Promise<CliListing> {
   let parsed = parseListingArg(raw, exchangeOption, options);
   if (!parsed.symbol) throw new ListingArgError("Ticker symbol is required.");
+  // USD-NGN and USDNGN are the pair USDNGN=X unless a security is listed under those letters.
+  const pair = parsed.exchange ? null : await readAmbiguousCurrencyPair(parsed.symbol, deps);
+  if (pair) parsed = { symbol: pair, exchange: "", key: pair };
   try {
     await checkListingExchange(parsed, deps);
   } catch (error) {

package/src/cli/listing-suggestion.ts

@@ -0,0 +1,159 @@
+import type { DataProvider } from "../types/data-provider";
+import type { TickerRecord } from "../types/ticker";
+import { LISTING_SEARCH_LIMIT, searchTickerCandidates, type TickerSearchCandidate } from "../tickers/search";
+import { mapWithConcurrency } from "../utils/concurrency";
+import { TickerNotFoundError } from "./ticker-resolution";
+
+/** How long a suggestion waits for search; a slow search leaves the plain "not found" as it was. */
+const SUGGESTION_TIMEOUT_MS = 6_000;
+/** Searches in flight at once while a list's missing symbols are looked up. */
+const SUGGESTION_CONCURRENCY = 4;
+/** A list with more missing symbols than this is an import with stale codes, not a typo; it gets no suggestions and no extra searches. */
+export const MAX_SUGGESTED_SYMBOLS = 10;
+/** Symbols shorter than this are too short for one edit to leave them recognisable. */
+const MIN_TYPO_LENGTH = 4;
+
+export interface ListingSuggestion {
+  /** The listing as `search` prints it: USDNGN=X. */
+  symbol: string;
+  name: string;
+}
+
+interface SuggestionDeps {
+  store: { loadAllTickers(): Promise<TickerRecord[]> };
+  dataProvider: DataProvider;
+  /** Replaces the search, for a caller that already has the candidates. */
+  search?: (query: string) => Promise<TickerSearchCandidate[]>;
+  timeoutMs?: number;
+}
+
+/** The text of a symbol or a name with its case, spaces, punctuation and a leading `$` gone: `USD-NGN` and `USD/NGN` are `USDNGN`. */
+function compact(text: string): string {
+  return text.toUpperCase().replace(/[^\p{L}\p{N}]/gu, "");
+}
+
+/** A symbol as people type it: without the `=X` or `=F` a pair or a future carries, and without its venue (`BTCUSDT:BYBIT`). */
+function typedForm(symbol: string): string {
+  return compact(symbol.split(":")[0]!.replace(/=[A-Z]?$/i, ""));
+}
+
+/** The edits (insert, delete, replace, swap two neighbours) between two strings, up to two; anything further apart is 2. */
+function editDistance(left: string, right: string): number {
+  if (left === right) return 0;
+  if (Math.abs(left.length - right.length) > 1) return 2;
+  const rows: number[][] = Array.from({ length: left.length + 1 }, (_, row) => [row, ...new Array<number>(right.length).fill(0)]);
+  for (let column = 1; column <= right.length; column += 1) rows[0]![column] = column;
+  for (let row = 1; row <= left.length; row += 1) {
+    for (let column = 1; column <= right.length; column += 1) {
+      const same = left[row - 1] === right[column - 1] ? 0 : 1;
+      let best = Math.min(rows[row - 1]![column]! + 1, rows[row]![column - 1]! + 1, rows[row - 1]![column - 1]! + same);
+      if (row > 1 && column > 1 && left[row - 1] === right[column - 2] && left[row - 2] === right[column - 1]) {
+        best = Math.min(best, rows[row - 2]![column - 2]! + 1);
+      }
+      rows[row]![column] = best;
+    }
+  }
+  return rows[left.length]![right.length]!;
+}
+
+function candidateName(candidate: TickerSearchCandidate): string {
+  return candidate.detail.split(" | ")[0]?.trim() ?? "";
+}
+
+/** 0 when the candidate is the typed symbol with other punctuation (`USD_NGN` for `USDNGN=X`) or named so, 1 for one slip of the keys, null for anything else. */
+function nearness(typed: string, candidate: TickerSearchCandidate): number | null {
+  const wanted = compact(typed);
+  if (!wanted) return null;
+  const symbol = typedForm(candidate.label || candidate.symbol);
+  if (wanted === symbol || wanted === compact(candidateName(candidate))) return 0;
+  return wanted.length >= MIN_TYPO_LENGTH && symbol.length >= MIN_TYPO_LENGTH && editDistance(wanted, symbol) === 1 ? 1 : null;
+}
+
+/**
+ * The search hit a symbol that was not found most likely meant, or null.
+ * Only a real near match counts: the same letters and digits with other
+ * punctuation, or one slip in a symbol of four characters or more. The first
+ * result is never taken for being first, and a tie between different symbols
+ * is no suggestion at all.
+ */
+export function nearestListing(typed: string, candidates: readonly TickerSearchCandidate[]): ListingSuggestion | null {
+  const typedKey = typed.trim().replace(/^\$/, "").toUpperCase();
+  const near = candidates
+    .filter((candidate) => (candidate.label || candidate.symbol).toUpperCase() !== typedKey)
+    .flatMap((candidate) => {
+      const tier = nearness(typed, candidate);
+      return tier == null ? [] : [{ candidate, tier }];
+    });
+  if (near.length === 0) return null;
+  const best = Math.min(...near.map((entry) => entry.tier));
+  const top = near.filter((entry) => entry.tier === best).map((entry) => entry.candidate);
+  if (new Set(top.map((candidate) => typedForm(candidate.label || candidate.symbol))).size > 1) return null;
+  const first = top[0]!;
+  return { symbol: first.label || first.symbol, name: candidateName(first) };
+}
+
+/** The suggestion as a line says it: `USDNGN=X (US Dollar/Nigerian Naira)`. */
+export function describeSuggestion({ symbol, name }: ListingSuggestion): string {
+  return name && name.toUpperCase() !== symbol.toUpperCase() ? `${symbol} (${name})` : symbol;
+}
+
+/** The search the `search` command runs for a query: saved tickers and the data service's matches, as many as it lists. */
+async function searchAsCommand(query: string, { store, dataProvider }: SuggestionDeps): Promise<TickerSearchCandidate[]> {
+  const tickers = new Map((await store.loadAllTickers()).map((ticker) => [ticker.metadata.ticker.toUpperCase(), ticker] as const));
+  return searchTickerCandidates({
+    query,
+    tickers,
+    dataProvider,
+    localLimit: 6,
+    totalLimit: LISTING_SEARCH_LIMIT,
+    searchContext: { limit: LISTING_SEARCH_LIMIT },
+  });
+}
+
+/**
+ * The listing search finds for a symbol that resolved to nothing, when it is a
+ * near match; null when search finds nothing near, fails or is slow. It never
+ * throws and never waits longer than the timeout.
+ */
+export async function suggestListing(input: string, deps: SuggestionDeps): Promise<ListingSuggestion | null> {
+  const query = input.trim().replace(/^\$/, "");
+  if (!query) return null;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const candidates = await Promise.race([
+      Promise.resolve().then(() => (deps.search ?? ((text: string) => searchAsCommand(text, deps)))(query)),
+      new Promise<null>((resolve) => { timer = setTimeout(() => resolve(null), deps.timeoutMs ?? SUGGESTION_TIMEOUT_MS); }),
+    ]);
+    return candidates ? nearestListing(query, candidates) : null;
+  } catch {
+    return null;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/** The answer for a symbol search lists nothing for, with nothing else said (a company that left its symbol, a wrong exchange, a stopped listing each say more). */
+const PLAIN_NO_MATCH = /^No ticker match found for ".*"\.$/s;
+
+/** Whether the message is the plain no-match answer, the one a suggestion can sit beside. */
+export function isPlainNoMatch(message: string | null | undefined): boolean {
+  return message != null && PLAIN_NO_MATCH.test(message);
+}
+
+/**
+ * The error a single symbol failed with, and when it is search finding no
+ * listing for the symbol, that error with the nearest listing named in its
+ * message: `No ticker match found for "USD_NGN"; did you mean USDNGN=X (US
+ * Dollar/Nigerian Naira)?`. Any other error comes back as it is.
+ */
+export async function withSuggestion(error: unknown, input: string, deps: SuggestionDeps): Promise<unknown> {
+  if (!(error instanceof TickerNotFoundError) || !isPlainNoMatch(error.message)) return error;
+  const suggestion = await suggestListing(input, deps);
+  return suggestion ? new TickerNotFoundError(`${error.message.replace(/\.$/, "")}; did you mean ${describeSuggestion(suggestion)}?`) : error;
+}
+
+/** The suggestion of each input, null where there is none; none at all for more than `MAX_SUGGESTED_SYMBOLS`. */
+export async function suggestListings(inputs: readonly string[], deps: SuggestionDeps): Promise<Array<ListingSuggestion | null>> {
+  if (inputs.length > MAX_SUGGESTED_SYMBOLS) return inputs.map(() => null);
+  return mapWithConcurrency(inputs, SUGGESTION_CONCURRENCY, (input) => suggestListing(input, deps));
+}

package/src/cli/native-smoke.ts

@@ -26,3 +26,16 @@ export async function smokePluginHost(): Promise<void> {
   const { smokePluginHostLoad } = await import("../plugins/host-smoke");
   await smokePluginHostLoad();
 }
+
+export const SHOT_VIEW_SMOKE_COMMAND = "__gloomberb-smoke-shot-view";
+
+/**
+ * Reads the page `shot` and rendered `fn` reports draw panes in. The release
+ * binary has no sources to build it from, so it carries a prebuilt copy; run
+ * from outside a checkout, this fails when that copy is missing or incomplete
+ * rather than on a user's first capture.
+ */
+export async function smokeShotView(): Promise<void> {
+  const { loadShotView } = await import("./desktop-pane-shot-view");
+  await loadShotView();
+}

package/src/cli/not-a-ticker.ts

@@ -2,7 +2,8 @@ import { notATickerSymbol } from "../sources/provider-errors";
 import { splitSymbolArgs } from "./symbol-args";
 
 // "Not a ticker: APPLE." as the router words it; the symbol ends at the sentence's own period.
-const NOT_A_TICKER_SENTENCE = /Not a ticker: ((?:(?!\.\s)[^\n`\x1b])+?)\.(?=\s|\x1b|$)(?! Try `gloomberb (?:search|fred) )/g;
+// One that already names what to try (a search, a FRED series, the pair search offered) is left alone.
+const NOT_A_TICKER_SENTENCE = /Not a ticker: ((?:(?!\.\s)[^\n`\x1b])+?)\.(?=\s|\x1b|$)(?! Try `gloomberb (?:search|fred) | Did you mean )/g;
 
 /**
  * The symbol as the user typed it on the command line (`Apple`), not as the router saw it (`APPLE`).
@@ -46,6 +47,17 @@ export function withSearchHints(text: string, args: readonly string[], isFredSer
     : text;
 }
 
+/**
+ * "Not a ticker: USD_NGN. Did you mean USDNGN=X (US Dollar/Nigerian Naira)?",
+ * the listing search suggests, which takes the place of the search hint.
+ */
+export function withListingSuggestion(message: string, suggestion: string): string {
+  const symbol = notATickerSymbol(message);
+  if (!symbol || message.includes(" Did you mean ")) return message;
+  const sentence = `Not a ticker: ${symbol}.`;
+  return message.replace(sentence, `${sentence} Did you mean ${suggestion}?`);
+}
+
 /** Whether an error message says the symbol is not a ticker. */
 export function isNotATickerMessage(message: string | null | undefined): boolean {
   return message != null && notATickerSymbol(message) !== null;

package/src/cli/pane-functions/capabilities.ts

@@ -140,19 +140,24 @@ export function capabilityHasOption(capability: PaneFunctionCapability, key: str
   return resolveOptionDef(capability, key) !== undefined;
 }
 
-function normalizeEnumValue(option: PaneFunctionOptionDef, rawValue: string): string {
+function normalizeEnumValue(option: PaneFunctionOptionDef, rawValue: string, argument: string | null): string {
   const token = optionToken(rawValue);
   const match = option.values?.find((candidate) => (
     optionToken(candidate.value) === token
     || candidate.aliases?.some((alias) => optionToken(alias) === token)
   ));
   if (match) return match.value;
+  const hint = option.invalidValueHint?.(rawValue, argument);
   throw new Error(
-    `Invalid --${option.key} value "${rawValue}". Use one of: ${option.values?.map(({ value }) => value).join(", ") ?? ""}.`,
+    `Invalid --${option.key} value "${rawValue}".${hint ? ` ${hint}` : ""} Use one of: ${option.values?.map(({ value }) => value).join(", ") ?? ""}.`,
   );
 }
 
-function normalizeOptionValue(option: PaneFunctionOptionDef, rawValue: string | true): string | number | boolean {
+function normalizeOptionValue(
+  option: PaneFunctionOptionDef,
+  rawValue: string | true,
+  argument: string | null = null,
+): string | number | boolean {
   if (option.type === "boolean") {
     if (rawValue === true) return true;
     if (/^true$/i.test(rawValue)) return true;
@@ -161,7 +166,7 @@ function normalizeOptionValue(option: PaneFunctionOptionDef, rawValue: string |
   }
   if (rawValue === true) throw new Error(`--${option.key} requires a value.`);
   if (option.normalize) return option.normalize(rawValue);
-  if (option.type === "enum") return normalizeEnumValue(option, rawValue);
+  if (option.type === "enum") return normalizeEnumValue(option, rawValue, argument);
   if (option.type === "integer") {
     const value = Number(rawValue);
     if (!Number.isInteger(value)) throw new Error(`--${option.key} must be an integer.`);
@@ -179,14 +184,17 @@ function normalizeOptionValue(option: PaneFunctionOptionDef, rawValue: string |
 export function normalizeCapabilityOptions(
   capability: PaneFunctionCapability,
   options: Record<string, string | true>,
-  /** `code` is what the user types for the function (`CDX`), which an error names; the capability id stands in when there is none. */
-  settings: { strict?: boolean; code?: string } = {},
+  /**
+   * `code` is what the user types for the function (`CDX`), which an error names; the capability id stands in when
+   * there is none. `argument` is what the function was given (`RMS.AX`), which an option's pointer names.
+   */
+  settings: { strict?: boolean; code?: string; argument?: string | null } = {},
 ): NormalizedPaneFunctionOptions {
   if (!capability.botSafe) {
     // A rendered view takes any pane setting; the options it declares are checked.
     return Object.fromEntries(Object.entries(options).map(([key, value]) => {
       const option = resolveOptionDef(capability, key);
-      return option ? [option.key, normalizeOptionValue(option, value)] : [key, value];
+      return option ? [option.key, normalizeOptionValue(option, value, settings.argument)] : [key, value];
     }));
   }
 
@@ -206,7 +214,7 @@ export function normalizeCapabilityOptions(
         `${settings.code ?? capability.id} does not support --${rawKey}.${supported ? ` Supported options: ${supported}.` : " It has no options."}`,
       );
     }
-    normalized[option.key] = normalizeOptionValue(option, rawValue);
+    normalized[option.key] = normalizeOptionValue(option, rawValue, settings.argument);
   }
   return normalized;
 }