gloomberb 0.17.4 → 0.17.6

package/src/cli/listing-arg.ts

@@ -13,16 +13,8 @@ import {
   type ListingVenue,
 } from "../tickers/listing-venues";
 import { findUsListingOfCompany, type UsListing } from "../tickers/us-listing";
-import {
-  describeTickerChange,
-  quotedListing,
-  startTickerChangeLookup,
-  tickerChangeLine,
-  type CurrentListing,
-  type TickerChange,
-  type TickerChangeLookup,
-} from "../tickers/ticker-changes";
-import type { TickerChanges } from "../types/ticker-changes";
+import { movedAwayChange, startTickerChangeLookup, type MovedTickerChange } from "../tickers/ticker-changes";
+import { loadListingFate, MovedSymbolError, type ListingFate } from "../tickers/listing-fate";
 import { quotedListingName } from "../tickers/listing-name";
 import { cliStyles } from "../utils/cli-output";
 import { groupByCompany, sameCompany, shortCompanyName } from "../tickers/company-name";
@@ -35,17 +27,14 @@ import {
   isUsListingExchange,
   parsePublicTickerKey,
   publicTickerKey,
-  resolveExchangeTimeZone,
   typedExchangeCode,
 } from "../utils/exchanges";
 import { withMarketData } from "./scoped-context";
+import { failWithFields } from "./errors";
 import { stripStrayEdges } from "./symbol-args";
 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";
 import { bareFuturesCode, futuresContractByCode } from "../market-data/futures-board";
 
 /** The `--exchange` option of every command that takes a ticker. */
@@ -260,7 +249,9 @@ export interface ListingDataRequest {
    * What became of the symbol (`loadListingFate`), for a command a listing
    * that stopped trading has nothing for (history, options): a request no
    * source serves fails with `fate.note` instead of the source's miss, and the
-   * change line leads any listings the failure names.
+   * change line leads any listings the failure names. A symbol whose company
+   * moved, with nothing new listed under it, fails naming its new symbol
+   * whatever came back (`failMovedSymbol`).
    */
   fate?: () => Promise<ListingFate>;
 }
