gloomberb 0.13.3 → 0.14.1

package/src/tickers/search/index.ts

@@ -1,12 +1,19 @@
 import type { SearchRequestContext, DataProvider } from "../../types/data-provider";
 import type { InstrumentSearchResult } from "../../types/instrument";
 import type { TickerRecord } from "../../types/ticker";
-import { canonicalExchange } from "../../utils/exchanges";
+import { canonicalExchange, parsePublicTickerKey, publicTickerKey } from "../../utils/exchanges";
+import { tickerHasYahooSuffix } from "../../sources/yahoo-finance/symbols";
 import { parseOptionSymbol } from "../../utils/options";
+import { resolveCurrencyUnit } from "../../utils/currency-units";
+import { searchContractKey, searchInstrumentKey } from "./identity";
+import { tickerInstrumentLabel } from "../instrument-label";
 import {
   buildSymbolAliases,
   classifyInstrumentKind,
   findExactTickerSearchMatch,
+  getForexQuoteCurrency,
+  isExplicitMarketSymbol,
+  isCryptoInstrumentType,
   normalizeSearchText,
   normalizeTickerSymbol,
   rankTickerSearchItems,
@@ -31,6 +38,21 @@ export {
 } from "./ranking";
 export { upsertTickerFromSearchResult } from "./upsert";
 
+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(", ")}.`);
+    this.name = "AmbiguousTickerError";
+  }
+}
+
+export class AmbiguousContractError extends AmbiguousTickerError {
+  constructor(query: string, contracts: readonly string[]) {
+    super(query, contracts);
+    this.name = "AmbiguousContractError";
+    this.message = `Multiple contracts match ${query}. Choose a contract in search.`;
+  }
+}
+
 const OPTION_TYPES = new Set(["OPT", "OPTION", "OPTIONS"]);
 
 const SHARE_CLASS_SUFFIXES = new Set(["A", "B", "C", "D", "K"]);
@@ -52,7 +74,6 @@ export function createLocalTickerSearchCandidates(
   options: TickerSearchCandidateOptions = {},
 ): TickerSearchCandidate[] {
   return Array.from(tickers).flatMap((ticker) => {
-    if (options.includeOptionContracts === false && isOptionTickerRecord(ticker)) return [];
     const symbol = normalizeTickerSymbol(ticker.metadata.ticker);
     const hint = providerHints.get(symbol);
     const exchangeLabel = ticker.metadata.exchange || hint?.exchange || hint?.primaryExchange;
@@ -61,23 +82,41 @@ export function createLocalTickerSearchCandidates(
     const primaryExchangeLabel = !savedExchange || !hintPrimaryExchange || savedExchange === hintPrimaryExchange
       ? hint?.primaryExchange
       : undefined;
-    return [{
-      id: `goto:${ticker.metadata.ticker}`,
-      label: ticker.metadata.ticker,
-      symbol,
-      detail: resolveLocalSearchName(ticker, hint),
-      right: exchangeLabel,
-      exchangeLabel,
-      primaryExchangeLabel,
-      providerRank: options.providerRanks?.get(symbol),
-      category: "Saved",
-      kind: "ticker",
-      saved: true,
-      instrumentClass: classifyInstrumentKind(hint?.brokerContract?.secType || hint?.type || ticker.metadata.assetCategory),
-      searchAliases: buildSymbolAliases(symbol),
-      ticker,
-      result: hint,
-    }];
+    const contractResults = (ticker.metadata.broker_contracts ?? [])
+      .filter((brokerContract) => searchContractKey({ brokerContract, type: ticker.metadata.assetCategory || "" }))
+      .map((brokerContract): InstrumentSearchResult => ({
+        providerId: brokerContract.brokerId, brokerInstanceId: brokerContract.brokerInstanceId,
+        symbol: ticker.metadata.ticker, name: tickerInstrumentLabel(ticker.metadata.ticker, brokerContract),
+        exchange: brokerContract.exchange || "", primaryExchange: brokerContract.primaryExchange, currency: brokerContract.currency,
+        type: brokerContract.secType || ticker.metadata.assetCategory || "", brokerContract,
+      }));
+    if (!contractResults.length && options.includeOptionContracts === false && isOptionTickerRecord(ticker)) return [];
+    return (contractResults.length ? contractResults : [hint])
+      .filter((result) => options.includeOptionContracts !== false || !result || !isOptionSearchResult(result))
+      .map((result) => {
+        const contractKey = result ? searchContractKey(result) : null;
+        const instrumentType = contractKey ? result!.type : hint?.brokerContract?.secType || hint?.type || ticker.metadata.assetCategory;
+        const venue = contractKey ? result!.exchange : exchangeLabel;
+        return {
+          id: `goto:${ticker.metadata.ticker}`,
+          label: ticker.metadata.ticker,
+          symbol,
+          detail: contractKey ? result!.name : resolveLocalSearchName(ticker, hint),
+          right: venue,
+          exchangeLabel: venue,
+          primaryExchangeLabel: contractKey ? result!.primaryExchange : primaryExchangeLabel,
+          providerRank: options.providerRanks?.get(symbol),
+          category: "Saved",
+          kind: "ticker",
+          saved: true,
+          instrumentClass: classifyInstrumentKind(instrumentType),
+          instrumentType,
+          searchAliases: buildSymbolAliases(symbol),
+          ticker,
+          result,
+          ...(contractKey ? { contractKey, id: `goto:${ticker.metadata.ticker}:${contractKey}` } : {}),
+        } as TickerSearchCandidate;
+      });
   });
 }
 
@@ -89,9 +128,15 @@ function createProviderTickerSearchCandidates(
   return searchResults.flatMap((result, providerRank) => {
     if (options.includeOptionContracts === false && isOptionSearchResult(result)) return [];
     const symbol = getSearchResultSymbol(result);
-    const saved = localTickers.has(symbol);
+    const currency = result.currency || getForexQuoteCurrency(symbol);
+    if (currency && !result.currency) result = { ...result, currency };
+    const listingKey = publicTickerKey(symbol, listingExchange(result));
+    const savedTicker = localTickers.get(listingKey) ?? localTickers.get(symbol);
+    const saved = !!savedTicker
+      && publicTickerKey(savedTicker.metadata.ticker, savedTicker.metadata.exchange) === listingKey;
     return [{
       id: buildProviderCandidateId(result, symbol),
+      contractKey: searchContractKey(result),
       label: symbol,
       symbol,
       detail: [result.name, result.brokerLabel, result.type].filter(Boolean).join(" | "),
@@ -103,6 +148,7 @@ function createProviderTickerSearchCandidates(
       kind: "search",
       saved,
       instrumentClass: classifyInstrumentKind(result.brokerContract?.secType || result.type),
+      instrumentType: result.brokerContract?.secType || result.type,
       searchAliases: buildSearchResultAliases(result),
       result,
     }];
@@ -197,6 +243,12 @@ export async function resolveTickerSearch({
     ?? findExactTickerSearchMatch(createLocalTickerSearchCandidates(tickers.values()), symbol)?.ticker
     ?? null;
   if (local) {
+    const contracts = new Map((local.metadata.broker_contracts ?? []).flatMap((brokerContract) => {
+      const key = searchContractKey({ brokerContract, type: local.metadata.assetCategory || "" });
+      return key ? [[key, brokerContract] as const] : [];
+    }));
+    if (contracts.size > 1) throw new AmbiguousContractError(symbol,
+      [...contracts.values()].map((contract) => tickerInstrumentLabel(local.metadata.ticker, contract)));
     return { kind: "local", symbol: local.metadata.ticker, ticker: local };
   }
 
@@ -204,16 +256,62 @@ export async function resolveTickerSearch({
     await searchProviderResults(dataProvider, symbol, searchContext),
     tickers,
   );
-  const exactMatch = findExactTickerSearchMatch(providerItems, symbol);
+  const literalMatches = providerItems.filter((item) => normalizeTickerSymbol(item.symbol) === symbol);
+  const matches = literalMatches.length ? literalMatches
+    : providerItems.filter((item) => findExactTickerSearchMatch([item], symbol));
+  let exactMatch = matches[0];
   if (!exactMatch?.result) return null;
 
+  const contracts = new Set(matches.map((item) => item.contractKey).filter(Boolean));
+  if (contracts.size > 1 || (contracts.size && matches.some((item) => !item.contractKey))) {
+    throw new AmbiguousContractError(symbol, matches.map((item) => tickerInstrumentLabel(item.symbol, item.result?.brokerContract)));
+  }
+  const listings = new Set(matches.map((item) => publicTickerKey(item.symbol, listingExchange(item.result!))));
+  if (listings.size > 1 && !parsePublicTickerKey(symbol).exchange && !tickerHasYahooSuffix(symbol)) {
+    // Search order is relevance, not a canonical listing identifier. Align bare
+    // symbols with the quote source only when it supplies the exact identity.
+    let verified: TickerSearchCandidate[] = [];
+    try {
+      const quote = await dataProvider.getQuote(symbol, "", {
+        brokerId: searchContext?.brokerId,
+        brokerInstanceId: searchContext?.brokerInstanceId,
+      });
+      const exchange = canonicalExchange(quote.listingExchangeName || quote.exchangeName);
+      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 result = item.result!;
+          const candidateCurrency = resolveCurrencyUnit(result.currency).currency;
+          return canonicalExchange(listingExchange(result)) === exchange
+            && (!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 } }));
+      }
+    } catch {
+      // An unavailable quote cannot establish the default listing.
+    }
+    if (new Set(verified.map((item) => publicTickerKey(item.symbol, listingExchange(item.result!)))).size !== 1) {
+      throw new AmbiguousTickerError(symbol, [...listings], Object.fromEntries(matches.map((item) => [
+        publicTickerKey(item.symbol, listingExchange(item.result!)), item.result!.name,
+      ])));
+    }
+    exactMatch = verified[0]!;
+  }
+
   return {
     kind: "provider",
     symbol: exactMatch.symbol,
-    result: exactMatch.result,
+    result: exactMatch.result!,
   };
 }
 
+function listingExchange(result: InstrumentSearchResult): string {
+  return result.exchange === "SMART" ? result.primaryExchange || result.exchange
+    : result.exchange || result.primaryExchange || "";
+}
+
 function buildProviderHints(
   searchResults: InstrumentSearchResult[],
   localTickers: ReadonlyMap<string, TickerRecord>,
@@ -278,12 +376,54 @@ async function searchProviderResults(
     }
   }));
 
+  // Catalogues can omit exact market symbols or return a crypto pair from a
+  // different venue. Verify the requested quote before accepting an alias.
+  const requested = parsePublicTickerKey(normalizeTickerSymbol(query));
+  const possibleCryptoPair = /^[A-Z0-9]{1,15}-[A-Z]{3,5}$/.test(requested.symbol);
+  if ((isExplicitMarketSymbol(query) || possibleCryptoPair)
+    && !findExactTickerSearchMatch([...byKey.values()].map((result) => ({
+      label: getSearchResultSymbol(result), instrumentType: result.type, right: result.exchange,
+    })), query)) {
+    const { symbol, exchange } = requested;
+    const marketType = /=F$/.test(symbol) ? "FUTURE"
+      : /^(?:[A-Z]{3}(?:\/[A-Z]{3}|(?:[A-Z]{3})?=X))$/.test(symbol) ? "CURRENCY"
+      : /^\^[A-Z0-9.-]+$/.test(symbol) ? "INDEX" : null;
+    if (marketType || possibleCryptoPair) {
+      try {
+        const quote = await dataProvider.getQuote(symbol, exchange);
+        const type = isCryptoInstrumentType(quote.instrumentType) ? quote.instrumentType : marketType;
+        if (Number.isFinite(quote.price) && quote.price !== 0
+          && Number.isFinite(quote.lastUpdated) && quote.lastUpdated > 0
+          && quote.currency?.trim()
+          && type
+          && (!isCryptoInstrumentType(type) || quote.price > 0)
+          && (!exchange || canonicalExchange(quote.listingExchangeName || quote.exchangeName) === exchange)
+          && (possibleCryptoPair ? normalizeTickerSymbol(quote.symbol) === symbol
+            : findExactTickerSearchMatch([{ label: quote.symbol }], symbol))) {
+          add([{
+            providerId: quote.providerId || dataProvider.id,
+            symbol,
+            name: quote.name || symbol,
+            exchange: exchange || quote.listingExchangeName || quote.exchangeName || "",
+            currency: quote.currency,
+            type,
+          }]);
+        }
+      } catch {
+        // An unverified symbol stays unresolved; never substitute a fuzzy equity.
+      }
+    }
+  }
+
   return [...byKey.values()];
 }
 
 function buildProviderSearchQueries(query: string): string[] {
   const trimmedQuery = query.trim();
   if (!trimmedQuery) return [];
+  const qualified = parsePublicTickerKey(trimmedQuery);
+  if (qualified.exchange) return [trimmedQuery.toUpperCase(), qualified.symbol];
+  if (tickerHasYahooSuffix(trimmedQuery.toUpperCase())) return [trimmedQuery.toUpperCase()];
 
   const symbolLike = /^[A-Za-z0-9.^=\-/]+$/.test(trimmedQuery);
   const queries = new Set<string>();
@@ -306,13 +446,7 @@ function buildCompactShareClassAliases(query: string): string[] {
 }
 
 function buildProviderSearchResultKey(result: InstrumentSearchResult): string {
-  return [
-    normalizeTickerSymbol(result.symbol),
-    normalizeSearchText(result.exchange || ""),
-    normalizeSearchText(result.type || ""),
-    normalizeSearchText(result.primaryExchange || ""),
-    normalizeSearchText(result.currency || ""),
-  ].join("|");
+  return searchInstrumentKey(result);
 }
 
 function buildProviderCandidateId(result: InstrumentSearchResult, symbol: string): string {
@@ -322,6 +456,7 @@ function buildProviderCandidateId(result: InstrumentSearchResult, symbol: string
     normalizeSearchText(result.exchange || result.primaryExchange || result.type || ""),
     normalizeSearchText(result.currency || ""),
     normalizeSearchText(result.providerId || ""),
+    searchContractKey(result),
   ].filter(Boolean).join(":");
 }
 

package/src/tickers/search/ranking.ts

@@ -2,10 +2,12 @@ import type {
   TickerSearchInstrumentClass,
   TickerSearchRankableItem,
 } from "./types";
+import { getYahooSymbol, tickerHasYahooSuffix } from "../../sources/yahoo-finance/symbols";
+import { canonicalExchange, parsePublicTickerKey } from "../../utils/exchanges";
 
 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"]);
-const EQUITY_TYPES = new Set(["STK", "STOCK", "EQUITY", "COMMONSTOCK", "COMMON STOCK", "ADR", "ORDINARYSHARES", "ORDINARY SHARES"]);
+const EQUITY_TYPES = new Set(["STK", "STOCK", "EQUITY", "COMMONSTOCK", "COMMON STOCK", "ADR", "DEPOSITARY RECEIPT", "DEPOSITARYRECEIPT", "ORDINARYSHARES", "ORDINARY SHARES"]);
 const COMPANY_NAME_SUFFIXES = new Set([
   "AG",
   "CO",
@@ -66,6 +68,7 @@ const ASSET_HINT_MAP: Record<string, TickerSearchInstrumentClass> = {
 const SAVED_MATCH_BONUS = 900;
 
 interface SearchQueryIntent {
+  rawQuery: string;
   normalizedQuery: string;
   compactQuery: string;
   companyQuery: string;
@@ -78,11 +81,16 @@ export function findExactTickerSearchMatch<T extends Pick<TickerSearchRankableIt
   items: T[],
   query: string,
 ): T | null {
+  const literal = items.find((item) => normalizeTickerSymbol(item.symbol || item.label) === normalizeTickerSymbol(query));
+  if (literal) return literal;
+  if (isQualifiedTickerQuery(query)) {
+    return items.find((item) => matchesQualifiedTicker(item, query)) ?? null;
+  }
   const aliasForms = buildSymbolAliases(query);
   const normalizedAliases = new Set(aliasForms.map((value) => normalizeSearchText(value)));
   const compactAliases = new Set(aliasForms.map((value) => compactSearchText(value)));
 
-  return items.find((item) =>
+  return items.find((item) => !isExplicitMarketSymbol(item.symbol || item.label) && !isCryptoInstrumentType(item.instrumentType) &&
     getItemSearchAliases(item).some((alias) =>
       normalizedAliases.has(normalizeSearchText(alias))
       || compactAliases.has(compactSearchText(alias))
@@ -90,6 +98,61 @@ export function findExactTickerSearchMatch<T extends Pick<TickerSearchRankableIt
   ) ?? null;
 }
 
+export function isCryptoInstrumentType(type?: string): boolean {
+  return ["CRYPTO", "CRYPTOCURRENCY", "DIGITALCURRENCY"].includes((type ?? "").toUpperCase().replace(/[\s_-]/g, ""));
+}
+
+function isQualifiedTickerQuery(query: string): boolean {
+  const symbol = normalizeTickerSymbol(query);
+  return isExplicitMarketSymbol(symbol) || !!parsePublicTickerKey(symbol).exchange || tickerHasYahooSuffix(symbol);
+}
+
+/** Futures, currency pairs, and indices use punctuation as part of their identity. */
+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);
+}
+
+/** Venue and market syntax must survive exact matching. Only explicit FX forms are equivalent. */
+function matchesQualifiedTicker(
+  item: Pick<TickerSearchRankableItem, "label"> & Partial<TickerSearchRankableItem>,
+  query: string,
+): boolean {
+  const normalized = normalizeTickerSymbol(query);
+  const symbol = normalizeTickerSymbol(item.symbol || item.label);
+  if (symbol === normalized) return true;
+  const requested = parsePublicTickerKey(normalized);
+  const candidate = parsePublicTickerKey(symbol);
+  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);
+  }
+  if (isExplicitMarketSymbol(requested.symbol)) {
+    const pair = forexPair(requested.symbol);
+    return candidate.symbol === requested.symbol || (pair != null && forexPair(candidate.symbol) === pair);
+  }
+  return exchanges.some((exchange) => getYahooSymbol(candidate.symbol, exchange).toUpperCase() === normalized);
+}
+
+function getTickerSearchListingKey(item: Pick<TickerSearchRankableItem, "label"> & Partial<TickerSearchRankableItem>): string {
+  const parsed = parsePublicTickerKey(normalizeTickerSymbol(item.symbol || item.label));
+  const exchange = parsed.exchange || (item.exchangeLabel === "SMART" ? item.primaryExchangeLabel
+    : item.exchangeLabel || item.primaryExchangeLabel || item.right);
+  return `${parsed.symbol}|${canonicalExchange(exchange)}${item.contractKey ? `|${item.contractKey}` : ""}`;
+}
+
 export function rankTickerSearchItems<T extends Pick<TickerSearchRankableItem, "id" | "label" | "detail" | "kind" | "category" | "right"> & Partial<TickerSearchRankableItem>>(
   items: T[],
   query: string,
@@ -126,7 +189,8 @@ export function rankTickerSearchItems<T extends Pick<TickerSearchRankableItem, "
       );
       const aliasScore = getItemSearchAliases(item)
         .reduce((best, alias) => Math.max(best, scoreSearchAlias(intent, alias)), 0);
-      const textScore = labelScore + detailScore + aliasScore;
+      const textScore = labelScore + detailScore + aliasScore
+        + (isQualifiedTickerQuery(query) && matchesQualifiedTicker(item, query) ? 100_000 : 0);
       const saved = isSavedSearchItem(item);
       const explicitIntentScore = scoreAssetPreference(intent, item.instrumentClass)
         + scoreExchangePreference(intent, item);
@@ -148,16 +212,18 @@ export function rankTickerSearchItems<T extends Pick<TickerSearchRankableItem, "
       };
     });
 
-  const matchedLocalSymbols = new Set(
+  // A saved symbol replaces its own source listing, not every exchange using it.
+  const matchedLocalListings = new Set(
     ranked
       .filter(({ item, textScore }) => textScore > 0 && item.kind === "ticker")
-      .map(({ normalizedSymbol }) => normalizedSymbol),
+      .map(({ item }) => getTickerSearchListingKey(item)),
   );
 
-  const filtered = ranked.filter(({ item, normalizedSymbol, textScore }) => {
+  const filtered = ranked.filter(({ item, textScore }) => {
     if (textScore <= 0) return false;
+    if (isExplicitMarketSymbol(query) && !isExplicitMarketSymbol(item.symbol || item.label)) return false;
     if (item.kind !== "search") return true;
-    return !matchedLocalSymbols.has(normalizedSymbol);
+    return !matchedLocalListings.has(getTickerSearchListingKey(item));
   });
 
   type RankedEntry = (typeof ranked)[number];
@@ -267,6 +333,12 @@ export function normalizeTickerSymbol(symbol: string): string {
 export function buildSymbolAliases(symbol: string): string[] {
   const normalizedSymbol = normalizeTickerSymbol(symbol);
   if (!normalizedSymbol) return [];
+  if (isExplicitMarketSymbol(normalizedSymbol)) {
+    const pair = forexPair(normalizedSymbol);
+    return pair
+      ? [...new Set([normalizedSymbol, `${pair}=X`, `${pair.slice(0, 3)}/${pair.slice(3)}`])]
+      : [normalizedSymbol];
+  }
 
   const searchText = normalizeSearchText(normalizedSymbol);
   const aliases = new Set<string>([
@@ -312,6 +384,7 @@ function analyzeSearchQuery(query: string): SearchQueryIntent {
   const companyQuery = companyTokens.join(" ");
 
   return {
+    rawQuery: query,
     normalizedQuery,
     compactQuery,
     companyQuery,
@@ -376,6 +449,10 @@ function scoreSymbolMatchRank(
   intent: SearchQueryIntent,
   item: Pick<TickerSearchRankableItem, "label"> & Partial<TickerSearchRankableItem>,
 ): number {
+  if (normalizeTickerSymbol(item.symbol || item.label) === normalizeTickerSymbol(intent.rawQuery)) return 4;
+  if (isQualifiedTickerQuery(intent.rawQuery)) return matchesQualifiedTicker(item, intent.rawQuery) ? 4 : 0;
+  if (isCryptoInstrumentType(item.instrumentType)) return 0;
+  if (isExplicitMarketSymbol(item.symbol || item.label)) return 0;
   if (!intent.normalizedQuery && !intent.compactQuery) return 0;
   const displaySymbol = normalizeSearchText(item.symbol || item.label);
   const compactDisplaySymbol = compactSearchText(item.symbol || item.label);
@@ -521,6 +598,5 @@ function scoreSearchField(query: string, value: string, weights: { exact: number
 
 function getTickerSearchDedupKey(item: Pick<TickerSearchRankableItem, "id" | "kind" | "label" | "detail" | "right"> & Partial<TickerSearchRankableItem>): string {
   if (item.kind !== "ticker" && item.kind !== "search") return item.id;
-  const qualifier = normalizeSearchText(item.right || item.detail.split("|").at(-1) || "");
-  return `${normalizeSearchText(item.symbol || item.label)}|${qualifier}`;
+  return getTickerSearchListingKey(item);
 }

package/src/tickers/search/types.ts

@@ -1,4 +1,4 @@
-import type { InstrumentSearchResult } from "../../types/instrument";
+import type { BrokerContractRef, InstrumentSearchResult, TickerListingRef } from "../../types/instrument";
 import type { TickerRecord } from "../../types/ticker";
 
 export type TickerSearchInstrumentClass = "equity" | "fund" | "derivative" | "other";
@@ -14,6 +14,8 @@ export interface TickerSearchRankableItem {
   symbol?: string;
   saved?: boolean;
   instrumentClass?: TickerSearchInstrumentClass;
+  instrumentType?: string;
+  contractKey?: string;
   exchangeLabel?: string;
   primaryExchangeLabel?: string;
   providerRank?: number;
@@ -39,4 +41,6 @@ export interface TickerOpenTarget {
   symbol: string;
   ticker: TickerRecord;
   created: boolean;
+  instrument?: BrokerContractRef | null;
+  listing?: TickerListingRef;
 }

package/src/tickers/search/upsert.ts

@@ -8,14 +8,25 @@ import {
   getSearchResultSymbol,
   shouldReplaceTickerName,
 } from "./result";
-import { canonicalExchange } from "../../utils/exchanges";
+import { canonicalExchange, parsePublicTickerKey, publicTickerKey } from "../../utils/exchanges";
+import { scopedBrokerContractIdentityKey } from "../../utils/instrument-identity";
 
 export async function upsertTickerFromSearchResult(
   tickerRepository: AppTickerRepositoryPort,
   result: InstrumentSearchResult,
+  options: { tickerSymbol?: string } = {},
 ): Promise<{ ticker: TickerRecord; created: boolean }> {
-  const symbol = getSearchResultSymbol(result);
+  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);
+    ticker = await tickerRepository.loadTicker(symbol);
+  }
   const created = !ticker;
 
   if (!ticker) {
@@ -39,10 +50,7 @@ export async function upsertTickerFromSearchResult(
     if (result.brokerContract) {
       const nextContracts = [...existingContracts];
       const hasContract = nextContracts.some((contract) =>
-        contract.brokerId === result.brokerContract!.brokerId
-        && contract.brokerInstanceId === result.brokerContract!.brokerInstanceId
-        && contract.conId === result.brokerContract!.conId
-        && contract.localSymbol === result.brokerContract!.localSymbol
+        scopedBrokerContractIdentityKey(contract) === scopedBrokerContractIdentityKey(result.brokerContract!)
       );
       if (!hasContract) {
         nextContracts.push(result.brokerContract);