gloomberb 0.16.4 → 0.16.5

package/src/sources/provider-router/history.ts

@@ -56,7 +56,8 @@ interface HistoryRequestDescriptor {
   context?: MarketDataRequestContext;
   cachePolicyKey: PriceHistoryCachePolicyKey;
   missingProviderError?: string;
-  isCachedValueStale(value: PriceHistoryResult): boolean;
+  /** `fetchedAt` is when the cached copy was fetched. */
+  isCachedValueStale(value: PriceHistoryResult, fetchedAt: number): boolean;
   isFetchedValueStale(value: PriceHistoryResult): boolean;
   fetchBroker(candidate: BrokerCandidate): Promise<PricePoint[] | null>;
   fetchProvider(provider: DataProvider): Promise<PriceHistoryResult | null>;
@@ -243,15 +244,20 @@ function mergeRequestHistoryGaps(
 }
 
 function normalizeRequestResult(value: PriceHistoryResult, request: HistoryRequestDescriptor): PriceHistoryResult {
-  return { ...value, points: normalizeRequestHistory(value.points, request),
+  // Only this router says a copy is behind, when it answers: neither a source
+  // nor a stored copy can carry that verdict in.
+  const { savedCopyBehind: _behind, ...kept } = value;
+  return { ...kept, points: normalizeRequestHistory(value.points, request),
     // A public equity response cannot establish a broker contract's session.
     ...(request.context?.instrument ? { session: undefined } : {}),
   };
 }
 
-function resultIsStale(value: PriceHistoryResult, symbol: string, exchange: string, intervalMs?: number | null): boolean {
+/** A copy fetched at `fetchedAt`, now for a source's answer. */
+function resultIsStale(value: PriceHistoryResult, symbol: string, exchange: string, fetchedAt: number, intervalMs?: number | null): boolean {
   return isPriceHistoryStaleForCurrentWindow(value.points, Date.now(), {
     symbol, exchange, intervalMs: intervalMs ?? (value.resolution ? priceHistoryIntervalMs(value.resolution) : undefined), session: value.session,
+    fetchedAt,
   });
 }
 
@@ -351,8 +357,8 @@ export class ProviderRouterHistoryRoutes {
       context,
       cachePolicyKey: intraday ? "priceHistoryIntraday" : "priceHistoryDaily",
       missingProviderError: `No history provider available for ${ticker}`,
-      isCachedValueStale: (value) => intraday && resultIsStale(value, ticker, exchange),
-      isFetchedValueStale: (value) => intraday && resultIsStale(value, ticker, exchange),
+      isCachedValueStale: (value, fetchedAt) => intraday && resultIsStale(value, ticker, exchange, fetchedAt),
+      isFetchedValueStale: (value) => intraday && resultIsStale(value, ticker, exchange, Date.now()),
       fetchBroker: async (candidate) => candidate.broker.getPriceHistory
         ? candidate.broker.getPriceHistory(
           ticker,
@@ -408,8 +414,8 @@ export class ProviderRouterHistoryRoutes {
       context,
       cachePolicyKey: intraday ? "priceHistoryIntraday" : "priceHistoryDaily",
       missingProviderError: `No resolution-aware history provider available for ${ticker}`,
-      isCachedValueStale: (value) => intraday && resultIsStale(value, ticker, exchange, intervalMs),
-      isFetchedValueStale: (value) => intraday && resultIsStale(value, ticker, exchange, intervalMs),
+      isCachedValueStale: (value, fetchedAt) => intraday && resultIsStale(value, ticker, exchange, fetchedAt, intervalMs),
+      isFetchedValueStale: (value) => intraday && resultIsStale(value, ticker, exchange, Date.now(), intervalMs),
       fetchBroker: async (candidate) => candidate.broker.getPriceHistoryForResolution
         ? candidate.broker.getPriceHistoryForResolution(
           ticker,
@@ -523,10 +529,10 @@ export class ProviderRouterHistoryRoutes {
       interval: barSize,
       context,
       cachePolicyKey: intervalMs != null && intervalMs >= 24 * 60 * 60 * 1000 ? "priceHistoryDaily" : "priceHistoryIntraday",
-      isCachedValueStale: (value) => currentWindowAtLookup
-        && resultIsStale(value, ticker, exchange, intervalMs),
+      isCachedValueStale: (value, fetchedAt) => currentWindowAtLookup
+        && resultIsStale(value, ticker, exchange, fetchedAt, intervalMs),
       isFetchedValueStale: (value) => isCurrentHistoryWindow(endDate)
-        && resultIsStale(value, ticker, exchange, intervalMs),
+        && resultIsStale(value, ticker, exchange, Date.now(), intervalMs),
       fetchBroker: async (candidate) => candidate.broker.getDetailedPriceHistory
         ? candidate.broker.getDetailedPriceHistory(
           ticker,
@@ -604,7 +610,7 @@ export class ProviderRouterHistoryRoutes {
     const withReportedGaps = (value: PriceHistoryResult) => historyCoverage(request).merge(value, reportedGaps);
     const clip = (value: PriceHistoryResult) => request.requestedRange
       ? clipHistoryToRange(value, request.requestedRange, request.target.exchange) : value;
-    const cachedHistoryStale = request.isCachedValueStale(cachedValue);
+    const cachedHistoryStale = request.isCachedValueStale(cachedValue, cached?.fetchedAt ?? Number.NEGATIVE_INFINITY);
     const forceRefresh = request.context?.cacheMode === "refresh";
     // A recent re-check, even a failed, empty or rejected one, defers the next
     // one; it does not make the copy current. A broader copy only tells what
@@ -613,8 +619,10 @@ export class ProviderRouterHistoryRoutes {
       request.exactCacheVariantKeys.includes(cached.variantKey) ? cached.fetchedAt : Number.NEGATIVE_INFINITY)) : "current";
     const cachedBeforeClose = servedState === "unsettled" || servedState === "recheck";
     if (cachedBeforeClose) this.markCalendarChecked(request, now);
-    const usableCached = hasUsablePriceHistory(cachedValue.points) && cached && !cached.expired && !cachedHistoryStale
-      && !cachedBeforeClose;
+    // A copy that a re-check since the close could not replace answers until
+    // the next one is due, though it does not hold the whole session.
+    const usableCached = hasUsablePriceHistory(cachedValue.points) && cached && !cached.expired
+      && (!cachedHistoryStale || servedState === "pending") && !cachedBeforeClose;
     // A copy behind or before the latest session is re-checked on the paced
     // schedule above, not on its short TTL: the source is likely to answer
     // the same. A short-lived process (the CLI) closes its store before a
@@ -627,9 +635,11 @@ export class ProviderRouterHistoryRoutes {
       if (refreshDue) {
         scheduleRouterRevalidation(this.historyRefreshInFlight, request.identity.revalidationKey, () => this.refreshHistory(request));
       }
+      // Only a copy a re-check could not replace reaches here short of the latest session.
+      const answered = cachedHistoryStale ? { ...cachedValue, savedCopyBehind: true as const } : cachedValue;
       return exactHit || !request.requestedRange
-        ? withReportedGaps(cachedValue)
-        : clip(withReportedGaps(cachedValue));
+        ? withReportedGaps(answered)
+        : clip(withReportedGaps(answered));
     }
 
     const supersededCacheSources = new Set<string>();
@@ -651,13 +661,21 @@ export class ProviderRouterHistoryRoutes {
     if (providerResult && hasUsablePriceHistory(providerResult.value.points)) return withReportedGaps(providerResult.value);
     if (providerResult) reportedGaps.push(providerResult.value);
     // A failed refetch falls back in the same order the cache hit used, so a
-    // failing request answers what the next request will.
-    const fallbackValue = ranked
+    // failing request answers what the next request will: a current copy
+    // first, else a saved copy short of the latest session, which beats an
+    // empty chart. Intraday copies expire two days after they are saved. A
+    // coin never closes, so its old copy is not shown: the miss says why.
+    const coin = isRoundTheClockCoin(target.symbol, target.exchange || request.target.exchange);
+    const fallbackRecords = ranked
       .map((entry) => entry.record)
-      .filter((record) => !supersededCacheSources.has(record.sourceKey))
-      .map((record) => record.value)
-      .find((value) => !request.isCachedValueStale(value));
-    if (fallbackValue) {
+      .filter((record) => !supersededCacheSources.has(record.sourceKey));
+    const fallbackRecord = fallbackRecords.find((record) => !request.isCachedValueStale(record.value, record.fetchedAt))
+      ?? (coin ? undefined : fallbackRecords[0]);
+    if (fallbackRecord) {
+      // A copy short of the latest session says so, so the chart can tell it
+      // from a current one: a thin listing's complete copy is not behind.
+      const fallbackValue = request.isCachedValueStale(fallbackRecord.value, fallbackRecord.fetchedAt)
+        ? { ...fallbackRecord.value, savedCopyBehind: true as const } : fallbackRecord.value;
       return request.requestedRange
         ? clip(withReportedGaps(fallbackValue))
         : withReportedGaps(fallbackValue);
@@ -673,11 +691,11 @@ export class ProviderRouterHistoryRoutes {
     }
     if (!providerResult && request.missingProviderError && !reportedGaps.some((value) => value.points.length > 0)) {
       // A source answered a coin's history but it stops short of the present: say so, not that nothing answered.
-      const behind = isRoundTheClockCoin(target.symbol, target.exchange || request.target.exchange)
-        && [...attempts.outcomes.values()].some((outcome) => outcome.outcome === "stale");
+      const behind = coin && [...attempts.outcomes.values()].some((outcome) => outcome.outcome === "stale");
       if (behind) throw new Error(`Latest history for ${target.symbol} is behind`);
-      // The service has no listing for the symbol: say it is not a ticker, not that no source answered.
-      throw noProviderError(request.missingProviderError, { notFound: attempts.misses.notFound }, request.target.symbol);
+      // A reason the service gave ("ADX listings have daily bars only.") says why; one that has no
+      // listing for the symbol says it is not a ticker; otherwise no source answered.
+      throw noProviderError(request.missingProviderError, attempts.misses, request.target.symbol);
     }
     return withReportedGaps(providerResult?.value ?? { points: [], resolution: historyResolutionForInterval(request.interval) });
   }

package/src/sources/provider-router/search.ts

@@ -28,6 +28,7 @@ function buildSearchCacheKey(query: string, context?: SearchRequestContext): str
     context?.preferBroker ?? true,
     context?.brokerInstanceId ?? "",
     context?.brokerId ?? "",
+    context?.limit ?? null,
   ]);
 }
 

package/src/sync/core-contributors.ts

@@ -107,6 +107,7 @@ function sanitizePortfolio(portfolio: Portfolio): Portfolio {
     // them would erase them on this device.
     ...(portfolio.cash ? { cash: { ...portfolio.cash } } : {}),
     ...(portfolio.targetWeights ? { targetWeights: { ...portfolio.targetWeights } } : {}),
+    ...(portfolio.importedFrom ? { importedFrom: { ...portfolio.importedFrom } } : {}),
   };
 }
 

package/src/tickers/company-name.ts

@@ -0,0 +1,75 @@
+/**
+ * Company names as venues spell them, compared and shortened for sentences.
+ * One company's listings carry its name with different legal forms and share
+ * wording ("Microsoft Corporation Common Stock", "Coca-Cola Company CDR"), so
+ * they are compared by the words that say whose they are.
+ */
+
+// Words that differ between one company's listings: legal forms, and how a depositary receipt is named.
+const NAME_NOISE = new Set([
+  "co", "company", "corp", "corporation", "inc", "incorporated", "ltd", "limited", "llc", "lp", "plc", "sa", "ag", "nv", "se",
+  "spa", "ab", "as", "asa", "oyj", "bv", "gmbh", "kgaa", "bhd", "berhad", "pcl", "the", "adr", "ads", "cedear", "cedears",
+  "sponsored", "unsponsored", "cdr", "cdi",
+]);
+// Words a venue adds to the share it lists ("Microsoft Corporation Common Stock"), never part of whose it is.
+const SHARE_NOISE = new Set(["common", "ordinary", "stock", "shares"]);
+
+/** A company's name for comparing its listings: "Kotobuki Spirits Co., Ltd." is "kotobuki spirits". */
+function companyKey(name: string): string {
+  return name.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase()
+    .replace(/\([^)]*\)/g, " ")
+    .replace(/\b(?:(?:american|global) )?depositary (?:shares?|receipts?)\b/g, " ")
+    .replace(/\./g, "")
+    .split(/[^\p{L}\p{N}]+/u)
+    .filter((word) => word && !NAME_NOISE.has(word))
+    .join(" ");
+}
+
+function companyWords(name: string | null | undefined): Set<string> {
+  return new Set(companyKey(name ?? "").split(" ").filter((word) => word && !SHARE_NOISE.has(word)));
+}
+
+/**
+ * Whether two names are one company's, however each venue spells it: one
+ * name's words are all in the other's, so "SPDR S&P 500 ETF Trust" is State
+ * Street's, "Coca-Cola Company CDR" Coca-Cola's, and "CAR Group" not Avis
+ * Budget Group. An empty name matches none.
+ */
+export function sameCompany(left: string | null | undefined, right: string | null | undefined): boolean {
+  const a = companyWords(left);
+  const b = companyWords(right);
+  if (a.size === 0 || b.size === 0) return false;
+  const [fewer, more] = a.size <= b.size ? [a, b] : [b, a];
+  return [...fewer].every((word) => more.has(word));
+}
+
+/** Items grouped by the company their names are, in the order each company first appears. Unnamed items are left out. */
+export function groupByCompany<T>(items: readonly T[], nameOf: (item: T) => string | null | undefined): T[][] {
+  const groups: T[][] = [];
+  for (const item of items) {
+    if (companyWords(nameOf(item)).size === 0) continue;
+    const group = groups.find((members) => members.some((member) => sameCompany(nameOf(member), nameOf(item))));
+    if (group) group.push(item);
+    else groups.push([item]);
+  }
+  return groups;
+}
+
+/** A company's name without its legal form, for sentences: "Avis Budget Group, Inc." is "Avis Budget Group". */
+export function shortCompanyName(name: string): string {
+  const words = name.trim().split(/\s+/).filter(Boolean);
+  const legal = (word: string) => {
+    const plain = word.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^\p{L}\p{N}]/gu, "");
+    // "Public Limited Company" is a legal form too, though "Public" alone can be a name.
+    return NAME_NOISE.has(plain) || SHARE_NOISE.has(plain) || (plain === "public" && words.length > 2);
+  };
+  while (words.length > 1 && legal(words[words.length - 1]!)) words.pop();
+  if (words.length > 1 && words[0]!.toLowerCase() === "the") words.shift();
+  return words.join(" ").replace(/[,;]+$/, "");
+}
+
+/** "CAR Group (ASX)": a listing named by its company without the legal form, for a sentence about the company. */
+export function shortListingTitle(listing: { symbol: string; exchange: string; name: string | null }): string {
+  const name = listing.name?.trim() ? shortCompanyName(listing.name) : listing.symbol;
+  return listing.exchange ? `${name} (${listing.exchange})` : name;
+}

package/src/tickers/instrument-kind.ts

@@ -130,3 +130,28 @@ export function resolveTickerInstrumentKind(
     ?? kindFromListing(ticker)
     ?? "equity";
 }
+
+/**
+ * A coin-typed listing named "<asset> (Derivatives)", such as NATGAS-USD
+ * "Natural Gas (Derivatives) USD": the price perpetual futures on that asset
+ * trade at on crypto venues, around the clock. It is neither the asset's
+ * exchange-listed future nor its spot price, though its type reads as a coin.
+ */
+export function isCryptoVenuePerpetual(type: string | null | undefined, name: string | null | undefined): boolean {
+  return classifyInstrumentType(type) === "crypto" && /\(derivatives\)/i.test(name ?? "");
+}
+
+/**
+ * A listing's type, in plain words where the provider's type misleads (a
+ * perpetual typed as a coin). `detail` says what it is not, for a report line.
+ */
+export function instrumentTypeLabel(
+  type: string | null | undefined,
+  name: string | null | undefined,
+  options: { detail?: boolean } = {},
+): string | undefined {
+  if (isCryptoVenuePerpetual(type, name)) {
+    return options.detail ? "Perpetual futures price (24/7 on crypto venues; not the listed future, not spot)" : "Perpetual futures price";
+  }
+  return type?.trim() || undefined;
+}

package/src/tickers/open-target.ts

@@ -11,7 +11,7 @@ import {
 import { tickerSelectionFromSearchResult } from "./selection";
 import { normalizeTickerSymbol } from "./search/ranking";
 import type { TickerOpenTarget } from "./search/types";
-import { parsePublicTickerKey } from "../utils/exchanges";
+import { isSharedExchangeCode, parsePublicTickerKey, typedExchangeCode } from "../utils/exchanges";
 import { getListingSymbol, tickerHasListingSuffix } from "../sources/listing-symbols";
 
 export type { TickerOpenTarget } from "./search/types";
@@ -34,7 +34,8 @@ export async function resolveTickerOpenTarget({
   const symbol = normalizeTickerInput(null, query);
   if (!symbol) return null;
   const requested = parsePublicTickerKey(symbol);
-  const preserveListingKey = !!requested.exchange || tickerHasListingSuffix(symbol);
+  // A code that names several venues (7203:TSE) opens the listing search settled on, under its own key.
+  const preserveListingKey = (!!requested.exchange && !isSharedExchangeCode(typedExchangeCode(symbol))) || tickerHasListingSuffix(symbol);
 
   let resolved: Awaited<ReturnType<typeof resolveTickerSearch>> | null = null;
   try {

package/src/tickers/search/index.ts

@@ -1,11 +1,12 @@
 import type { SearchRequestContext, DataProvider } from "../../types/data-provider";
 import type { InstrumentSearchResult } from "../../types/instrument";
 import type { TickerRecord } from "../../types/ticker";
-import { canonicalExchange, parsePublicTickerKey, publicTickerKey } from "../../utils/exchanges";
+import { canonicalExchange, isSharedExchangeCode, isUsListingExchange, parsePublicTickerKey, publicTickerKey, typedExchangeCode } from "../../utils/exchanges";
 import { getListingSymbol, tickerHasListingSuffix } from "../../sources/listing-symbols";
 import { parseOptionSymbol } from "../../utils/options";
 import { resolveCurrencyUnit } from "../../utils/currency-units";
 import { assetClassMarketSymbol, parseAssetClassQuery } from "./asset-classes";
+import { bareFuturesCode, futuresContractByCode } from "../../market-data/futures-board";
 import { searchContractKey, searchInstrumentKey } from "./identity";
 import { tickerInstrumentLabel } from "../instrument-label";
 import {
@@ -40,9 +41,21 @@ export {
 } from "./ranking";
 export { upsertTickerFromSearchResult } from "./upsert";
 
+const MAX_NAMED_LISTINGS = 6;
+
+/**
+ * Search rows a symbol's listings are read from, by the command bar's `SAN:`
+ * venue list and the CLI's venue list alike. A keystroke's ten stop short of a
+ * symbol several companies use: CAR's ASX line is its eleventh.
+ */
+export const LISTING_SEARCH_LIMIT = 30;
+
 export class AmbiguousTickerError extends Error {
   constructor(readonly query: string, readonly listings: readonly string[], readonly listingNames: Readonly<Record<string, string>> = {}) {
-    super(`Multiple listings match ${query}. Choose an exchange in search or use ${listings.slice(0, 3).join(", ")}.`);
+    // Every listing is a choice: a list cut short could leave out the one meant.
+    const more = listings.length - MAX_NAMED_LISTINGS;
+    const named = `${listings.slice(0, MAX_NAMED_LISTINGS).join(", ")}${more > 0 ? ` or one of ${more} more in search` : ""}`;
+    super(`Multiple listings match ${query}. Choose an exchange in search or use ${named}.`);
     this.name = "AmbiguousTickerError";
   }
 }
@@ -291,7 +304,10 @@ export function resolveTickerSearch(options: ResolveTickerSearchOptions): Promis
   if (!requested) return Promise.resolve(null);
   // `NET:` lists NET's venues instead of settling on one.
   const pickListing = isListingPickerQuery(requested);
-  const symbol = symbolSearchQuery(requested);
+  const typed = symbolSearchQuery(requested);
+  // A futures board code no security uses is its future (TTF is TTF=F), unless a saved ticker holds it.
+  const future = pickListing || options.tickers.has(typed) ? null : bareFuturesCode(typed);
+  const symbol = future?.symbol ?? typed;
   const literal = resolveTickerSymbol(symbol, options, pickListing ? requested : null);
   const alternatives = pickListing ? [] : dottedVenueQueries(symbol);
   // Most input has no venue code to retry: hand back the literal lookup
@@ -346,6 +362,9 @@ async function resolveTickerSymbol(
     publicTickerKey(item.symbol, listingExchange(item.result!)), item.result!.name,
   ])));
   if (pickerQuery && listings.size > 1) throw ambiguity(pickerQuery);
+  // A code that names several venues (TSE) the symbol trades on more than one of is a choice.
+  if (!saved && isSharedExchangeCode(typedExchangeCode(symbol))
+    && new Set(matches.map((item) => canonicalExchange(listingExchange(item.result!)))).size > 1) throw ambiguity(symbol);
   if (saved) return saved;
   if (listings.size > 1 && !parsePublicTickerKey(symbol).exchange && !tickerHasListingSuffix(symbol)) {
     // Search order is relevance, not a canonical listing identifier. Align bare
@@ -360,14 +379,14 @@ async function resolveTickerSymbol(
       const currency = resolveCurrencyUnit(quote.currency).currency;
       if (exchange && currency && Number.isFinite(quote.price) && quote.price !== 0
         && Number.isFinite(quote.lastUpdated) && quote.lastUpdated > 0) {
-        verified = matches.filter((item) => {
+        const sameSecurity = matches.filter((item) => {
           const result = item.result!;
           const candidateCurrency = resolveCurrencyUnit(result.currency).currency;
-          return canonicalExchange(listingExchange(result)) === exchange
-            && (!candidateCurrency || candidateCurrency === currency)
+          return (!candidateCurrency || candidateCurrency === currency)
             && findExactTickerSearchMatch([{ label: quote.symbol, right: exchange, instrumentType: quote.instrumentType }], item.symbol)
             && (!isCryptoInstrumentType(result.type) || quote.price > 0);
-        }).map((item) => ({ ...item, result: { ...item.result!, currency } }));
+        });
+        verified = quotedListings(sameSecurity, exchange).map((item) => ({ ...item, result: { ...item.result!, currency } }));
       }
     } catch {
       // An unavailable quote cannot establish the default listing.
@@ -376,6 +395,8 @@ async function resolveTickerSymbol(
       throw ambiguity(symbol);
     }
     exactMatch = verified[0]!;
+    const chosen = publicTickerKey(exactMatch.symbol, listingExchange(exactMatch.result!));
+    return { kind: "provider", symbol: exactMatch.symbol, result: exactMatch.result!, otherListings: [...listings].filter((key) => key !== chosen) };
   }
 
   return {
@@ -385,6 +406,19 @@ async function resolveTickerSymbol(
   };
 }
 
+/**
+ * The listings a bare symbol's own quote is on: those on the venue it names.
+ * The US exchanges share one symbol namespace, so a quote on any of them is
+ * the symbol's one US listing, whichever venue the feed labels it with (ET's
+ * NYSE line comes back as NYSE American).
+ */
+function quotedListings(items: TickerSearchCandidate[], exchange: string): TickerSearchCandidate[] {
+  const venue = (item: TickerSearchCandidate) => canonicalExchange(listingExchange(item.result!));
+  const named = items.filter((item) => venue(item) === exchange);
+  if (named.length > 0 || !isUsListingExchange(exchange)) return named;
+  return items.filter((item) => isUsListingExchange(venue(item)));
+}
+
 function listingExchange(result: InstrumentSearchResult): string {
   return result.exchange === "SMART" ? result.primaryExchange || result.exchange
     : result.exchange || result.primaryExchange || "";
@@ -455,6 +489,10 @@ async function searchProviderResults(
   // number of spellings tried.
   const searchQueries = buildProviderSearchQueries(query);
   if (marketSymbol && !searchQueries.includes(marketSymbol)) searchQueries.push(marketSymbol);
+  // A futures board code also finds its future, which the catalogue files under
+  // the continuous symbol only: NG finds NovaGold and NG=F.
+  const boardFuture = assetClass ? null : futuresContractByCode(query)?.symbol;
+  if (boardFuture && !searchQueries.includes(boardFuture)) searchQueries.push(boardFuture);
   await Promise.all(searchQueries.map(async (searchQuery) => {
     try {
       const results = await dataProvider.search(searchQuery, {

package/src/tickers/search/ranking.ts

@@ -3,8 +3,10 @@ import type {
   TickerSearchRankableItem,
 } from "./types";
 import { getListingSymbol, tickerHasListingSuffix } from "../../sources/listing-symbols";
-import { canonicalExchange, parsePublicTickerKey } from "../../utils/exchanges";
+import { currencyPairCode } from "../../utils/currency-pair";
+import { canonicalExchange, exchangeCodeVenues, parsePublicTickerKey, typedExchangeCode } from "../../utils/exchanges";
 import { assetClassKeeps, assetClassMarketSymbol, instrumentClassCode, parseAssetClassQuery } from "./asset-classes";
+import { futuresContractByCode } from "../../market-data/futures-board";
 
 const FUND_TYPES = new Set(["ETF", "ETN", "ETP", "FUND", "MUTUALFUND", "CEF", "CLOSEDEND"]);
 const DERIVATIVE_TYPES = new Set(["OPT", "OPTION", "OPTIONS", "FUT", "FUTURE", "FUTURES", "WARRANT", "WARRANTS", "RIGHT", "RIGHTS"]);
@@ -28,15 +30,15 @@ const COMPANY_NAME_SUFFIXES = new Set([
   "SE",
 ]);
 
-const EXCHANGE_HINT_ALIASES: Record<string, string[]> = {
+/** Words in a search that say where to look ("toyota tokyo"), each with the venue labels it matches. */
+const VENUE_HINT_ALIASES: Record<string, string[]> = {
   NASDAQ: ["NASDAQ", "NMS"],
   NYSE: ["NYSE", "NYSE ARCA", "ARCA"],
   AMEX: ["AMEX"],
   TSX: ["TSX", "TORONTO"],
   TORONTO: ["TORONTO", "TSX"],
   XETRA: ["XETRA"],
-  TSE: ["TOKYO STOCK EXCHANGE", "TOKYO", "JPX", "TSE"],
-  TOKYO: ["TOKYO STOCK EXCHANGE", "TOKYO", "JPX", "TSE"],
+  TOKYO: ["TOKYO STOCK EXCHANGE", "TOKYO", "JPX"],
   JPX: ["JPX", "TOKYO STOCK EXCHANGE", "TOKYO"],
   LSE: ["LSE", "LONDON"],
   HKEX: ["HKEX", "HONG KONG"],
@@ -46,6 +48,13 @@ const EXCHANGE_HINT_ALIASES: Record<string, string[]> = {
   AIRES: ["BUENOS AIRES", "BUE"],
 };
 
+/** A code the venue list reads as several venues (TSE: Toronto or Tokyo) ranks a row on any of them. */
+function sharedCodeHint(code: string): string[] {
+  return [code, ...exchangeCodeVenues(code).flatMap((venue) => VENUE_HINT_ALIASES[venue] ?? [venue])];
+}
+
+const EXCHANGE_HINT_ALIASES: Record<string, string[]> = { ...VENUE_HINT_ALIASES, TSE: sharedCodeHint("TSE") };
+
 const ASSET_HINT_MAP: Record<string, TickerSearchInstrumentClass> = {
   STOCK: "equity",
   STK: "equity",
@@ -121,15 +130,8 @@ export function isExplicitMarketSymbol(symbol: string): boolean {
   return /[=^]/.test(symbol) || /^[A-Z]{3}\/[A-Z]{3}$/i.test(symbol.trim());
 }
 
-function forexPair(symbol: string): string | null {
-  if (/^[A-Z]{3}\/[A-Z]{3}$/.test(symbol)) return symbol.replace("/", "");
-  if (/^[A-Z]{6}=X$/.test(symbol)) return symbol.slice(0, -2);
-  if (/^[A-Z]{3}=X$/.test(symbol)) return `USD${symbol.slice(0, -2)}`;
-  return null;
-}
-
 export function getForexQuoteCurrency(symbol: string): string | undefined {
-  return forexPair(parsePublicTickerKey(normalizeTickerSymbol(symbol)).symbol)?.slice(3);
+  return currencyPairCode(normalizeTickerSymbol(symbol))?.slice(3);
 }
 
 /** Venue and market syntax must survive exact matching. Only explicit FX forms are equivalent. */
@@ -145,12 +147,16 @@ function matchesQualifiedTicker(
   const exchanges = [candidate.exchange, item.exchangeLabel, item.primaryExchangeLabel, item.right]
     .filter((value): value is string => !!value);
   if (requested.exchange) {
-    return candidate.symbol === requested.symbol
-      && exchanges.some((exchange) => canonicalExchange(exchange) === requested.exchange);
+    // EURUSD:CCY and EURUSD:FX name the pair listed as EURUSD=X on CCY.
+    const pair = currencyPairCode(requested.symbol, requested.exchange);
+    // A code that names several venues (TSE: Toronto or Tokyo) matches a row on any of them.
+    const venues = exchangeCodeVenues(typedExchangeCode(normalized));
+    return (candidate.symbol === requested.symbol || (pair != null && currencyPairCode(candidate.symbol) === pair))
+      && exchanges.some((exchange) => venues.includes(canonicalExchange(exchange)));
   }
   if (isExplicitMarketSymbol(requested.symbol)) {
-    const pair = forexPair(requested.symbol);
-    return candidate.symbol === requested.symbol || (pair != null && forexPair(candidate.symbol) === pair);
+    const pair = currencyPairCode(requested.symbol);
+    return candidate.symbol === requested.symbol || (pair != null && currencyPairCode(candidate.symbol) === pair);
   }
   return exchanges.some((exchange) => getListingSymbol(candidate.symbol, exchange).toUpperCase() === normalized);
 }
@@ -408,6 +414,16 @@ export function rankTickerSearchItems<T extends Pick<TickerSearchRankableItem, "
     ? deduped.findIndex((item) => parsePublicTickerKey(item.symbol || item.label).symbol === marketSymbol)
     : -1;
   if (marketIndex > 0) deduped.unshift(...deduped.splice(marketIndex, 1));
+  // A futures board code's future ranks with its code, not with the derivatives
+  // the word ranking puts last: first where no security uses the code (TTF),
+  // right after the security that keeps it otherwise (NovaGold, then NG=F).
+  const boardFuture = assetClass ? null : futuresContractByCode(query);
+  const futureIndex = boardFuture
+    ? deduped.findIndex((item) => normalizeTickerSymbol(item.symbol || item.label) === boardFuture.symbol)
+    : -1;
+  if (boardFuture && futureIndex >= 0) {
+    deduped.splice(boardFuture.bareCode ? 0 : Math.min(1, futureIndex), 0, ...deduped.splice(futureIndex, 1));
+  }
   return deduped;
 }
 
@@ -432,7 +448,7 @@ export function buildSymbolAliases(symbol: string): string[] {
   const normalizedSymbol = normalizeTickerSymbol(symbol);
   if (!normalizedSymbol) return [];
   if (isExplicitMarketSymbol(normalizedSymbol)) {
-    const pair = forexPair(normalizedSymbol);
+    const pair = currencyPairCode(normalizedSymbol);
     return pair
       ? [...new Set([normalizedSymbol, `${pair}=X`, `${pair.slice(0, 3)}/${pair.slice(3)}`])]
       : [normalizedSymbol];

package/src/tickers/search/types.ts

@@ -38,7 +38,13 @@ export interface TickerSearchCandidate extends TickerSearchRankableItem {
 
 export type ResolvedTickerSearch =
   | { kind: "local"; symbol: string; ticker: TickerRecord }
-  | { kind: "provider"; symbol: string; result: InstrumentSearchResult };
+  | {
+    kind: "provider";
+    symbol: string;
+    result: InstrumentSearchResult;
+    /** A bare symbol's other listings (SYM:EXCH) when its quote chose one of several. */
+    otherListings?: string[];
+  };
 
 export interface TickerOpenTarget {
   symbol: string;

package/src/tickers/us-listing.ts

@@ -0,0 +1,34 @@
+import type { DataProvider } from "../types/data-provider";
+import { canonicalExchange, isUsListingExchange, parsePublicTickerKey } from "../utils/exchanges";
+import { sameCompany } from "./company-name";
+import { LISTING_SEARCH_LIMIT } from "./search";
+import { classifyInstrumentKind } from "./search/ranking";
+
+export interface UsListing {
+  symbol: string;
+  /** Canonical code of its US exchange. */
+  exchange: string;
+  name: string;
+}
+
+/**
+ * A company's own listing on a US exchange, found by its name: Sanofi's SNY,
+ * Toyota's TM. Funds and contracts that carry its name are not its listing.
+ * Null when search knows no US line of the company.
+ */
+export async function findUsListingOfCompany(
+  dataProvider: Pick<DataProvider, "search">,
+  company: string | null | undefined,
+): Promise<UsListing | null> {
+  const name = company?.trim();
+  if (!name) return null;
+  const results = await dataProvider.search(name, { limit: LISTING_SEARCH_LIMIT }).catch(() => []);
+  for (const result of results) {
+    const exchange = canonicalExchange(result.exchange === "SMART" ? result.primaryExchange : result.exchange || result.primaryExchange);
+    const kind = classifyInstrumentKind(result.brokerContract?.secType || result.type);
+    if (!isUsListingExchange(exchange) || kind === "fund" || kind === "derivative") continue;
+    if (!sameCompany(result.name, name) || parsePublicTickerKey(result.symbol).exchange) continue;
+    return { symbol: result.symbol.toUpperCase(), exchange, name: result.name };
+  }
+  return null;
+}

package/src/time-series/hooks.ts

@@ -3,6 +3,7 @@ import { apiClient } from "../api-client";
 import { loadCachedFredSeries } from "../sources/gloomberb-cloud/fred-series";
 import { instrumentFromTicker } from "../market-data/request-types";
 import { useAssetData, useCapabilityInvoker } from "../plugins/runtime";
+import { getSharedRegistry } from "../plugins/registry";
 import { createChartSeriesResolver } from "../capabilities";
 import { useAppSelector } from "../state/app/context";
 import type { FredSeriesRequest } from "../sources/gloomberb-cloud/fred-series";
@@ -17,6 +18,13 @@ import {
 /** A scoped, immutable model for exports that must render exactly the loaded data. */
 export const ChartSnapshotContext = createContext<ChartResolutionResult | null>(null);
 
+/** A registered series' own reload cadence, when it has one. */
+function registeredSeriesRefreshMs(source: { capabilityId: string; seriesId: string }): number | undefined {
+  const found = getSharedRegistry()?.series.findLoaded(source.capabilityId, source.seriesId);
+  const definition = found?.series.definition;
+  return definition && "refreshMs" in definition ? definition.refreshMs : undefined;
+}
+
 async function loadFred(request: FredSeriesRequest) {
   return loadCachedFredSeries(
     request,
@@ -71,6 +79,7 @@ export function useResolvedChartSpec(
     dataProvider,
     loadFredSeries: loadFred,
     resolveCapabilitySeries: createChartSeriesResolver(capabilityInvoker),
+    capabilityRefreshMs: registeredSeriesRefreshMs,
   }), [capabilityInvoker, dataProvider]);
   return useChartResolution(hydratedSpec, sources, { ...options, snapshot });
 }