gloomberb 0.17.4 → 0.17.6

package/src/tickers/listing-fate.ts

@@ -0,0 +1,242 @@
+import type { DataProvider } from "../types/data-provider";
+import type { Quote } from "../types/financials";
+import type { TickerChanges } from "../types/ticker-changes";
+import {
+  describeTickerChange,
+  movedAwayChange,
+  quotedListing,
+  startTickerChangeLookup,
+  tickerChangeLine,
+  type CurrentListing,
+  type MovedTickerChange,
+  type TickerChange,
+  type TickerChangeLookup,
+} from "./ticker-changes";
+import { isQuoteBeforeLatestSession, isQuoteStaleForCurrentSession } from "../market-data/quotes/freshness";
+import { formatMarketPriceWithCurrency, quoteFormatOptions } from "../market-data/market/format";
+import { canonicalExchange, isUsListingExchange, parsePublicTickerKey, resolveExchangeTimeZone } from "../utils/exchanges";
+import { zonedDateKey } from "../utils/zoned-date-time";
+
+/*
+ * What became of a symbol, read the way `quote` reads it: the listing's own
+ * quote says whether and when it stopped trading, and the symbol's ticker
+ * changes say whether its company moved. The CLI commands and the app's panes
+ * both decide from here what a symbol has to serve.
+ */
+
+// 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).
+ */
+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;
+  /**
+   * The change when the symbol's company trades under another symbol now
+   * and its own quote shows nothing new listed under it (`movedAwayChange`):
+   * the old line, stopped or named for that company. Whatever data comes
+   * back under the symbol is then another security's (a listing abroad with
+   * the same letters, or the new symbol's bars under the old one), so a
+   * command or pane serves none and names the new symbol. Null without a
+   * quote to tell by.
+   */
+  moved: MovedTickerChange | null;
+}
+
+/** Nothing became of the symbol, or nothing could be told. */
+export const NO_FATE: ListingFate = { endedOn: null, change: null, note: null, moved: null };
+/** How long a fate waits for a change lookup it started late, or for a stopped line's. */
+export const LATE_CHANGE_WAIT_MS = 2_000;
+
+// 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: { symbol: string; request: { exchange: string } },
+  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;
+}
+
+/** `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: { 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, moved: quote ? movedAwayChange(change) : null };
+}
+
+/**
+ * Whether a quote's line stopped: a whole session traded without it, or it
+ * ended long ago. Only such a line can be a company that moved away, so only
+ * its change lookup is waited for.
+ */
+function mayHaveMoved(quote: Quote | null, now = Date.now()): boolean {
+  return !!quote && (isQuoteBeforeLatestSession(quote, now) || endedTradingDate(quote, now) != null);
+}
+
+/**
+ * `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.
+ */
+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 = await (options.quote !== undefined
+      ? options.quote
+      : dataProvider.getQuote(request.symbol, request.exchange).catch(() => null));
+    // A lookup started beside the command's request gets a short grace once that is ready, so a slow
+    // one never holds a symbol that trades. A line that stopped is waited for: only its company can
+    // have moved, and then the answer decides whether the command serves anything at all.
+    const changes = await lookup.settle(!options.changes || mayHaveMoved(quote) ? LATE_CHANGE_WAIT_MS : undefined);
+    return describeListingFate(listing, quote, changes);
+  } catch {
+    return NO_FATE;
+  }
+}
+
+/**
+ * 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".
+ */
+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);
+}
+
+/**
+ * What a report or loader with nothing of its own to serve for a symbol
+ * throws when the symbol's company moved (`ListingFate.moved`): its message
+ * is the change's line, "HFC became DINO on 2022-03-15".
+ */
+export class MovedSymbolError extends Error {
+  constructor(readonly change: MovedTickerChange) {
+    super(change.note);
+    this.name = "MovedSymbolError";
+  }
+}
+
+/**
+ * The listing an instrument's fate is read for: its symbol without the venue
+ * a key carries (HFC:NYSE is HFC on NYSE). Null for a broker's contract,
+ * which is not a listing the change history is about.
+ */
+export function fateListing(instrument: {
+  symbol: string;
+  exchange?: string | null;
+  brokerId?: string;
+  instrument?: unknown;
+}): { symbol: string; exchange: string } | null {
+  if (instrument.brokerId || instrument.instrument) return null;
+  const key = parsePublicTickerKey(instrument.symbol);
+  return { symbol: key.symbol, exchange: key.exchange ?? instrument.exchange ?? "" };
+}
+
+/**
+ * What a pane does with a symbol: serve it, wait to know, or show that its
+ * company moved (`ListingFate.moved`) instead of another security's data.
+ * A symbol waits only while what is known says nothing trades under it: a
+ * quote that shows the line ended waits for the change lookup, and a change
+ * that says the company left with nothing known listed there waits for the
+ * quote. Any other symbol is served at once, whatever is still coming, a
+ * quote cached from an earlier session included. A lookup that failed or
+ * answered nothing is no change.
+ */
+export type ListingFateGate =
+  | { kind: "serve" }
+  | { kind: "wait" }
+  | { kind: "moved"; change: MovedTickerChange };
+
+const SERVE: ListingFateGate = { kind: "serve" };
+const WAIT: ListingFateGate = { kind: "wait" };
+
+/**
+ * `ListingFateGate` from what is known so far. `quote` and `changes` are
+ * undefined while they load and null when there is none. A move on record
+ * is told by the quote, which says whether the old line stopped or something
+ * new trades there (FB's fund); until it is in, the change's own word on
+ * what lists there now decides whether to wait for it.
+ */
+export function listingFateGate(
+  listing: { symbol: string; exchange?: string | null },
+  { quote, changes }: { quote: Quote | null | undefined; changes: TickerChanges | null | undefined },
+  now = Date.now(),
+): ListingFateGate {
+  if (changes === undefined) return quote && endedTradingDate(quote, now) ? WAIT : SERVE;
+  if (!changes?.moved) return SERVE;
+  if (quote === undefined) return movedAwayChange(describeTickerChange(listing.symbol, changes)) ? WAIT : SERVE;
+  const { moved } = describeListingFate(listing, quote, changes, now);
+  return moved ? { kind: "moved", change: moved } : SERVE;
+}