@@ -472,7 +463,7 @@ interface OtherListingsMessage {
  * The command that asks again for another listing: `gloomberb history SAN:EPA
  * --range 5Y` keeps the options. Null where the request names listings alone.
  */
-function retryCommand(request: ListingDataRequest, key: string): string | null {
+function retryCommand(request: Pick<ListingDataRequest, "command" | "retry">, key: string): string | null {
   if (request.retry !== undefined) return request.retry?.(key) ?? null;
   const [command, ...options] = request.command.split(" ");
   return ["gloomberb", command, key, ...options].join(" ");
@@ -638,95 +629,23 @@ export function chosenListingNote(symbol: string, exchange: string, others: read
   return `${symbol} -> ${exchange}${aside ? ` (${aside})` : ""}`;
 }
 
-// A quote this much older than now, and stale, is a listing that stopped trading, not a quiet day.
-const ENDED_AFTER_MS = 183 * 24 * 60 * 60_000;
-
-/**
- * The exchange-local date a listing last traded, when its quote is stale and
- * that was over half a year ago (TWTR's 2022-10-27); null for anything newer.
- */
-function endedTradingDate(quote: Quote, now = Date.now()): string | null {
-  const last = Math.max(...[quote.lastTradeTime, quote.lastUpdated].filter((time): time is number => Number.isFinite(time)));
-  if (!(last > 0) || now - last < ENDED_AFTER_MS || !isQuoteStaleForCurrentSession(quote, now)) return null;
-  const zone = resolveExchangeTimeZone(quote.listingExchangeName || quote.exchangeName) ?? "UTC";
-  return zonedDateKey(last, zone);
-}
-
-/** What trades under a symbol now, from its quote: nothing when it has none or stopped long ago. */
-export function tradingListing(quote: Quote | null | undefined, now = Date.now()): CurrentListing | null {
-  return quote && !endedTradingDate(quote, now) ? quotedListing(quote) : null;
-}
-
-/** "TWTR: no longer trading since 2022-10-27 (last price $53.86)", for a quote that stopped long ago. */
-export function noLongerTradingNote(label: string, quote: Quote, now = Date.now()): string | null {
-  const date = endedTradingDate(quote, now);
-  if (!date) return null;
-  const price = formatMarketPriceWithCurrency(quote.price, quote.currency, quoteFormatOptions(quote));
-  return `${label}: no longer trading since ${date} (last price ${price})`;
-}
-
 /**
- * What became of a symbol, from what `quote` reads it by: the listing's own
- * quote, which says when it stopped trading, and the symbol's ticker changes
- * beside that quote (FB became META).
+ * "HFC became DINO on 2022-03-15: `gloomberb history DINO`": a symbol whose
+ * company moved, with the command that asks for it under its new symbol.
  */
-export interface ListingFate {
-  /** The exchange-local date the listing last traded, when its quote stopped long ago (TWTR's 2022-10-27). */
-  endedOn: string | null;
-  /** The symbol's change as `quote` reads it; null when it has none, or was read on a listing abroad. */
-  change: TickerChange | null;
-  /**
-   * The line a command with nothing to serve for the symbol says: `quote`'s
-   * change line when its company left it ("FB now lists ...; Meta Platforms
-   * trades as META (changed 2022-06-09)"), else, for a listing that stopped,
-   * "TWTR stopped trading 2022-10-27; no history or options served". Null
-   * for a symbol that trades as it always has.
-   */
-  note: string | null;
-}
-
-const NO_FATE: ListingFate = { endedOn: null, change: null, note: null };
-/** How long a fate whose change lookup started late waits for it. */
-const LATE_CHANGE_WAIT_MS = 2_000;
-
-/** `ListingFate` from a listing's quote (null when it has none) and its ticker changes. */
-export function describeListingFate(
-  listing: { symbol: string; exchange?: string | null },
-  quote: Quote | null,
-  changes: TickerChanges | null,
-  now = Date.now(),
-): ListingFate {
-  const symbol = listing.symbol.trim().toUpperCase();
-  const endedOn = quote ? endedTradingDate(quote, now) : null;
-  // A bare symbol read on a listing abroad (SXR8 -> XETRA) is not the US symbol the changes are of.
-  const abroad = !!quote && !!bareListingNote({ symbol, request: { symbol, exchange: listing.exchange ?? "" } }, quote);
-  const change = abroad ? null : describeTickerChange(symbol, changes, tradingListing(quote, now));
-  const note = tickerChangeLine(change) ?? (endedOn ? `${symbol} stopped trading ${endedOn}; no history or options served` : null);
-  return { endedOn, change, note };
+export function movedSymbolLine(change: MovedTickerChange, retry: string | null): string {
+  return retry ? `${change.note}: \`${retry}\`` : change.note;
 }
 
 /**
- * `describeListingFate` for a listing: its quote is `quote` when the command
- * has it, else loaded; its changes come from `changes` when the command started
- * that lookup beside its own request, else from one started here. Fails soft:
- * a source that does not answer says nothing became of it.
+ * Fails a command that has nothing to serve for a symbol whose company
+ * moved (`ListingFate.moved`) with `movedSymbolLine`; `--json` reads the
+ * change as quote rows carry it (`tickerChange`) and the command that asks
+ * for the new symbol (`retry`). Exits as any failure does.
  */
-export async function loadListingFate(
-  listing: { symbol: string; exchange?: string | null; request?: { symbol: string; exchange: string } },
-  dataProvider: Pick<DataProvider, "getQuote" | "getTickerChanges">,
-  options: { quote?: Quote | null | Promise<Quote | null>; changes?: TickerChangeLookup } = {},
-): Promise<ListingFate> {
-  const request = listing.request ?? { symbol: listing.symbol, exchange: listing.exchange ?? "" };
-  const lookup = options.changes ?? startTickerChangeLookup(dataProvider, listing.symbol, listing.exchange);
-  try {
-    const [quote, changes] = await Promise.all([
-      options.quote !== undefined ? options.quote : dataProvider.getQuote(request.symbol, request.exchange).catch(() => null),
-      options.changes ? lookup.settle() : lookup.settle(LATE_CHANGE_WAIT_MS),
-    ]);
-    return describeListingFate(listing, quote, changes);
-  } catch {
-    return NO_FATE;
-  }
+export function failMovedSymbol(change: MovedTickerChange, request: Pick<ListingDataRequest, "command" | "retry">): never {
+  const retry = retryCommand(request, change.tradesAs);
+  return failWithFields(movedSymbolLine(change, retry), "ticker_moved", { tickerChange: change, retry });
 }
 
 /**
@@ -745,41 +664,28 @@ export function listingFateLoader(
 }
 
 /**
- * The lines a command says about a symbol's fate beside what it served. With
- * nothing served, `fate.note`. With data, `quote`'s change line when the
- * symbol's company left it (FB's bars are the fund listed there now), and, for
- * bars from before the symbol's holder took it (META's from 2021), that they
- * are from its old symbol: "Includes FB-era bars: META was FB until 2022-06-09".
+ * A command's load for one listing beside its fate (`listingFateLoader`): a
+ * symbol whose company moved serves nothing, whatever came back or failed,
+ * and the command fails naming its new symbol (`failMovedSymbol`). A loader
+ * that finds that itself (`MovedSymbolError`) fails the same way.
  */
-export function listingFateNotes(fate: ListingFate, served: { served: boolean; firstDate?: string | null }): string[] {
-  if (!served.served) return fate.note ? [fate.note] : [];
-  const { change } = fate;
-  const first = served.firstDate?.slice(0, 10);
-  const earlier = change?.kind === "formerly" && first ? change.changes.filter((hop) => first < hop.date).map((hop) => hop.from) : [];
-  return [
-    tickerChangeLine(change),
-    earlier.length > 0 ? `Includes ${earlier.join("- and ")}-era bars: ${change!.note}` : null,
-  ].filter((line): line is string => !!line);
-}
-
-// The zones of the US exchanges; a venue in another is abroad.
-const US_TIME_ZONES = new Set(["America/New_York", "America/Chicago"]);
-
-/**
- * "SXR8 -> XETRA" for a bare symbol the data service read on its home listing
- * abroad, as it reads a symbol with no US listing whose listings belong to one
- * company or fund: a row that shows the symbol as typed says which listing it
- * is. Null for a named or saved venue, and for a venue the app does not place
- * outside the US (a US exchange, OTC, a futures exchange).
- */
-export function bareListingNote(
-  listing: Pick<CliListing, "symbol" | "request">,
-  quote: Pick<Quote, "listingExchangeName" | "exchangeName"> | null | undefined,
-): string | null {
-  if (listing.request.exchange || !quote || !/^[A-Z0-9]{1,10}$/.test(listing.symbol)) return null;
-  const venue = canonicalExchange(quote.listingExchangeName || quote.exchangeName);
-  const zone = resolveExchangeTimeZone(venue);
-  return zone && !US_TIME_ZONES.has(zone) && !isUsListingExchange(venue) ? `${listing.symbol} -> ${venue}` : null;
+export async function refuseMovedListing<T>(
+  fate: (() => Promise<ListingFate>) | null,
+  request: Pick<ListingDataRequest, "command" | "retry">,
+  load: () => Promise<T>,
+): Promise<T> {
+  let value: T;
+  try {
+    value = await load();
+  } catch (error) {
+    if (error instanceof MovedSymbolError) failMovedSymbol(error.change, request);
+    const moved = (await fate?.())?.moved;
+    if (moved) failMovedSymbol(moved, request);
+    throw error;
+  }
+  const moved = (await fate?.())?.moved;
+  if (moved) failMovedSymbol(moved, request);
+  return value;
 }
 
 /**
@@ -802,8 +708,9 @@ export function tradingBoardNote(
  * calls what it returned empty, and a listing's exchange is one its symbol does
  * not trade on, the command ends in that message instead of the request's own
  * "unavailable". With `request`, a bare symbol no source serves ends naming
- * its other listings (`otherListingsMessage`). A request that succeeds costs no
- * extra lookup.
+ * its other listings (`otherListingsMessage`), and with `request.fate` a symbol
+ * whose company moved ends naming its new symbol, served or not. A request
+ * that succeeds costs no extra lookup beyond the fate the command reads anyway.
  */
 export async function loadForListing<T>(
   listings: ListingForLoad | readonly ListingForLoad[],
@@ -823,12 +730,20 @@ export async function loadForListing<T>(
     await checkVenues();
     if (request && all.length === 1 && isNoProviderError(error)) {
       const [other, fate] = await Promise.all([otherListingsMessage(all[0]!, deps, request), request.fate?.() ?? null]);
+      // Nothing served either way: a company that moved is under its new symbol, before any other listing.
+      const moved = movedAwayChange(fate?.change);
+      if (moved) failMovedSymbol(moved, request);
       if (other) ctx.fail(other.message, [fate?.note, other.details].filter(Boolean).join("\n"));
       if (fate?.note) ctx.fail(`${fate.note}.`);
     }
     throw error;
   }
   if (isMiss?.(value)) await checkVenues();
+  // Data came back, but the symbol's company moved and nothing new lists there: the data is another security's.
+  if (request?.fate && all.length === 1) {
+    const { moved } = await request.fate();
+    if (moved) failMovedSymbol(moved, request);
+  }
   return value;
 }
 
@@ -969,10 +884,18 @@ export function listingIdentity(
 
 /** The listing's own quote, for its company name and venue; null when it has none. */
 export async function loadListingQuote(dataProvider: DataProvider, listing: Pick<CliListing, "request">): Promise<Quote | null> {
+  return (await loadListingQuoteAnswer(dataProvider, listing)).quote;
+}
+
+/** The listing's own quote, or the error its request failed with: "Not a ticker: PALANTIR." for a name typed as a symbol. */
+export async function loadListingQuoteAnswer(
+  dataProvider: DataProvider,
+  listing: Pick<CliListing, "request">,
+): Promise<{ quote: Quote | null; error?: unknown }> {
   try {
-    return await dataProvider.getQuote(listing.request.symbol, listing.request.exchange);
-  } catch {
-    return null;
+    return { quote: await dataProvider.getQuote(listing.request.symbol, listing.request.exchange) };
+  } catch (error) {
+    return { quote: null, error };
   }
 }
 

package/src/cli/listing-suggestion.ts

@@ -5,6 +5,7 @@ import { mapWithConcurrency } from "../utils/concurrency";
 import { isUsListingExchange } from "../utils/exchanges";
 import { STARTER_SYMBOLS } from "../tickers/starter-symbols";
 import { TickerNotFoundError } from "./ticker-resolution";
+import { typoDistance } from "../utils/typo-distance";
 
 /** How long a suggestion waits for search; a slow search leaves the plain "not found" as it was. */
 const SUGGESTION_TIMEOUT_MS = 6_000;
@@ -39,25 +40,6 @@ 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() ?? "";
 }
@@ -68,7 +50,7 @@ function nearness(typed: string, candidate: TickerSearchCandidate): number | nul
   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;
+  return wanted.length >= MIN_TYPO_LENGTH && symbol.length >= MIN_TYPO_LENGTH && typoDistance(wanted, symbol) === 1 ? 1 : null;
 }
 
 /**
@@ -154,7 +136,7 @@ export async function suggestUsTicker(typed: string, deps: SuggestionDeps): Prom
   const saved = (await deps.store.loadAllTickers().catch(() => [])).filter((ticker) => isUsListingExchange(ticker.metadata.exchange));
   const near = new Set([...STARTER_SYMBOLS, ...saved.map((ticker) => ticker.metadata.ticker)]
     .map((symbol) => symbol.trim().toUpperCase())
-    .filter((symbol) => compact(symbol).length >= MIN_TYPO_LENGTH && editDistance(wanted, compact(symbol)) === 1));
+    .filter((symbol) => compact(symbol).length >= MIN_TYPO_LENGTH && typoDistance(wanted, compact(symbol)) === 1));
   if (near.size !== 1) return null;
   const [symbol] = near;
   const candidates = await searchCandidates(symbol!, deps);

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

@@ -26,6 +26,7 @@ import {
 } from "../../utils/cli-output";
 import { renderGlossaryEntries, type GlossaryLookup } from "../glossary";
 import { renderSeriesMatches, type SeriesMatch } from "../series-search";
+import { typoDistance } from "../../utils/typo-distance";
 
 export interface PaneFunctionCatalog {
   panes: ReadonlyMap<string, PaneDef>;
@@ -152,6 +153,55 @@ export function findFunctionCode(registry: PaneFunctionCatalog, token: string):
   };
 }
 
+/** A function code a typed one is a slip away from: what to type, and the function's name. */
+export interface NearFunctionCode {
+  code: string;
+  label: string;
+}
+
+/** Typed names shorter than this are too short for one slip to leave them recognisable (`HQ` is a slip from a dozen codes). */
+const MIN_CODE_TYPO_LENGTH = 3;
+/**
+ * A word typed as a command is as likely a ticker as a slip from a code
+ * (`PLTR`, `META`, `QQQ`): it is read as a slip only from this length and
+ * when its first letter is the code's.
+ */
+const MIN_COMMAND_WORD_TYPO_LENGTH = 4;
+/** Near codes an unknown one is answered with; more than this many is no suggestion. */
+const NEAR_CODE_LIMIT = 3;
+
+/**
+ * The function codes one slip of the keys from a name that opens no function
+ * (a letter swapped, missing, extra or wrong: `RCDF` for RDCF, `HPP` for HP),
+ * among the mnemonics the command bar takes, each named by the code it is
+ * near (`DES` for Ticker Research, whose code is T). Empty when none is that
+ * close, the name is too short to tell, or so many are that none stands out.
+ * A word typed as a command (`commandWord`, `gloomberb RCDF PLTR`) is held to
+ * MIN_COMMAND_WORD_TYPO_LENGTH and the code's first letter, so a ticker typed
+ * there is not taken for a code.
+ */
+export function nearFunctionCodes(
+  registry: PaneFunctionCatalog,
+  name: string,
+  { commandWord = false }: { commandWord?: boolean } = {},
+): NearFunctionCode[] {
+  const wanted = normalizeLookupToken(name);
+  if (wanted.length < (commandWord ? MIN_COMMAND_WORD_TYPO_LENGTH : MIN_CODE_TYPO_LENGTH)) return [];
+  const near = new Map<PaneTemplateDef, string>();
+  for (const template of registry.paneTemplates.values()) {
+    const prefix = template.shortcut?.prefix;
+    if (!prefix) continue;
+    const code = [prefix, ...template.shortcut?.aliases ?? []].find((candidate) => {
+      const known = normalizeLookupToken(candidate);
+      return (!commandWord || known[0] === wanted[0]) && typoDistance(wanted, known) === 1;
+    });
+    if (code) near.set(template, code.toUpperCase());
+  }
+  if (near.size > NEAR_CODE_LIMIT) return [];
+  return [...near].map(([template, code]) => ({ code, label: template.label }))
+    .sort((left, right) => left.code.localeCompare(right.code));
+}
+
 function sampleArgForTemplate(template: PaneTemplateDef): string {
   switch (template.shortcut?.argKind) {
     case "ticker":

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

@@ -44,6 +44,12 @@ export interface ReportFreshness {
   basis?: string;
   /** Set when the dates are the start of a period: the status line then reads `Sep 2026 (monthly)`. */
   periodicity?: "monthly" | "quarterly" | "annual";
+  /**
+   * The newest bar's week or month had not ended, and the last day it covers
+   * so far (`asOf`, when known): the status line reads `month to date, through
+   * Thu 15 Oct 2026`.
+   */
+  periodToDate?: { period: "week" | "month"; through?: string };
   /** The local date of the session close `asOf` is, when the newest observation is its venue's latest close. */
   asOfClose?: string;
   /**
@@ -346,11 +352,20 @@ function declaredSources(declared: HeadlessPaneFreshness, now: number): Array<{
   });
 }
 
+/** A declared bar period still forming, its last day read as a date; null for anything else. */
+function readPeriodToDate(declared: HeadlessPaneFreshness["periodToDate"], now: number): { period: "week" | "month"; through: ReportTime | null } | null {
+  if (declared?.period !== "week" && declared?.period !== "month") return null;
+  const through = declared.through ? parseReportTime(declared.through) : null;
+  return { period: declared.period, through: through?.dateOnly && through.time <= now + FUTURE_TOLERANCE_MS ? through : null };
+}
+
 function resolveFreshness({ declared, signals, observations, now }: FreshnessInputs): ReportFreshness {
   const sources = declaredSources(declared, now);
   // Sources date the data by their own observations, as a declared as-of does.
   const declaredAsOf = observedTime({ asOf: declared.asOf }, now, ["asOf"]) ?? newest(sources.map(({ time }) => time));
-  const asOf = declaredAsOf ?? newest([...observations.units, ...observations.extra]);
+  // A bar still forming covers its period through a later day than the one it is dated by.
+  const periodToDate = readPeriodToDate(declared.periodToDate, now);
+  const asOf = declaredAsOf ?? periodToDate?.through ?? newest([...observations.units, ...observations.extra]);
   // The oldest source, not the newest, says how far behind the view can be.
   const agedFrom = sources.length ? oldest(sources.map(({ time }) => time))
     : declared.oldestAge ? oldest(observations.units) ?? asOf : null;
@@ -443,6 +458,7 @@ function resolveFreshness({ declared, signals, observations, now }: FreshnessInp
     ...(partial ?? {}),
     ...(status === "not-a-feed" && declared.basis ? { basis: declared.basis } : {}),
     ...(periodicity ? { periodicity } : {}),
+    ...(periodToDate && !declaredAsOf ? { periodToDate: { period: periodToDate.period, ...(periodToDate.through ? { through: isoTime(periodToDate.through) } : {}) } } : {}),
     ...(asOfClose ? { asOfClose } : {}),
     ...(tradingDayMarket ? { tradingDayMarket } : {}),
     ...(market ? { market } : {}),
@@ -550,6 +566,16 @@ function periodText(date: string, periodicity: NonNullable<ReportFreshness["peri
       : `${year}`;
 }
 
+/**
+ * A bar still forming: `month to date, through Thu 15 Oct 2026`, or with no
+ * day to name, the period from its start, `Oct 2026 to date` or `week of Mon
+ * 12 Oct 2026 to date`.
+ */
+export function periodToDateText({ period, through }: NonNullable<ReportFreshness["periodToDate"]>, asOf: string): string {
+  if (through) return `${period} to date, through ${dayText(through)}`;
+  return period === "month" ? `${periodText(asOf, "monthly")} to date` : `week of ${dayText(asOf)} to date`;
+}
+
 /** The period a FRED series frequency ("Monthly", "Quarterly") publishes in; null for daily and weekly series, whose dates are days. */
 export function periodicityOf(frequency: string | null | undefined): ReportFreshness["periodicity"] | null {
   const word = frequency?.trim().toLowerCase() ?? "";
@@ -674,7 +700,8 @@ function asOfText(freshness: ReportFreshness, short: boolean, local: boolean, un
   const market = freshness.tradingDayMarket;
   const period = freshness.periodicity;
   const time = parseReportTime(freshness.asOf);
-  const asOf = period ? `${periodText(freshness.asOf, period)} (${period})`
+  const asOf = freshness.periodToDate ? periodToDateText(freshness.periodToDate, freshness.asOf)
+    : period ? `${periodText(freshness.asOf, period)} (${period})`
     : freshness.asOfClose
       ? `${tradingDayText(freshness.asOfClose, market)} close`
       : time?.dateOnly ? tradingDayText(freshness.asOf, market)
@@ -706,16 +733,22 @@ function sourcesAsOfParts(freshness: ReportFreshness, sources: readonly ReportSo
  * When the first venue opens again: its UTC time when that is later the same
  * UTC day, else its weekday at the venue (`Mon`), with the date a week out.
  */
-function reopenText(market: ReportMarket, now: number, local: boolean): string | null {
+function reopenText(market: ReportMarket, now: number, local: boolean): { text: string; time: boolean } | null {
   if (!market.reopensAt || !market.reopensOn) return null;
   const at = Date.parse(market.reopensAt);
   if (!Number.isFinite(at)) return null;
   const iso = new Date(at).toISOString();
-  if (iso.slice(0, 10) === new Date(now).toISOString().slice(0, 10)) return `${iso.slice(11, 16)} UTC${local ? localTimeSuffix(at) : ""}`;
-  return at - now > WEEKDAY_ONLY_MS ? dayText(market.reopensOn) : WEEKDAYS[new Date(`${market.reopensOn}T00:00:00Z`).getUTCDay()]!;
+  if (iso.slice(0, 10) === new Date(now).toISOString().slice(0, 10)) return { text: `${iso.slice(11, 16)} UTC${local ? localTimeSuffix(at) : ""}`, time: true };
+  return { text: at - now > WEEKDAY_ONLY_MS ? dayText(market.reopensOn) : WEEKDAYS[new Date(`${market.reopensOn}T00:00:00Z`).getUTCDay()]!, time: false };
 }
 
-/** `markets closed until Mon`; `short` is the compact form a narrow capture falls back to (`reopens Mon`). */
+/**
+ * `markets closed until Mon`; `short` is the compact form a narrow capture
+ * falls back to (`reopens Mon`). A time is always the regular session's open,
+ * and says so (`pre-market open · regular session opens 13:30 UTC`), so it is
+ * never read as when the pre-market opens, nor a US market as closed until
+ * then while its pre-market trades first.
+ */
 function marketText(market: ReportMarket, now: number, short: boolean, local: boolean): string {
   const reopen = reopenText(market, now, local);
   switch (market.state) {
@@ -724,10 +757,12 @@ function marketText(market: ReportMarket, now: number, short: boolean, local: bo
     case "after-hours":
       return "after hours";
     case "pre-market":
-      return reopen ? `pre-market, opens ${reopen}` : "pre-market";
+      if (!reopen) return "pre-market open";
+      return short ? `pre-market · regular opens ${reopen.text}` : `pre-market open · regular session opens ${reopen.text}`;
     case "closed":
-      if (short) return reopen ? `reopens ${reopen}` : "closed";
-      return reopen ? `markets closed until ${reopen}` : "markets closed";
+      if (!reopen) return short ? "closed" : "markets closed";
+      if (reopen.time) return short ? `regular opens ${reopen.text}` : `markets closed · regular session opens ${reopen.text}`;
+      return short ? `reopens ${reopen.text}` : `markets closed until ${reopen.text}`;
     default: {
       const _exhaustive: never = market.state;
       return _exhaustive;

package/src/cli/pane-functions/function-help.ts

@@ -68,10 +68,10 @@ const QUOTES: FunctionFreshness = { free: "15 minutes delayed, crypto real-time"
 /** US option chains and the quotes behind them. */
 const OPTIONS: FunctionFreshness = { free: DELAYED, pro: REAL_TIME };
 const FX: FunctionFreshness = { free: DELAYED, pro: REAL_TIME };
-/** Open interest settles once a session; spot and the quotes behind gamma follow the plan. */
+/** Open interest is counted once a session and reaches Gloom about two sessions late; spot and the quotes behind gamma follow the plan. */
 const OPX_DATA: FunctionFreshness = {
-  free: "Open interest as of the prior session; spot and gamma 15 minutes delayed",
-  pro: "Open interest as of the prior session; spot and gamma real-time",
+  free: "Open interest about two sessions old, its date in the footer; spot and gamma 15 minutes delayed",
+  pro: "Open interest about two sessions old, its date in the footer; spot and gamma real-time",
 };
 const NEWS: FunctionFreshness = { free: "12 hours delayed", pro: REAL_TIME };
 const US_SCANNER: FunctionFreshness = { free: DELAYED, pro: REAL_TIME };
@@ -175,7 +175,7 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     bloomberg: ["DDIS"],
   },
   HP: {
-    summary: "Daily open, high, low, close and volume in a scrollable table.",
+    summary: "Open, high, low, close and volume in a scrollable table: daily bars over 3M to start, weekly for 5Y and monthly for ALL. The newest bar is marked to date while its day, week or month runs on.",
     usage: ["HP AAPL"],
     keys: [key("t", " range")],
     data: QUOTES,
@@ -241,14 +241,14 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     bloomberg: ["OMON"],
   },
   OPX: {
-    summary: "Open interest by strike for one expiry with max pain and spot marked, every expiry's open interest, put/call ratio and max pain, and dealer gamma (GEX) by strike with its flip level and a range for the dealer assumption. MAXPAIN opens it too.",
+    summary: "Open interest by strike for one expiry with max pain and spot marked, every expiry's open interest, put/call ratio, max pain and net dealer gamma, and dealer gamma (GEX) by strike with its flip level, call and put walls and a range for the dealer assumption. MAXPAIN opens it too.",
     usage: ["OPX", "OPX SPY", "OPX SPX"],
     keys: [TABS, OPEN],
     data: OPX_DATA,
     bloomberg: ["OPX"],
   },
   GEX: {
-    summary: "Net dealer gamma by strike across every expiry or one, with the total, the flip level and a range for the dealer assumption. The GEX tab of OPX.",
+    summary: "Net dealer gamma by strike across every expiry or one, with the total, the flip level, the call and put walls and a range for the dealer assumption. The GEX tab of OPX.",
     usage: ["GEX", "GEX SPY", "GEX SPX"],
     keys: [TABS],
     data: OPX_DATA,
@@ -756,7 +756,7 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     bloomberg: ["GLCO"],
   },
   CTM: {
-    summary: "A futures root's listed contracts as a curve against a week and a month ago, with roll yield, contango or backwardation, and each contract's price, open interest and volume. Takes a FUT root, VX or a CME crypto root (BTC, ETH, SOL, XRP), which also shows each contract's premium to spot and annualised basis against the USD pair quote.",
+    summary: "A futures root's listed contracts as a curve against a week and a month ago, with roll yield, contango or backwardation, and each contract's price, open interest and volume. Takes a FUT root, VX or a CME crypto root (BTC, ETH, SOL, XRP), which also shows each contract's premium to spot and annualised basis against the USD pair quote: Ann Basis = (Last / spot - 1) × 365 / days to expiry, simple actual/365.",
     usage: ["CTM GC", "CTM BTC"],
     keys: [key("d", "ate"), key("c", "urrent"), STEP],
     data: same("Delayed, usually 10 minutes; VIX at settlement"),
@@ -1068,8 +1068,8 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     bloomberg: ["13F"],
   },
   INS: {
-    summary: "Insider buys, sells, awards and gifts from Form 4 filings, with insider name, size and price. US equities.",
-    usage: ["INS NVDA"],
+    summary: "Insider buys, sells, awards and gifts from Form 4 filings, with insider name, size and price. US equities. Alone it ranks the companies whose insiders are buying in the open market, with why.",
+    usage: ["INS NVDA", "INS"],
     keys: [OPEN, key("f", "ilter")],
     data: AS_FILED,
     bloomberg: ["INS"],

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

@@ -286,6 +286,7 @@ function serializeBundleSection(
       title: section.title,
       columns: serializableColumns(columns),
       rows: section.rows,
+      ...(section.unit ? { unit: section.unit } : {}),
       ...(section.empty && section.rows.length === 0 ? { empty: section.empty } : {}),
     };
   }
@@ -410,9 +411,20 @@ function seriesPointExportDate(series: HeadlessSeries, date: SeriesPointDate): s
   return isDateOnly(date) ? date as string : new Date(time).toISOString().replace(".000Z", "Z");
 }
 
+/**
+ * A latest value as the series report prints it: percentages and multiples
+ * (P/E, EV/EBITDA, one series over another) to two decimals, which a multiple
+ * under 0.1 trades for three significant digits so a small ratio is not
+ * flattened to 0.03. The exports keep every digit. Any other unit prints as
+ * loaded, without float noise.
+ */
 function seriesValue(series: HeadlessSeries, value: number | null): string {
   if (value == null) return "-";
-  return series.unit?.trim() === "%" && Number.isFinite(value) ? value.toFixed(2) : displayNumber(value);
+  if (!Number.isFinite(value)) return displayNumber(value);
+  const unit = series.unit?.trim();
+  if (unit === "%") return value.toFixed(2);
+  if (unit?.toLowerCase() === "x") return value !== 0 && Math.abs(value) < 0.1 ? value.toPrecision(3) : value.toFixed(2);
+  return displayNumber(value);
 }
 
 function renderRows(
@@ -467,7 +479,7 @@ function renderBundle(
     renderSection(section.title),
     "rows" in section && section.rows
       ? renderRows(section.textRows ?? section.rows, section.textColumns ?? section.columns, definition.columns, section.empty)
-      : renderEntries(section.entries),
+      : renderEntries(section.textEntries ?? section.entries),
   ]);
 }
 
@@ -618,11 +630,11 @@ export function headlessReportTables(
       break;
     }
     case "bundle":
-      tables = (result as HeadlessBundleResult).sections.map((section) => (
-        "rows" in section && section.rows
-          ? exportRowsTable(section.title, displayedColumns(columnsFor(section.rows, section.columns, definition.columns)), section.rows)
-          : exportEntriesTable(section.title, section.entries)
-      ));
+      tables = (result as HeadlessBundleResult).sections.map((section) => {
+        if (!("rows" in section && section.rows)) return exportEntriesTable(section.title, section.entries);
+        const table = exportRowsTable(section.title, displayedColumns(columnsFor(section.rows, section.columns, definition.columns)), section.rows);
+        return section.unit?.trim() ? { ...table, identity: { currencyOrUnit: section.unit.trim() } } : table;
+      });
       break;
     case "series": {
       const seriesResult = result as HeadlessSeriesResult;