gloomberb 0.19.2 → 0.19.3

package/src/cli/commands/market.ts

@@ -1,10 +1,13 @@
 import { logFailure } from "../../utils/log-failure";
 import type { CliCommandDef } from "../../types/plugin";
 import { TIME_RANGES, type TimeRange } from "../../time-series/range";
+import { CHART_RESOLUTION_STEP_MS } from "../../time-series/resolution";
 import { yearToDateStartIndex } from "../../market-data/market/year-to-date";
 import type { EarningsEvent, QuoteBatchResult, QuoteSubscriptionTarget, SecFilingItem } from "../../types/data-provider";
 import { companyDataNotes, type CompanyFrom } from "../../types/company-from";
 import type { NewsArticle, NewsFeed, NewsQuery } from "../../news/types";
+import { newsSummaryLine } from "../../news/news-model";
+import { shortStoryId } from "../../news/story-id";
 import type {
   AnalystResearchData,
   CorporateActionsData,
@@ -52,6 +55,7 @@ import {
   analystReferenceMetadata,
   analystUpside,
   formatAnalystReference,
+  ratingReason,
 } from "../../plugins/builtin/research/analyst-model";
 import { getPublishedUsEquityCalendarYears, getPublishedUsEquitySession } from "../../market-data/published-us-sessions";
 import { isQuoteStaleForCurrentSession, noPrintsTodayText } from "../../market-data/quotes/freshness";
@@ -103,6 +107,7 @@ import {
 } from "../../utils/option-expiry";
 import { DATE_OPTION_EXAMPLES, isoDateOption, isoDateToday } from "../../utils/calendar-date";
 import { apiClient } from "../../api-client";
+import { CLOUD_QUOTE_DELAY_MINUTES } from "../../api-client/plan-rules";
 import type { ExchangeAnnouncementsPayload } from "../../api-client/exchange-announcements";
 import { exchangeAnnouncementsPage, listsExchangeAnnouncements, type ExchangeAnnouncementsPage } from "../../utils/exchange-announcements";
 import { dailyFxLeg, fxCloseOnDate, type FxCloseReading } from "../../market-data/fx-closes";
@@ -120,7 +125,7 @@ import {
   type CliReportTables,
 } from "../report-tables";
 import { historyCoverageNotice } from "../../sources/history-coverage";
-import { maxDrawdown, maxDrawdownText } from "../../utils/max-drawdown";
+import { maxDrawdownText } from "../../utils/max-drawdown";
 import { isPastPriceWindow, loadPriceWindowHistory, PRICE_WINDOW_FROM_HELP, PRICE_WINDOW_TO_HELP, priceWindowText, readPriceWindow, type PriceWindow } from "../../utils/price-window";
 import {
   BAR_INTERVAL_LABELS,
@@ -132,6 +137,9 @@ import {
   historyFacts,
   historyFlagNote,
   historyWickNote,
+  historyContractDrawdown,
+  historyRollNote,
+  historyThinNote,
   historyGapNote,
   historyJumpNote,
   historyUnbrokenFrom,
@@ -146,13 +154,14 @@ import {
   historyUnit,
   quotedPriceDivisor,
   historyVolume,
+  historyVolumeBasis,
   historyVolumeText,
   type HistoryRow,
   type HistoryUnit,
   type HistoryVolume,
 } from "../history-rows";
 import {
-  HISTORY_EXPORT_COLUMNS,
+  historyExportColumns,
   historyExportStatus,
   historyFailureRow,
   oneLineFailure,
@@ -191,7 +200,7 @@ import { DAY_SO_FAR_TEXT, withSessionBar } from "../../time-series/session-bar";
 import { isFiniteNumber } from "../../utils/guards";
 import { exportedFundamentals } from "../../utils/price-earnings";
 import { fundamentalsFreshness, fxPairFreshness, quotesFreshness, rowsFreshness, valuationFreshness } from "../freshness";
-import { fxRateNotes } from "../../plugins/builtin/shared/fx-rate-freshness";
+import { fxRateNotes, refreshedFxRateNotes } from "../../plugins/builtin/shared/fx-rate-freshness";
 import { quoteBarNotes } from "../../market-data/quotes/intraday-bar";
 import { cedearRatioText, depositaryPairText, isReceiptSide, listingCedearRatio, listingDepositaryPair } from "../../market-data/depositary-pair";
 import { isPesoDollarPair, loadPesoDollarRates, pesoDollarRateLines, pesoDollarRatesJson } from "../peso-dollar-rates";
@@ -246,13 +255,13 @@ import {
   type CliListing,
   type ListingIdentity,
 } from "../listing-arg";
-import { bareListingNote, listingFateNotes, noLongerTradingNote, tradingListing } from "../../tickers/listing-fate";
+import { bareListingNote, listingFateNotes, noLongerTradingNote, SUCCESSOR_CHANGE_WAIT_MS, tradingListing } from "../../tickers/listing-fate";
 import { isYieldIndexSymbol } from "../../tickers/index-roots";
 import {
   analyzeTaxEquivalent, distributionBasis, loadTreasuryTenors, parseTaxRates, TAX_RATE_HELP_OPTIONS, taxEquivalentJson, type TaxRates,
 } from "../../market-data/tax-equivalent";
 import { CBOE_YIELD_INDEX_CLOSE } from "../../plugins/builtin/shared/treasury-cutoffs";
-import { earningsCalendarFailure, earningsChoiceNote, earningsDateLabel, isListingAbroad, noListingCalendarNote } from "../earnings-calendar";
+import { earningsCalendarFailure, earningsChoiceNote, earningsDateLabel, isListingAbroad, noListingCalendarNote, undatedListingsNote } from "../earnings-calendar";
 import { formatBasisPoints, toBasisPoints } from "../../utils/basis-points";
 import { providerMissReason } from "../../sources/provider-errors";
 import { isNetworkFailure } from "../../utils/network-failure";
@@ -805,7 +814,10 @@ function financialStatementRows(financials: FinancialsCliData) {
 
 function newsRows(articles: NewsArticle[]) {
   return articles.map((article) => ({
+    id: article.id,
     title: article.title,
+    // Whole, as exports write it; the text table's line under the row (newsRowNote) runs it together.
+    summary: article.summary ?? null,
     source: article.source,
     publishedAt: isoDate(article.publishedAt),
     topic: article.topic,
@@ -823,6 +835,8 @@ function filingRows(filings: SecFilingItem[]) {
     companyName: filing.companyName ?? "",
     accessionNumber: filing.accessionNumber,
     url: filing.primaryDocumentUrl ?? filing.filingUrl,
+    // A current report's press release exhibit, where its index names one: the figures, not the cover page.
+    pressReleaseUrl: filing.pressReleaseUrl ?? "",
     items: secFilingItemCodes(filing.items) ?? "",
     // A current report's items by number and name: the results 8-K reads apart from another filed that day.
     itemsLabel: currentReportItemsLabel(filing.items) ?? "",
@@ -867,9 +881,16 @@ function analystRows(data: AnalystResearchData) {
     current: rating.current ?? "",
     prior: rating.prior ?? "",
     target: rating.currentPriceTarget ?? null,
+    ...(ratingReason(rating) ? { reason: rating.reason } : {}),
   }));
 }
 
+/** The reason coverage of an action gave, under its row with the article. */
+function analystRowNote(row: { reason?: AnalystResearchData["ratings"][number]["reason"] }): string | null {
+  const reason = row.reason;
+  return reason ? `${reason.text} · ${reason.url}` : null;
+}
+
 /** Provider values carry binary floating-point noise such as 0.26940000000000003. */
 function cleanDecimal(value: number | undefined): string {
   return value == null || !Number.isFinite(value) ? "" : String(Number(value.toFixed(6)));
@@ -1044,7 +1065,7 @@ async function runQuote(rawArgs: string[], ctx: Parameters<CliCommandDef["execut
       const listing = asked[index]!;
       // A bare symbol read on a listing abroad (SXR8 -> XETRA) is not the US symbol the changes are of.
       if (result.quote && bareListingNote(listing, result.quote)) return { change: null, formerIssuer: null };
-      const payload = await changes.get(listing)?.settle() ?? null;
+      const payload = await changes.get(listing)?.settle(SUCCESSOR_CHANGE_WAIT_MS) ?? null;
       const current = tradingListing(result.quote, now);
       return { change: describeTickerChange(listing.symbol, payload, current), formerIssuer: describeFormerIssuer(listing.symbol, payload, current) };
     }));
@@ -1391,7 +1412,7 @@ async function loadListingHistory(
       : market.dataProvider.getPriceHistory(symbol, exchange, loadRange, context).then((points): PriceHistoryResult => ({ points, resolution: null }));
   const quoteAnswer = loadListingQuoteAnswer(market.dataProvider, listing);
   const quoted = quoteAnswer.then((answer) => answer.quote);
-  const fate = lookups ? listingFateLoader(listing, market, quoted) : null;
+  const fate = lookups ? listingFateLoader(listing, market, quoted, { successor: true }) : null;
   const request = { command: historyCommand(ask), noun: "history", ...(fate ? { fate } : {}) };
   const [loaded, quote] = await Promise.all([
     loadForListing(listing, market, ctx, load, (loaded) => loaded.points.length === 0, request)
@@ -1435,21 +1456,28 @@ async function loadListingHistory(
   // A bar history: dated by its last bar, stale once bars of its size stop arriving.
   // The day's own bar, while its session trades, is not a close: dated by the quote it was read from.
   const dayToDate = fromQuote && interval === "1d" && data.at(-1)?.partial === true;
+  // Signed out or free, the bars of a session in progress run as late as the delayed quote they end on, and say how late.
+  const sessionTrading = quote?.marketState === "REGULAR" || quote?.marketState === "PRE" || quote?.marketState === "POST";
+  const delayedTail = quote?.dataSource === "delayed" && !quote.delisting && (dayToDate || (intraday && sessionTrading));
   // The source that served the bars, a broker or another source when Gloom Cloud could not.
   const source = loaded.sourceName ? { source: loaded.sourceName } : {};
   // A window that closed before today is the history asked for: no later bar makes it stale.
   const freshness = withSavedCopy(window && isPastPriceWindow(window) ? rowsFreshness(data, {
     ...source,
     status: "not-a-feed", basis: `${interval ? BAR_INTERVAL_LABELS[interval] : "price"} bars, ${priceWindowText(window)}`, observedKey: "date", oldest: null,
+    ...(volume ? { note: historyVolumeText(volume, interval, historyVolumeBasis(data)) } : {}),
   }) : rowsFreshness(data, {
     ...source,
     ...barHistoryFreshness(intraday ? null : barResolutionFromDates(data.map((row) => row.date))),
     observedKey: "date",
     oldest: null,
     cadenceExchange: venue,
+    // An intraday bar is dated by its open, so the line names its span: `last bar 15:00–16:00 UTC`.
+    ...(intraday && interval && interval in CHART_RESOLUTION_STEP_MS ? { barMinutes: CHART_RESOLUTION_STEP_MS[interval] / 60_000 } : {}),
     ...(forming ? { periodToDate: forming.periodToDate } : closedDay ? { asOf: closedDay } : {}),
     ...(dayToDate ? { basis: "daily bars", ...(quote && Number.isFinite(quote.lastUpdated) ? { asOf: new Date(quote.lastUpdated).toISOString() } : {}) } : {}),
-    ...(volume || dayToDate ? { note: [volume ? historyVolumeText(volume, interval) : null, dayToDate ? `the newest bar is ${DAY_SO_FAR_TEXT}` : null].filter(Boolean).join("; ") } : {}),
+    ...(delayedTail ? { status: "delayed" as const, delayMinutes: CLOUD_QUOTE_DELAY_MINUTES } : {}),
+    ...(volume || dayToDate ? { note: [volume ? historyVolumeText(volume, interval, historyVolumeBasis(data)) : null, dayToDate ? `the newest bar is ${DAY_SO_FAR_TEXT}` : null].filter(Boolean).join("; ") } : {}),
   // The rows are drawn from the bars served, which say whether they are the saved copy.
   }), loaded);
   const gaps = historyGapNote(data, traded);
@@ -1467,6 +1495,8 @@ async function loadListingHistory(
     // The status line says how far a bar still forming runs; the note is for the bars it does not name.
     gaps ?? [], historyJumpNote(data) ?? [], historyFlagNote(data) ?? [], historyWickNote(data) ?? [], historyMissingVolumeNote(data) ?? [],
     historyVenueVolumeNote(data) ?? [],
+    // NG=F's rows are November's to the 23rd and December's from the 26th: each roll named, and thin bars said.
+    historyRollNote(listing.symbol, data) ?? [], historyThinNote(data) ?? [],
     historyBarStatusNote(forming ? served : data, { tradingDay: venueTradingDay(venue, Date.now()) }) ?? [],
   ].flat();
   return {
@@ -1475,6 +1505,19 @@ async function loadListingHistory(
   };
 }
 
+/**
+ * A continuous future's history is the front month's, not the contract its
+ * quote names now: NG=F's rows from before the roll are November's under a
+ * quote of "Natural Gas Dec 2026". The heading says "Natural Gas front month"
+ * once the bars name their contracts.
+ */
+function frontMonthIdentity(identity: ListingIdentity, symbol: string, rows: readonly HistoryRow[]): ListingIdentity {
+  if (!/=F$/i.test(symbol) || !rows.some((row) => row.contract)) return identity;
+  const board = futuresBoardContract(symbol);
+  const name = board?.name ?? identity.name?.replace(/\s+[A-Z][a-z]{2}\s+\d{4}$/, "");
+  return name ? { ...identity, name: `${name} front month` } : identity;
+}
+
 /** What a listing with no bar for what was asked says, in a warning and in a list's status column. */
 function emptyHistoryNote(symbol: string, { range, window }: HistoryAsk): string {
   return window ? `No bars for ${symbol} from ${priceWindowText(window)}.` : `No bars for ${symbol} in ${range}.`;
@@ -1520,6 +1563,8 @@ const HISTORY_FLAG_TEXT_COLUMN: CliResultColumn = {
     row.partial ? cliStyles.muted("partial") : "",
     row.filled ? cliStyles.muted("filled") : "",
     row.unsettled ? cliStyles.muted("unsettled") : "",
+    row.roll && typeof row.contract === "string" ? cliStyles.muted(`roll to ${row.contract}`) : "",
+    row.thin ? cliStyles.muted("thin") : "",
     typeof row.status === "string" ? cliStyles.warning(row.status) : "",
   ].filter(Boolean).join(" "),
 };
@@ -1573,8 +1618,10 @@ async function runHistory(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
     const missingVolume = historyReportsVolume(data) ? MISSING_VOLUME_TEXT : "";
     const textColumns = historyTextColumns(intraday, price).map((column) => column.key !== "volume" ? column
       : { ...column, format: historyVolumeCell(() => missingVolume) });
-    // The largest fall from a close to a later one in the bars shown, said under the heading.
-    const drawdown = maxDrawdown(data);
+    // The largest fall from a close to a later one in the bars shown, said under the heading: within one contract
+    // of a continuous future, never from one month's close to another's across a roll.
+    const contractDrawdown = historyContractDrawdown(data);
+    const drawdown = contractDrawdown?.drawdown ?? null;
     ctx.printResult({
       data,
       metadata: {
@@ -1591,20 +1638,21 @@ async function runHistory(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
         // The first bar after the last gap or jump; the first bar when there is none.
         unbrokenFrom: historyUnbrokenFrom(data) ?? data[0]?.date ?? null,
         bars: data.length,
-        maxDrawdown: drawdown,
+        maxDrawdown: drawdown && contractDrawdown?.contract ? { ...drawdown, contract: contractDrawdown.contract } : drawdown,
         asOf: freshness?.asOf ?? null,
         ...(volume ? { volumeUnit: volume.unit, volumePeriod: interval === "1d" ? "UTC day" : interval } : {}),
       },
       ...(notes.length > 0 ? { warnings: notes } : {}),
       freshness,
     }, {
-      heading: [listingHeading(identity), cliStyles.muted(historyFacts(unit, data).join("  ·  ")),
-        ...drawdown && interval ? [cliStyles.muted(maxDrawdownText(drawdown, { basis: `${BAR_INTERVAL_LABELS[interval]} closes`, price,
+      heading: [listingHeading(frontMonthIdentity(identity, history.listing.symbol, data)), cliStyles.muted(historyFacts(unit, data).join("  ·  ")),
+        ...drawdown && interval ? [cliStyles.muted(maxDrawdownText(drawdown, {
+          basis: `${BAR_INTERVAL_LABELS[interval]} closes${contractDrawdown?.contract ? `, ${contractDrawdown.contract}` : ""}`, price,
           date: (text) => intraday ? formatUtcTime(text) : text.slice(0, 10) }))] : []].join("\n"),
       dateKey: "date",
       textColumns: [...textColumns, HISTORY_FLAG_TEXT_COLUMN],
-      // One header whatever the market is doing, for one symbol as for a list (HISTORY_EXPORT_COLUMNS).
-      columns: HISTORY_EXPORT_COLUMNS,
+      // One header whatever the market is doing, for one symbol as for a list (historyExportColumns).
+      columns: historyExportColumns(data),
       exportStatus: historyExportStatus,
       // Every exported row says what it is a bar of, the currency a price is in and its bar size, so it survives head and concatenation.
       exportIdentity: { symbolOrSeries: history.listing.key, currencyOrUnit: unit.currency ?? unit.unit, interval },
@@ -1710,7 +1758,7 @@ async function runHistoryList(
       dateKey: "date",
       textColumns: [{ key: "symbol", header: "Symbol", shrink: false }, ...textColumns,
         { key: "currency", header: "Cur", shrink: false, format: currencyCell }, HISTORY_FLAG_TEXT_COLUMN],
-      columns: HISTORY_EXPORT_COLUMNS,
+      columns: historyExportColumns(rows),
       exportStatus: historyExportStatus,
       // Every row names its symbol, the currency its prices are in, its bar size and the as-of of its own symbol's bars.
       exportIdentity: (row) => {
@@ -1929,9 +1977,18 @@ const NEWS_COLUMNS = [
   { key: "source", header: "Source" },
   { key: "title", header: "Title" },
   { key: "tickers", header: "Tickers" },
+  // The short id `fn news-story-pane` opens the story by; exports keep the whole id.
+  { key: "id", header: "ID", format: (value: unknown) => typeof value === "string" ? shortStoryId(value) : "" },
   { key: "url", header: "URL", optional: true },
 ];
 
+/**
+ * A story's summary under its row, on one line, cut to the width (`rowNote`): the figure a headline leaves out.
+ * None for a summary that only repeats the headline; exports keep the summary whole.
+ */
+const newsRowNote = (row: Record<string, unknown>) => typeof row.summary === "string"
+  ? newsSummaryLine({ title: String(row.title ?? ""), summary: row.summary }) : null;
+
 /**
  * Stories matching text, printed as a symbol's news is, under a line saying
  * what they match. A text naming a commodity that matched nothing says so and
@@ -1968,6 +2025,7 @@ async function printNewsSearch(
     heading: newsSearchHeading(text, [reason, closestReason].filter(Boolean).join("  ·  ") || undefined),
     rows: newsRows,
     columns: NEWS_COLUMNS,
+    rowNote: newsRowNote,
     empty: named ? noStoriesMessage(text, route) : empty ?? (searched ? noStoriesMessage(text, null) : "No stories to show."),
   });
 }
@@ -2011,6 +2069,7 @@ async function printMetalNews(route: MetalNewsRoute, limit: number, ctx: Paramet
     heading: metalNewsHeading(route),
     rows: newsRows,
     columns: NEWS_COLUMNS,
+    rowNote: newsRowNote,
     empty: failure === undefined ? noMetalStoriesMessage(route) : "No stories to show.",
     ...(ticker ? { footnote: `${word} ${cliArrow("→")} ${route.metal}'s market news. For ${ticker.name ?? ticker.symbol} (ticker ${ticker.symbol}), try: ${companyNews}` } : {}),
   });
@@ -2113,6 +2172,7 @@ async function runNews(rawArgs: string[], ctx: Parameters<CliCommandDef["execute
       ...(identity ? { heading: listingHeading(identity) } : {}),
       rows: newsRows,
       columns: NEWS_COLUMNS,
+      rowNote: newsRowNote,
       ...(empty ? { empty } : {}),
       ...(wordHint ? { footnote: wordHint } : {}),
     });
@@ -2127,15 +2187,18 @@ const FILING_COLUMNS = [
   { key: "url", header: "URL", optional: true },
   { key: "items", header: "Items" },
   { key: "itemsLabel", header: "Item names" },
+  { key: "pressReleaseUrl", header: "Press release URL" },
 ];
 
-// The text table names the items before the URL, which a narrow terminal drops first.
+// The text table names the items before the URL, which a narrow terminal drops first. A current report's
+// URL is its press release where it has one, the page its figures are on; exports keep both links.
 const FILING_TEXT_COLUMNS = [
   { key: "filingDate", header: "Date" },
   { key: "form", header: "Form" },
   { key: "companyName", header: "Company", maxWidth: 24 },
   { key: "itemsLabel", header: "Items" },
-  { key: "url", header: "URL", optional: true },
+  { key: "url", header: "URL", optional: true,
+    format: (value: unknown, row: Record<string, unknown>) => String(row.pressReleaseUrl || (value ?? "")) },
 ];
 
 /** The US listing the SEC files a symbol under, from the symbol's venues: NYSE for SAN's Banco Santander. */
@@ -2631,6 +2694,7 @@ async function runAnalyst(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
       heading: listingHeading(identity),
       rows: analystRows,
       summary: (research) => analystSummary(research, quote),
+      rowNote: analystRowNote,
       columns: [
         { key: "date", header: "Date" },
         { key: "firm", header: "Firm" },
@@ -2722,7 +2786,7 @@ async function runOptions(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
     const refresh = ctx.cliOptions.refresh;
     const venues = loadBareVenues(listing, market);
     const quotePromise = loadListingQuote(market.dataProvider, listing);
-    const fate = listingFateLoader(listing, market, quotePromise);
+    const fate = listingFateLoader(listing, market, quotePromise, { successor: true });
     const inputsPromise = loadOptionModelInputs(market.dataProvider, listing, quotePromise, refresh);
     const now = Date.now();
     // Expiries close on the listing's clock: a coin's options (Deribit) settle at 08:00 UTC on any day.
@@ -3078,7 +3142,9 @@ async function runFx(rawArgs: string[], ctx: Parameters<CliCommandDef["execute"]
     }));
     const freshness = fxPairFreshness(loaded);
     // A rate that is its pair's bar says which bar, and a stale one why it stands.
-    const rateNotes = fxRateNotes(new Map([...loaded].map(([code, leg]) => [code, leg.timing])));
+    const timings = new Map([...loaded].map(([code, leg]) => [code, leg.timing]));
+    // --refresh read every leg again: one that is still stale says the data service has no newer rate.
+    const rateNotes = [...fxRateNotes(timings), ...ctx.cliOptions.refresh ? refreshedFxRateNotes(timings) : []];
     if (tenor && shortRates && !("error" in tenor)) {
       const read = await shortRates;
       if ("error" in read) throw read.error;
@@ -3214,12 +3280,14 @@ async function runEarnings(rawArgs: string[], ctx: Parameters<CliCommandDef["exe
         return listed ? earningsChoiceNote(listing, eventOf(listing), await listed) : null;
       })),
     ]);
-    const noCalendar = abroadNotes.join("\n");
+    // A listing at home the calendar has no date for is named as well: a list never drops a symbol unsaid.
+    const undated = undatedListingsNote(listings.filter((listing) => !isListingAbroad(listing) && !eventOf(listing)));
+    const noCalendar = [...abroadNotes, ...undated ? [undated] : []].join("\n");
     // Text prints the listings without a calendar under the table; other formats carry them as warnings.
     const warnings = [
       ...listings.flatMap(listingReadNotes),
       ...choiceNotes.filter((note): note is string => !!note),
-      ...ctx.cliOptions.format === "text" ? [] : abroadNotes,
+      ...ctx.cliOptions.format === "text" ? [] : [...abroadNotes, ...undated ? [undated] : []],
     ];
     ctx.printResult({
       data: events,
@@ -3292,7 +3360,8 @@ export const marketDataCliCommands: BuiltinCliCommandDef[] = [
       }, {
         title: "CSV",
         lines: [
-          "Every --csv has one header, whatever the symbol, range or market state: Date, Open, High, Low, Close, Volume, Flag, Partial, Filled, Unsettled, Volume unit, Volume note, Venue volume, Volume venue, status, then symbol_or_series, currency_or_unit, interval, source and as_of. Prices are plain numbers in the currency currency_or_unit names. Partial, Filled and Unsettled are true or false, and status says why a row has no prices.",
+          "Every --csv has one header, whatever the symbol, range or market state: Date, Open, High, Low, Close, Volume, Flag, Partial, Filled, Unsettled, Volume unit, Volume note, Venue volume, Volume venue, Volume basis, status, then symbol_or_series, currency_or_unit, interval, source and as_of. Prices are plain numbers in the currency currency_or_unit names. Partial, Filled and Unsettled are true or false, and status says why a row has no prices.",
+          "A continuous future whose bars name their contracts (NG=F) adds Contract, Roll and Thin before status: the contract per bar, and true or false for the bar it rolled at and a bar that traded far below those around it.",
         ],
       }, {
         title: "Several symbols",

package/src/cli/commands/news-search.ts

@@ -72,14 +72,30 @@ export function newsFallbackText(symbol: string): string | null {
 }
 
 /**
- * The stories matching the text, in the service's order: stories with every
- * word in the headline first, then the ones with some only in the summary,
- * newest first within each. The service holds stories back from an account
+ * Stories newest first, as `news <words>` lists them. The service picks the
+ * best matches (every word in the headline before words only in the summary);
+ * the list is then read by date, which its help promises. A story with no
+ * date goes last; equal dates keep the service's order.
+ */
+function newestFirst(articles: readonly NewsArticle[]): NewsArticle[] {
+  const time = (article: NewsArticle) => {
+    const at = new Date(article.publishedAt as Date | string | number).getTime();
+    return Number.isFinite(at) ? at : -Infinity;
+  };
+  return articles.map((article, index) => ({ article, index, at: time(article) }))
+    .sort((left, right) => right.at - left.at || left.index - right.index)
+    .map(({ article }) => article);
+}
+
+/**
+ * The stories matching the text, newest first (`newestFirst`): the service
+ * chooses them, stories with every word in the headline ahead of the ones with
+ * some only in the summary. The service holds stories back from an account
  * without real-time access, as every other news request.
  */
 export async function searchNewsStories(text: string, limit: number, topics?: readonly string[]): Promise<NewsArticle[]> {
   const response = await apiClient.searchCloudNews(text, limit, topics);
-  return response.items.map((item) => mapCloudNewsArticle(item));
+  return newestFirst(response.items.map((item) => mapCloudNewsArticle(item)));
 }
 
 /** A search's stories, and whether they are its closest ones because no story has every word. */
@@ -96,7 +112,10 @@ export interface NewsSearchAnswer {
  */
 export async function searchClosestNewsStories(text: string, limit: number): Promise<NewsSearchAnswer> {
   const response = await apiClient.searchCloudNews(text, limit, undefined, { closest: true });
-  return { found: response.items.map((item) => mapCloudNewsArticle(item)), closest: response.match === "closest" };
+  const found = response.items.map((item) => mapCloudNewsArticle(item));
+  // The closest stories stay most words first, as their heading says; a match of every word is read by date.
+  const closest = response.match === "closest";
+  return { found: closest ? found : newestFirst(found), closest };
 }
 
 /** What the heading says of a search no story has every word of. */

package/src/cli/commands/overview.ts

@@ -59,7 +59,7 @@ import { buildCorrelationSeries } from "../../plugins/builtin/correlation/matrix
 import { alignDailyCloses, correlateDailyCloses } from "../../plugins/builtin/correlation/compute";
 import { mixedSessionCloseNote } from "../../market-data/market/session-close-note";
 import { CORRELATION_RETURN_BASIS, loadCorrelationHistory } from "../../plugins/builtin/correlation/history";
-import { EXCHANGE_OPTION, listingIdentity, listingReadNotes, loadForListing, loadListingQuote, requireCliListing, type CliListing } from "../listing-arg";
+import { coinListingNotes, EXCHANGE_OPTION, listingIdentity, listingReadNotes, loadForListing, loadListingQuote, requireCliListing, type CliListing } from "../listing-arg";
 import { CLI_COMMAND_GROUPS } from "../help";
 import { formatChangePercentCell, formatCompactCell } from "../helpers";
 import { WORLD_INDICES } from "../../plugins/builtin/world-indices/indices";
@@ -481,7 +481,7 @@ async function runEcon(args: string[], ctx: Parameters<CliCommandDef["execute"]>
   const country = parseCountry(takeOption(rawArgs, "--country"), ctx);
   const impact: ImpactFilter = parseFilter(takeOption(rawArgs, "--impact"), FILTER_CYCLE, "impact", ctx);
   const search = takeOption(rawArgs, "--search")?.trim() ?? null;
-  if (search === "") ctx.fail("--search needs the words of an event's name.", "Such as econ --search nonfarm.");
+  if (search === "") ctx.fail("--search needs the words of an event's name or its publisher.", "Such as econ --search nonfarm.");
   const fromOption = parseDateOption(takeOption(rawArgs, "--from"), "--from", ctx);
   const tzOption = takeOption(rawArgs, "--tz");
   const viewerZone = tzOption == null ? null : canonicalTimeZone(tzOption);
@@ -909,7 +909,12 @@ async function runCorrelation(rawArgs: string[], ctx: Parameters<CliCommandDef["
       asOf: newestReportTime(lastBars),
       oldest: oldestReportTime(lastBars),
     });
-    const warnings = [...listingReadNotes(leftListing!), ...listingReadNotes(rightListing!), ...sessionNote ? [sessionNote] : []];
+    // A coin's code read as a listing (BTC, the Grayscale fund) says so, as `quote BTC` does.
+    const warnings = [
+      ...listingReadNotes(leftListing!), ...listingReadNotes(rightListing!),
+      ...coinListingNotes(leftListing!, leftQuote), ...coinListingNotes(rightListing!, rightQuote),
+      ...sessionNote ? [sessionNote] : [],
+    ];
     ctx.printResult({
       data: [{ left, right, samples: sampleSize, correlation }],
       ...(warnings.length > 0 ? { warnings } : {}),
@@ -971,7 +976,7 @@ export const overviewCliCommands: CliCommandDef[] = [
       options: [
         { flags: "--country <regions or countries>", description: "US, G7, EU, all (default), or countries by their two-letter codes, comma separated, such as MX or MX,BR,ZA" },
         { flags: "--impact <level>", description: "high, medium, low, or all (default all)" },
-        { flags: "--search <words>", description: "Events whose name has these words, case, spaces and hyphens aside, such as nonfarm or fed funds" },
+        { flags: "--search <words>", description: "Events whose name or publisher has these words, case, spaces and hyphens aside, such as nonfarm, fed funds or USDA" },
         { flags: "--from <date>", description: `First day listed, as ${DATE_OPTION_EXAMPLES} (default today, UTC); an earlier day lists past events from the stored calendar and says where it starts` },
         { flags: "--tz <zone>", description: "Add a column with each release's time on that clock, an IANA zone such as America/New_York; with the weekday when it falls on another day than the UTC date" },
       ],

package/src/cli/commands/search.ts

@@ -24,7 +24,7 @@ import { initMarketData, withMarketData } from "../context";
 import { listingChangeLine, loadListingFate } from "../../tickers/listing-fate";
 import { formatMarketPriceWithCurrency, quoteFormatOptions } from "../../market-data/market/format";
 import { formerIssuerLine, startTickerChangeLookup, type TickerChangeLookup } from "../../tickers/ticker-changes";
-import { fail, failRetryable } from "../errors";
+import { fail, failRetryable, failWithError, isCliFailure, unreachableError } from "../errors";
 import { isProviderBusy, SEARCH_BUSY_CODE, SEARCH_BUSY_MESSAGE } from "../../sources/provider-errors";
 import { isNetworkFailure } from "../../utils/network-failure";
 import type { MarketContext } from "../types";
@@ -36,6 +36,7 @@ import { knownGapMessage, commandPointer } from "../known-gaps";
 import { instrumentTypeLabel } from "../../tickers/instrument-kind";
 import { canonicalExchange, isUsListingExchange } from "../../utils/exchanges";
 import { companyLines, companyNameExtraWords, groupByCompany, namedByService, sameCompany } from "../../tickers/company-name";
+import { isLowQualityTickerName } from "../../tickers/search/result";
 import { findCatalogSeries, renderSeriesMatches, type SeriesMatch } from "../series-search";
 import { centralBankAskedAbout, centralBankCiting, type CentralBank } from "../../utils/central-banks";
 import { createPaneCatalog } from "../pane-functions/discovery";
@@ -133,8 +134,8 @@ export async function searchCandidatesForCli({
     const quote = BARE_SYMBOL.test(symbol) && candidates.some((candidate) => candidate.symbol.toUpperCase() === symbol)
       ? await (quoted ?? loadSearchedQuote(symbol, savedExchange, dataProvider))
       : null;
-    return withQuotedNames(symbol, withUsLineOfPrimary(withHomeListingPrimary(trimmedQuery, withPrimaryListingFirst(symbol, candidates, quote))), quote)
-      .slice(0, totalLimit);
+    const ordered = withQuotedNames(symbol, withUsLineOfPrimary(withHomeListingPrimary(trimmedQuery, withPrimaryListingFirst(symbol, candidates, quote))), quote);
+    return withOtherCompaniesApart(ordered).slice(0, totalLimit);
   } catch (error) {
     // Not "No matches found": a script or a reader would take that for a name nothing lists.
     if (isProviderBusy(error)) failRetryable(SEARCH_BUSY_MESSAGE, SEARCH_BUSY_CODE);
@@ -346,6 +347,35 @@ function withQuotedNames(symbol: string, candidates: TickerSearchCandidate[], qu
   });
 }
 
+/** A symbol without a venue's suffix or code: DK for DK.BA or DK:BYMA. */
+const baseSymbol = (symbol: string) => symbol.toUpperCase().replace(/[:.][A-Z]{1,4}$/, "");
+
+/**
+ * Other Listings are the primary listing's company's own lines alone: by its
+ * name, a name it had (Cassava Sciences for Filana's FLNA), or, for a line
+ * search names no company for, its symbol on another venue. Another company's
+ * line, or a nameless line under another symbol (DKC1O on BYMA under
+ * `search DK`), is an Other Match, listed after them.
+ */
+function withOtherCompaniesApart(candidates: TickerSearchCandidate[]): TickerSearchCandidate[] {
+  // A line search names no company for: no name, or only its symbol (DKC1O).
+  const nameless = (candidate: TickerSearchCandidate) =>
+    isLowQualityTickerName(candidate.result ? candidate.result.name ?? "" : resolveSearchName(candidate), candidate.symbol);
+  const primary = candidates.find((candidate) => candidate.category === "Primary Listing");
+  // A primary line search names no company for gives nothing to tell its company's lines by.
+  if (!primary || nameless(primary)) return candidates;
+  const names = [resolveSearchName(primary), primary.result?.formerName, ...primary.nameAliases ?? []];
+  const ownLine = (candidate: TickerSearchCandidate) => nameless(candidate)
+    ? baseSymbol(candidate.symbol) === baseSymbol(primary.symbol)
+    : names.some((company) => sameCompany(resolveSearchName(candidate), company));
+  const others = candidates.filter((candidate) => candidate.category === "Other Listings" && !ownLine(candidate));
+  if (others.length === 0) return candidates;
+  const kept = candidates.filter((candidate) => !others.includes(candidate));
+  const at = kept.findLastIndex((candidate) => candidate === primary || candidate.category === "Other Listings") + 1;
+  const apart = others.map((candidate) => ({ ...candidate, category: "Other Matches" as const }));
+  return [...kept.slice(0, at), ...apart, ...kept.slice(at)];
+}
+
 /** "Saved", or the broker a row came from; never the data service's internal id. */
 function searchSourceLabel(candidate: TickerSearchCandidate): string {
   return candidate.kind === "ticker" ? "Saved" : candidate.result?.brokerLabel || "";
@@ -498,18 +528,19 @@ export function buildSearchReport({
   /** What the query was searched as: "Read VIX.X as ^VIX (Cboe Volatility Index)." */
   readAs?: string;
 }): string {
+  // Every note is prose: it wraps to a narrow --width.
   const lines = [renderSection(`Search: ${query}`)];
-  if (readAs) lines.push("", readAs);
+  if (readAs) lines.push("", wrapToTerminal(readAs));
   const notes = [...fate.notes, ...formerIssuerNotes(candidates, fate)];
-  if (notes.length > 0) lines.push("", ...notes);
+  if (notes.length > 0) lines.push("", ...notes.map((note) => wrapToTerminal(note)));
   const gap = knownGapMessage(query);
   const indexNote = gap ? null : indexRootNote(query, candidates);
-  if (indexNote) lines.push("", indexNote);
-  if (gap) lines.push("", gap);
+  if (indexNote) lines.push("", wrapToTerminal(indexNote));
+  if (gap) lines.push("", wrapToTerminal(gap));
   const bank = searchedCentralBank(query);
   if (bank) lines.push("", wrapToTerminal(centralBankLine(bank)));
   const setting = commandPointer(query);
-  if (setting) lines.push("", setting);
+  if (setting) lines.push("", wrapToTerminal(setting));
   const charted = renderSeriesMatches(query, series, SEARCH_SERIES_LIMIT, cliTerminalWidth() ?? 100, "catalog");
   // A query that names the data ("carbon", "day-ahead") lists its series first; words that happen to
   // be in a series name ("apple") list them after the tickers.
@@ -523,9 +554,9 @@ export function buildSearchReport({
     if (functions.length > 0) lines.push("", renderFunctionMatches(functions));
     else if (!gap && !bank && !setting && !charted) {
       return [...lines, ...hasNonLatinLetters(query) ? [cliStyles.muted(OTHER_SCRIPT_NO_MATCH)]
-        : [cliStyles.muted("No matches found."), cliStyles.muted(catalogHint(query))]].join("\n");
+        : [cliStyles.muted("No matches found."), cliStyles.muted(wrapToTerminal(catalogHint(query)))]].join("\n");
     }
-    if (pointToCatalog) lines.push("", cliStyles.muted(catalogHint(query)));
+    if (pointToCatalog) lines.push("", cliStyles.muted(wrapToTerminal(catalogHint(query))));
     return lines.join("\n");
   }
 
@@ -558,11 +589,39 @@ export function buildSearchReport({
     ));
   }
   if (charted && !seriesFirst) lines.push("", charted);
-  if (pointToCatalog) lines.push("", cliStyles.muted(catalogHint(query)));
+  if (pointToCatalog) lines.push("", cliStyles.muted(wrapToTerminal(catalogHint(query))));
 
   return lines.join("\n");
 }
 
+/**
+ * What a search says from its own text, whatever the ticker lookup does: the
+ * data no source carries and its proxies ("baltic dry"), the central bank the
+ * query names, the setting or report it names.
+ */
+function localSearchNotes(query: string): string[] {
+  const bank = searchedCentralBank(query);
+  return [knownGapMessage(query), bank ? centralBankLine(bank) : null, commandPointer(query)].filter((note): note is string => !!note);
+}
+
+/**
+ * A ticker lookup that was busy or never reached the data service fails only
+ * the ticker part of a search: the notes from local text print first (text) or
+ * ride in the failure's details (JSON), then the failure says that no tickers
+ * were looked up. A search with no such note fails as before.
+ */
+function failTickerLookup(error: unknown, query: string, printNotes: boolean): never {
+  const notes = localSearchNotes(query);
+  const busy = isCliFailure(error) && error.code === SEARCH_BUSY_CODE;
+  if (notes.length === 0 || !(busy || isNetworkFailure(error))) throw error;
+  if (printNotes) console.log([renderSection(`Search: ${query}`), "", ...notes.map((note) => wrapToTerminal(note))].join("\n"));
+  const failure = busy ? { code: SEARCH_BUSY_CODE, message: TICKER_SEARCH_BUSY_MESSAGE, retryable: true } : unreachableError();
+  return failWithError(printNotes ? failure : { ...failure, details: [failure.details, ...notes].filter(Boolean).join("\n") });
+}
+
+/** The busy line after a search's own notes printed: only the ticker lookup is missing. */
+const TICKER_SEARCH_BUSY_MESSAGE = "Ticker search is busy, try again in a moment.";
+
 /** The functions a search lists when it found no ticker, unless a known gap or a central bank already says where to look. */
 function searchedFunctions(
   query: string,
@@ -613,7 +672,7 @@ export async function search(query: string, dependencies: SearchCommandDependenc
       tickers,
       dataProvider,
       ...quote ? { quote } : {},
-    });
+    }).catch((error: unknown) => failTickerLookup(error, trimmedQuery, !dependencies.printResult));
     const fate = quote && changes ? await searchFate(symbol, candidates, await quote, dataProvider, changes) : NO_SEARCH_FATE;
 
     const series = findCatalogSeries(dependencies.plugins ?? [], trimmedQuery, "names");