package/src/tickers/open-target.ts

@@ -1,5 +1,6 @@
 import type { AppTickerRepositoryPort } from "../core/app-service-ports";
 import type { SearchRequestContext, DataProvider } from "../types/data-provider";
+import type { Quote } from "../types/financials";
 import type { TickerRecord } from "../types/ticker";
 import {
   AmbiguousTickerError,
@@ -17,6 +18,15 @@ import { settleTypedListingKey } from "./listing-venues";
 
 export type { TickerOpenTarget } from "./search/types";
 
+/**
+ * What an open that found nothing says: neither the key's own quote nor the
+ * listing search found the listing. Opens from a board row, a link and the
+ * command bar all say it the same way.
+ */
+export function tickerOpenFailureMessage(symbol: string): string {
+  return `Could not open ${symbol}: no quote or listing found.`;
+}
+
 export async function resolveTickerOpenTarget({
   query,
   tickers,
@@ -85,18 +95,22 @@ export async function resolveTickerOpenTarget({
     return { symbol: ticker.metadata.ticker, ticker, created, ...tickerSelectionFromSearchResult(resolved.result) };
   }
 
+  let quote: Quote | null = null;
+  try {
+    quote = await dataProvider.getQuote(symbol, "", publicOnly ? { instrument: null } : undefined);
+  } catch {
+    // No source has a price for the key right now.
+  }
+  const quoteExchange = quote ? quote.listingExchangeName ?? quote.exchangeName : undefined;
+  // A public open (a board row, a link) skips search for its quote. When the
+  // quote cannot vouch for the listing, because no source prices it right now
+  // or the one that answers prices another venue, search still lists it as
+  // the command bar reads it, and the pane shows the quote's own state.
+  if (!quote || (preserveListingKey && !quoteNamesListing(quote))) {
+    return publicOnly ? openListedPublicTarget() : null;
+  }
+
   try {
-    const quote = await dataProvider.getQuote(symbol, "", publicOnly ? { instrument: null } : undefined);
-    const quoteExchange = quote.listingExchangeName ?? quote.exchangeName;
-    if (preserveListingKey && quoteExchange) {
-      const baseSymbol = requested.exchange ? requested.symbol : symbol.slice(0, symbol.lastIndexOf("."));
-      if (!findExactTickerSearchMatch([{ label: baseSymbol, right: quoteExchange }], symbol)) return null;
-    }
-    if (preserveListingKey) {
-      const listingAlias = requested.exchange ? getListingSymbol(requested.symbol, requested.exchange) : symbol;
-      const explicitAliasMatches = tickerHasListingSuffix(listingAlias) && normalizeTickerSymbol(quote.symbol) === listingAlias;
-      if (!explicitAliasMatches && !findExactTickerSearchMatch([{ label: quote.symbol, right: quoteExchange }], symbol)) return null;
-    }
     const quoteSymbol = preserveListingKey ? symbol : normalizeTickerSymbol(quote.symbol || symbol);
     const selection = publicOnly ? tickerSelectionFromSearchResult({ providerId: dataProvider.id, symbol: quoteSymbol,
       name: quote.name || quoteSymbol, exchange: requested.exchange ?? quoteExchange ?? "", currency: quote.currency, type: quote.instrumentType || "" }) : {};
@@ -122,4 +136,40 @@ export async function resolveTickerOpenTarget({
   } catch {
     return null;
   }
+
+  /** Whether the quote answered for the listing the key names, not the same symbol on another venue. */
+  function quoteNamesListing(answer: Quote): boolean {
+    try {
+      if (quoteExchange) {
+        const baseSymbol = requested.exchange ? requested.symbol : symbol.slice(0, symbol.lastIndexOf("."));
+        if (!findExactTickerSearchMatch([{ label: baseSymbol, right: quoteExchange }], symbol)) return false;
+      }
+      const listingAlias = requested.exchange ? getListingSymbol(requested.symbol, requested.exchange) : symbol;
+      const explicitAliasMatches = tickerHasListingSuffix(listingAlias) && normalizeTickerSymbol(answer.symbol) === listingAlias;
+      return explicitAliasMatches || !!findExactTickerSearchMatch([{ label: answer.symbol, right: quoteExchange }], symbol);
+    } catch {
+      return false;
+    }
+  }
+
+  async function openListedPublicTarget(): Promise<TickerOpenTarget | null> {
+    try {
+      // Public listings only: no saved ticker or broker contract stands in for the key.
+      const listed = await resolveTickerSearch({
+        query: symbol,
+        activeTicker: null,
+        tickers: new Map(),
+        dataProvider,
+        searchContext: { ...searchContext, preferBroker: false },
+      });
+      if (listed?.kind !== "provider" || listed.result.brokerContract) return null;
+      const { ticker, created } = await upsertTickerFromSearchResult(tickerRepository, listed.result, {
+        tickerSymbol: preserveListingKey ? symbol : undefined,
+      });
+      return { symbol: ticker.metadata.ticker, ticker, created, ...tickerSelectionFromSearchResult(listed.result) };
+    } catch (error) {
+      if (error instanceof AmbiguousTickerError) throw error;
+      return null;
+    }
+  }
 }

package/src/tickers/search/index.ts

@@ -2,7 +2,7 @@ import type { SearchRequestContext, DataProvider } from "../../types/data-provid
 import type { InstrumentSearchResult } from "../../types/instrument";
 import type { TickerRecord } from "../../types/ticker";
 import { canonicalExchange, isSharedExchangeCode, isUsListingExchange, parsePublicTickerKey, publicTickerKey, typedExchangeCode } from "../../utils/exchanges";
-import { getListingSymbol, tickerHasListingSuffix } from "../../sources/listing-symbols";
+import { getListingSymbol, listingSuffixConflictsWithExchange, tickerHasListingSuffix } from "../../sources/listing-symbols";
 import { parseOptionSymbol } from "../../utils/options";
 import { resolveCurrencyUnit } from "../../utils/currency-units";
 import { currencyPairSpelling } from "../../utils/currency-pair";
@@ -33,6 +33,7 @@ import {
 } from "./result";
 
 import { typedPerpetualListing } from "../perpetual-listing";
+import { settleWithin } from "../../utils/async-deadline";
 export type {
   ResolvedTickerSearch,
   TickerSearchCandidate,
@@ -319,18 +320,59 @@ export function resolveTickerSearch(options: ResolveTickerSearchOptions): Promis
   const symbol = future?.symbol ?? (pair && !pair.ambiguous ? pair.symbol : typed);
   const literal = resolveTickerSymbol(symbol, options, pickListing ? requested : null);
   const alternatives = pickListing ? [] : [...dottedVenueQueries(symbol), ...pair?.ambiguous ? [pair.symbol] : []];
+  // A listing suffix search does not carry (CEZ.PR) is read from its own quote, as `quote` reads it.
+  const quoted = !pickListing && tickerHasListingSuffix(symbol) && !parsePublicTickerKey(symbol).exchange;
   // Most input has no venue code to retry: hand back the literal lookup
   // itself, so it settles no later than it did before the retry existed.
-  if (alternatives.length === 0) return literal;
+  if (alternatives.length === 0 && !quoted) return literal;
   return literal.then(async (resolved) => {
     for (const alternative of resolved ? [] : alternatives) {
       const match = await resolveTickerSymbol(alternative, options, null);
       if (match) return match;
     }
-    return resolved;
+    return resolved ?? (quoted ? quotedSuffixListing(symbol, options) : null);
   });
 }
 
+/** As long as a search source gets: past it, the key reads as unmatched. */
+const SUFFIX_QUOTE_TIMEOUT_MS = 5_000;
+
+/**
+ * A suffixed listing (CEZ.PR, PETR4.SA, VOLV-B.ST) that search does not list,
+ * vouched for by its own quote: the quote answers for that key, prices it, and
+ * names a venue the suffix belongs to. This is how `quote` and opening the
+ * key from the command bar read it, so adding it to a watchlist, a portfolio
+ * or the first-run positions takes the same listing.
+ */
+async function quotedSuffixListing(
+  symbol: string,
+  { dataProvider, searchContext }: ResolveTickerSearchOptions,
+): Promise<ResolvedTickerSearch | null> {
+  // No source prices the key, or none answers in time: it stays unmatched.
+  const quote = await settleWithin(dataProvider.getQuote(symbol, "", {
+    brokerId: searchContext?.brokerId,
+    brokerInstanceId: searchContext?.brokerInstanceId,
+  }), SUFFIX_QUOTE_TIMEOUT_MS);
+  if (!quote) return null;
+  const exchange = canonicalExchange(quote.listingExchangeName || quote.exchangeName);
+  if (!exchange || normalizeTickerSymbol(quote.symbol || "") !== symbol
+    || !Number.isFinite(quote.price) || quote.price === 0
+    || listingSuffixConflictsWithExchange(symbol, exchange)) return null;
+  return {
+    kind: "provider",
+    symbol,
+    result: {
+      providerId: dataProvider.id,
+      symbol,
+      name: quote.name?.trim() || symbol,
+      exchange,
+      currency: quote.currency || undefined,
+      type: quote.instrumentType || "",
+    },
+    quote,
+  };
+}
+
 async function resolveTickerSymbol(
   symbol: string,
   { tickers, dataProvider, searchContext }: ResolveTickerSearchOptions,

package/src/tickers/search/ranking.ts

@@ -252,6 +252,7 @@ export function rankTickerSearchItems<T extends Pick<TickerSearchRankableItem, "
           : null,
         explicitIntentScore,
         themeFund: themeWord != null && isThemeFund(item, themeWord) ? 1 : 0,
+        themeCompany: themeWord != null && isThemeCompany(item, themeWord) ? 1 : 0,
         normalizedSymbol: normalizeSearchText(item.symbol || item.label),
         symbolMatchRank: scoreSymbolMatchRank(intent, item),
         nameOnly: companyMatchRank > 0 && labelScore + aliasScore <= 0
@@ -270,6 +271,14 @@ export function rankTickerSearchItems<T extends Pick<TickerSearchRankableItem, "
     if (!namedCompany && leadingFunds.size < LEADING_THEME_FUNDS) leadingFunds.add(symbol);
     if (!leadingFunds.has(symbol)) entry.themeFund = 0;
   }
+  // The companies the server sent with the theme (Albemarle, SQM and PLS for "lithium") follow those funds, in its
+  // order, ahead of the smaller companies whose names carry the word, so the leaders are on the first screen.
+  const leadingCompanies = new Set<string>();
+  for (const entry of ranked.filter(({ themeCompany }) => themeCompany).sort(byProviderRank)) {
+    const key = getTickerSearchListingKey(entry.item);
+    if (!namedCompany && leadingCompanies.size < LEADING_THEME_COMPANIES) leadingCompanies.add(key);
+    if (!leadingCompanies.has(key)) entry.themeCompany = 0;
+  }
 
   // A saved symbol replaces its own source listing, not every exchange using it.
   const matchedLocalListings = new Set(
@@ -374,7 +383,7 @@ export function rankTickerSearchItems<T extends Pick<TickerSearchRankableItem, "
 
   filtered.sort((a, b) => {
     // Precedence is exact symbol, explicit query hints, a sector word's funds
-    // in the server's order, whole-word company relevance, issuer relevance, provider order within that issuer, partial
+    // and then the companies sent with it, each in the server's order, whole-word company relevance, issuer relevance, provider order within that issuer, partial
     // symbol, saved relevance, then stable source order.
     const aExactSymbolRank = a.symbolMatchRank >= 2 ? a.symbolMatchRank : 0;
     const bExactSymbolRank = b.symbolMatchRank >= 2 ? b.symbolMatchRank : 0;
@@ -383,7 +392,8 @@ export function rankTickerSearchItems<T extends Pick<TickerSearchRankableItem, "
       return b.explicitIntentScore - a.explicitIntentScore;
     }
     if (b.themeFund !== a.themeFund) return b.themeFund - a.themeFund;
-    if (a.themeFund) {
+    if (b.themeCompany !== a.themeCompany) return b.themeCompany - a.themeCompany;
+    if (a.themeFund || a.themeCompany) {
       const aProviderRank = a.item.providerRank ?? Number.POSITIVE_INFINITY;
       const bProviderRank = b.item.providerRank ?? Number.POSITIVE_INFINITY;
       if (aProviderRank !== bProviderRank) return aProviderRank - bProviderRank;
@@ -589,6 +599,13 @@ export function themeQueryWord(
 
 /** How many sector funds lead a sector word's list: the rest of the list is the companies named for it. */
 const LEADING_THEME_FUNDS = 5;
+/** How many companies sent with a sector word follow its funds, before the companies named for it. */
+const LEADING_THEME_COMPANIES = 5;
+
+/** A company the server sent with the theme: a sector's leader whose name need not say it (Albemarle for "lithium"). */
+function isThemeCompany(item: Partial<TickerSearchRankableItem>, word: string): boolean {
+  return item.instrumentClass === "equity" && !!item.searchKeywords?.some((keyword) => normalizeSearchText(keyword) === word);
+}
 
 /**
  * A fund that tracks the theme (sent with it, or named for it) on a US exchange, where the large sector funds

package/src/tickers/search/types.ts

@@ -1,4 +1,5 @@
 import type { BrokerContractRef, InstrumentSearchResult, TickerListingRef } from "../../types/instrument";
+import type { Quote } from "../../types/financials";
 import type { TickerRecord } from "../../types/ticker";
 
 export type TickerSearchInstrumentClass = "equity" | "fund" | "derivative" | "other";
@@ -44,6 +45,8 @@ export type ResolvedTickerSearch =
     result: InstrumentSearchResult;
     /** A bare symbol's other listings (SYM:EXCH) when its quote chose one of several. */
     otherListings?: string[];
+    /** The quote that vouched for a listing search does not carry, so the caller need not ask again. */
+    quote?: Quote;
   };
 
 export interface TickerOpenTarget {

package/src/tickers/search/upsert.ts

@@ -11,6 +11,25 @@ import {
 import { canonicalExchange, parsePublicTickerKey, publicTickerKey } from "../../utils/exchanges";
 import { scopedBrokerContractIdentityKey } from "../../utils/instrument-identity";
 
+/**
+ * The key a result is saved under when its symbol is already saved for
+ * another listing (`SAP:XETR` beside a saved SAP on NYSE), or null when the
+ * symbol's own key serves. Opening a second listing must never re-denominate
+ * existing positions.
+ */
+export function otherListingTickerKey(
+  result: InstrumentSearchResult,
+  symbol: string,
+  saved: TickerRecord | null | undefined,
+): string | null {
+  const selectedExchange = canonicalExchange(
+    result.exchange === "SMART" ? result.primaryExchange : result.exchange || result.primaryExchange,
+  );
+  const savedExchange = canonicalExchange(saved?.metadata.exchange);
+  if (!saved || !selectedExchange || !savedExchange || selectedExchange === savedExchange) return null;
+  return publicTickerKey(parsePublicTickerKey(symbol).symbol, selectedExchange);
+}
+
 export async function upsertTickerFromSearchResult(
   tickerRepository: AppTickerRepositoryPort,
   result: InstrumentSearchResult,
@@ -18,13 +37,9 @@ export async function upsertTickerFromSearchResult(
 ): Promise<{ ticker: TickerRecord; created: boolean }> {
   let symbol = options.tickerSymbol ?? getSearchResultSymbol(result);
   let ticker = await tickerRepository.loadTicker(symbol);
-  const selectedExchange = canonicalExchange(
-    result.exchange === "SMART" ? result.primaryExchange : result.exchange || result.primaryExchange,
-  );
-  const savedExchange = canonicalExchange(ticker?.metadata.exchange);
-  if (ticker && selectedExchange && savedExchange && selectedExchange !== savedExchange) {
-    // Opening a second listing must never re-denominate existing positions.
-    symbol = publicTickerKey(parsePublicTickerKey(symbol).symbol, selectedExchange);
+  const otherListingKey = otherListingTickerKey(result, symbol, ticker);
+  if (otherListingKey) {
+    symbol = otherListingKey;
     ticker = await tickerRepository.loadTicker(symbol);
   }
   const created = !ticker;

package/src/tickers/ticker-changes.ts

@@ -39,8 +39,13 @@ type TickerChangeSource = Pick<DataProvider, "getTickerChanges">;
 /** A lookup in flight: `settle` waits a little more for it, then gives up and stops the request. */
 export interface TickerChangeLookup {
   settle(graceMs?: number): Promise<TickerChanges | null>;
+  /** Its answer once it has one, null when it failed or there is nothing to look up; undefined while it runs. */
+  peek(): TickerChanges | null | undefined;
 }
 
+/** A change whose company moved to another symbol (`movedAwayChange`). */
+export type MovedTickerChange = TickerChange & { tradesAs: string };
+
 /** How long a command waits for a note once its own answer is ready. */
 const TICKER_CHANGE_GRACE_MS = 200;
 /** The longest a lookup runs, for a caller that keeps waiting. */
@@ -54,12 +59,13 @@ interface Entry {
   promise: Promise<TickerChanges | null>;
   controller: AbortController;
   done: boolean;
+  value: TickerChanges | null;
   failedAt: number | null;
 }
 
 /** One session's answers per source: a symbol is looked up once. */
 const sessions = new WeakMap<TickerChangeSource, Map<string, Entry>>();
-const NONE: TickerChangeLookup = { settle: async () => null };
+const NONE: TickerChangeLookup = { settle: async () => null, peek: () => null };
 
 /** A venue the change history is about: none named, a US exchange, or US over-the-counter. */
 export function isUsSymbolVenue(exchange?: string | null): boolean {
@@ -99,9 +105,9 @@ function entryFor(symbol: string, source: TickerChangeSource & Required<TickerCh
   if (cached && (cached.failedAt === null || Date.now() - cached.failedAt < RETRY_FAILED_AFTER_MS)) return cached;
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), LOOKUP_TIMEOUT_MS);
-  const entry: Entry = { promise: Promise.resolve(null), controller, done: false, failedAt: null };
+  const entry: Entry = { promise: Promise.resolve(null), controller, done: false, value: null, failedAt: null };
   entry.promise = source.getTickerChanges(symbol, { signal: controller.signal })
-    .then(readPayload)
+    .then((payload) => entry.value = readPayload(payload))
     .catch(() => {
       entry.failedAt = Date.now();
       return null;
@@ -140,6 +146,7 @@ export function startTickerChangeLookup(
       entry.controller.abort();
       return null;
     },
+    peek: () => entry.done ? entry.value : undefined,
   };
 }
 
@@ -153,9 +160,9 @@ function day(date: string): number {
   return Date.parse(`${date}T00:00:00Z`);
 }
 
-/** "to META on 2022-06-09, then MMATQ on 2024-08-21": each later hop of a chain. */
-function laterHops(hops: readonly TickerChangeHop[], lead: string): string {
-  return hops.slice(1).map((hop) => `, then ${lead}${hop.to} on ${hop.date}`).join("");
+/** ", then MMATQ on 2024-08-21": each later hop of a chain. */
+function laterHops(hops: readonly TickerChangeHop[]): string {
+  return hops.slice(1).map((hop) => `, then ${hop.to} on ${hop.date}`).join("");
 }
 
 /**
@@ -167,6 +174,16 @@ export function tickerChangeLine(change: TickerChange | null | undefined): strin
   return change?.kind === "moved" ? change.note : null;
 }
 
+/**
+ * The change when the company that held the symbol trades under another now
+ * and nothing new lists under it (HFC became DINO): the symbol has no data of
+ * its own. Null for a symbol a new security took (FB lists a fund), one its
+ * holder renamed into (META), and one with no change.
+ */
+export function movedAwayChange(change: TickerChange | null | undefined): MovedTickerChange | null {
+  return change?.kind === "moved" && !change.listed && change.tradesAs ? { ...change, tradesAs: change.tradesAs } : null;
+}
+
 /**
  * The note for a symbol's changes. `current` is what the command found
  * trading under the symbol: null when nothing does, left out when it did not
@@ -174,7 +191,7 @@ export function tickerChangeLine(change: TickerChange | null | undefined): strin
  * left, is that issuer's old line rather than a new listing.
  *
  * "FB now lists ProShares S&P 500 Dynamic Daily Buffer ETF; Meta Platforms trades as META (changed 2022-06-09)"
- * "FB changed to META on 2022-06-09"
+ * "HFC became DINO on 2022-03-15"
  * "METV was META until 2022-01-31" (data only: `tickerChangeLine` prints none)
  */
 export function describeTickerChange(
@@ -197,10 +214,10 @@ export function describeTickerChange(
     const listed = listedHere ? current?.name?.trim() || payload.listedName || "another security" : null;
     const when = moved.hops.length === 1
       ? `changed ${first.date}`
-      : `changed to ${first.to} on ${first.date}${laterHops(moved.hops, "")}`;
+      : `changed to ${first.to} on ${first.date}${laterHops(moved.hops)}`;
     const note = listed
       ? `${symbol} now lists ${listed}; ${issuer ?? `the former ${symbol}`} trades as ${moved.symbol} (${when})`
-      : `${symbol} changed to ${first.to} on ${first.date}${laterHops(moved.hops, "to ")}`;
+      : `${symbol} became ${first.to} on ${first.date}${laterHops(moved.hops)}`;
     return { symbol, kind: "moved", note, changes: moved.hops, tradesAs: moved.symbol, issuer, listed };
   }
   if (formerly) {

package/src/time-series/bar-spacing.ts

@@ -0,0 +1,19 @@
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * The typical spacing of a series of bar times: the median gap between
+ * consecutive distinct times, so the long gap a holiday leaves (Golden Week
+ * closes Shanghai from 30 Sep to 8 Oct) does not read as the bar size. Null
+ * with fewer than two distinct times.
+ */
+export function medianBarGap(times: readonly number[]): number | null {
+  const finite = times.filter(Number.isFinite).sort((left, right) => left - right);
+  const gaps = finite.slice(1).map((time, index) => time - finite[index]!).filter((gap) => gap > 0).sort((left, right) => left - right);
+  return gaps.length > 0 ? gaps[Math.floor((gaps.length - 1) / 2)]! : null;
+}
+
+/** A bar size of a day or more read from the typical spacing of its bars (medianBarGap). */
+export function barSizeFromGap(gapMs: number): "1d" | "1wk" | "1mo" {
+  const days = gapMs / DAY_MS;
+  return days >= 25 ? "1mo" : days >= 6 ? "1wk" : "1d";
+}