gloomberb 0.16.3 → 0.16.4

package/src/utils/price-history.ts

@@ -1,6 +1,7 @@
 import type { PricePoint, TickerFinancials } from "../types/financials";
 import { canonicalExchange, resolveExchangeTimeZone } from "./exchanges";
 import { isRoundTheClockCoin } from "./crypto-pair";
+import { isCurrencyPairListing, latestFxWeekClose } from "./fx-market-hours";
 import { hasPublishedSessionCalendar, isRegularSessionTime, isTimestampStaleForExchangeSession, latestRegularSessionClose, latestRegularSessionOpen, sessionCalendarTimeZone } from "../market-data/market/freshness";
 import { zonedDateTimeParts } from "./zoned-date-time";
 import { regularHistorySessionStaleness } from "../market-data/history-session";
@@ -29,6 +30,16 @@ interface PriceHistoryFreshnessOptions {
   session?: HistorySession;
 }
 
+/**
+ * How old the newest bar of a current copy may be. Completed bars are
+ * timestamped at their opening time, so before the next one is delivered the
+ * newest may be almost two intervals plus the feed delay old; finer bars keep
+ * a floor.
+ */
+function allowedBarLagMs(intervalMs: number | null): number {
+  return Math.max(MAX_SAME_SESSION_HISTORY_LAG_MS, intervalMs != null ? 2 * intervalMs + DELAYED_HISTORY_ALLOWANCE_MS : 0);
+}
+
 export function priceHistoryIntervalMs(interval: string): number | null {
   const parsed = parseBarInterval(interval);
   return parsed ? parsed.count * BAR_INTERVAL_UNIT_MS[parsed.unit] : null;
@@ -204,11 +215,7 @@ export function isPriceHistoryStaleForCurrentWindow(
     if (regularStale !== null) return regularStale;
   }
   const age = now - latestTime;
-  // Completed bars are timestamped at their opening time. Before the next
-  // completed bar is delivered, the newest bar may be almost two intervals
-  // plus the feed delay old. Keep the existing tolerance for finer bars.
-  const allowedLag = Math.max(MAX_SAME_SESSION_HISTORY_LAG_MS,
-    intervalMs != null ? 2 * intervalMs + DELAYED_HISTORY_ALLOWANCE_MS : 0);
+  const allowedLag = allowedBarLagMs(intervalMs);
   if (age <= allowedLag) return false;
   const exchange = options.exchange || "NASDAQ";
   // Bars that reach the close of the venue's latest session stay current
@@ -310,6 +317,31 @@ function isBarBeforeSession(latestTime: number, session: string, intervalMs: num
   return dayNumber(session) >= dayNumber(bar) + Math.max(1, Math.round(intervalMs / DAY_MS));
 }
 
+/**
+ * An intraday copy fetched before the venue's latest session settled holds
+ * that session only as far as the fetch. Once the session is over, or the
+ * next has begun, a copy whose last bar stops short of the close by more than
+ * a current copy's bars may lag is refetched. A copy fetched after the
+ * session settled holds all of it, however early its last bar: a thin listing
+ * need not trade late. A currency pair's session is the FX week, which closes
+ * Friday 17:00 New York. Coins never close, and within the FX week neither do
+ * pairs: isPriceHistoryStaleForCurrentWindow holds those copies to the present.
+ */
+function intradayHistoryFetchState(
+  points: PricePoint[], fetchedAt: number, now: number, intervalMs: number, options: CalendarHistoryFetchOptions,
+): CalendarHistoryFetchState {
+  if (isRoundTheClockCoin(options.symbol, options.exchange)) return "current";
+  const settledBy = now - SESSION_BAR_SETTLE_MS;
+  // Bare symbols resolve to their US listing at the sources.
+  const close = isCurrencyPairListing(options.symbol, options.exchange) ? latestFxWeekClose(settledBy)
+    : latestRegularSessionClose(canonicalExchange(options.exchange) || "NYSE", settledBy)?.close ?? null;
+  if (close === null || fetchedAt >= close + SESSION_BAR_SETTLE_MS) return "current";
+  const latest = points.findLast(hasFiniteClose);
+  const latestTime = latest ? getPricePointTimestamp(latest) : Number.NaN;
+  if (!Number.isFinite(latestTime) || latestTime >= close - allowedBarLagMs(intervalMs)) return "current";
+  return unsettledState(close + SESSION_BAR_SETTLE_MS, options.checkedAt, now);
+}
+
 /**
  * A daily or coarser series changes at every close. A copy fetched before the
  * latest settled close is outdated whatever its cache TTL. A copy fetched
@@ -327,7 +359,8 @@ export function calendarHistoryFetchState(
   if (!Number.isFinite(fetchedAt) || !Number.isFinite(now) || fetchedAt >= now) return "current";
   const normalized = normalizePriceHistory(points);
   const intervalMs = options.intervalMs ?? inferredHistoryIntervalMs(normalized);
-  if (intervalMs == null || intervalMs < DAY_MS) return "current";
+  if (intervalMs == null) return "current";
+  if (intervalMs < DAY_MS) return intradayHistoryFetchState(normalized, fetchedAt, now, intervalMs, options);
   const exchange = canonicalExchange(options.exchange);
   if (isRoundTheClockCoin(options.symbol, options.exchange)) {
     return now - fetchedAt > CRYPTO_BAR_MAX_AGE_MS

package/src/utils/rpc-timeout-error.ts

@@ -1,5 +1,9 @@
-/** A timeout this many times past its limit means the machine slept through it. */
-const SLEEP_TIMEOUT_FACTOR = 5;
+/**
+ * A timeout this many times past its limit means the page was suspended, not
+ * that the Bun process stalled. A page that is running fires the timer within
+ * a second or two of its limit, and a hidden one within a minute.
+ */
+const SLEEP_TIMEOUT_FACTOR = 2;
 
 /**
  * A call to the desktop's Bun process that did not complete in time: the

package/src/utils/sec-eps-basis.ts

@@ -23,6 +23,8 @@ export interface SecEpsBasis {
 type Fact = { start?: string; end?: string; val?: number; accn?: string; filed?: string; form?: string };
 type Row = Fact & { start: string; end: string; val: number; accn: string; filed: string };
 type Edge = { node: string; factor: number; evidence?: SecEpsSplitEvidence };
+type Proof = { split: Fact; before: Row; after: Row; evidence: SecEpsSplitEvidence };
+type SplitEvent = { ratio: number; proofs: Proof[]; consistent: boolean; evidence: SecEpsSplitEvidence; node: string };
 const date = (value: unknown): value is string => typeof value === "string" && /^\d{4}-\d{2}-\d{2}$/.test(value)
   && Number.isFinite(Date.parse(`${value}T00:00:00Z`)) && new Date(`${value}T00:00:00Z`).toISOString().slice(0, 10) === value;
 const record = (value: unknown): Record<string, unknown> => value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
@@ -47,27 +49,83 @@ function uniqueObservations(rows: Fact[]): Map<string, Row> {
   return result;
 }
 
+/** When the last restated filing and the first restating one were filed: the split falls between. */
+function cut(proofs: Proof[]): { lastRestated: string; firstRestating: string } {
+  return {
+    lastRestated: proofs.reduce((max, proof) => proof.before.filed > max ? proof.before.filed : max, ""),
+    firstRestating: proofs.reduce((min, proof) => proof.after.filed < min ? proof.after.filed : min, "9999"),
+  };
+}
+const separable = (proofs: Proof[]) => cut(proofs).lastRestated < cut(proofs).firstRestating;
+
+/**
+ * One split, however many filings repeat it and under whatever context dates
+ * (an approval date, the effective date, each period of the equity statement).
+ * Rows with one ratio and one context date are one disclosure. A split divides
+ * the filings once, so disclosures with one ratio are one split when a single
+ * filing date still separates every filing they restate from every filing that
+ * restates; two splits with one ratio leave no such date (the later split
+ * restates filings that already carry the earlier one).
+ */
+function splitEvents(proofs: Proof[]): SplitEvent[] {
+  const disclosures = new Map<string, Proof[]>();
+  for (const proof of proofs) {
+    const key = `${proof.split.val}:${proof.split.end}`;
+    disclosures.set(key, [...disclosures.get(key) ?? [], proof]);
+  }
+  const groups: Proof[][] = [];
+  for (const ratio of new Set(proofs.map((proof) => proof.split.val!))) {
+    const sorted = [...disclosures.values()].filter((group) => group[0]!.split.val === ratio)
+      .sort((a, b) => cut(a).firstRestating.localeCompare(cut(b).firstRestating) || cut(a).lastRestated.localeCompare(cut(b).lastRestated));
+    let current: Proof[] = [];
+    for (const disclosure of sorted) {
+      // A disclosure whose own filings admit no such date proves nothing.
+      if (!separable(disclosure)) groups.push(disclosure);
+      else if (current.length && separable([...current, ...disclosure])) current.push(...disclosure);
+      else {
+        current = [...disclosure];
+        groups.push(current);
+      }
+    }
+  }
+  return groups.map((group, index) => {
+    const first = [...group].sort((a, b) => a.after.filed.localeCompare(b.after.filed) || a.after.accn.localeCompare(b.after.accn)
+      || a.split.end!.localeCompare(b.split.end!) || a.before.filed.localeCompare(b.before.filed) || a.before.end.localeCompare(b.before.end))[0]!;
+    return { ratio: group[0]!.split.val!, proofs: group, consistent: separable(group), evidence: first.evidence, node: `split:${index}` };
+  });
+}
+
 /**
  * Share bases belong to source accessions, not filing dates. A split edge needs
  * an explicit SEC split fact and unchanged same-period income with inverse EPS
- * restatement. Repeated EPS AND diluted shares connect otherwise equal bases.
+ * restatement. Repeated EPS AND diluted shares connect otherwise equal bases;
+ * where a filing tags no diluted shares, repeated EPS AND income do, if no
+ * disclosed split could leave that EPS unchanged at cent rounding.
  * No price jump, ticker exception, or chronological assumption establishes one.
+ *
+ * Every filing that states a split and restates an earlier filing by its ratio
+ * is evidence of that split. The filings it restated share one basis and the
+ * restating filings share the next, so a split filed in several filings under
+ * several context dates is one factor, not a run of unproved disclosures.
  */
 export function createSecEpsBasisResolver(payload: unknown): (fact: Fact) => { value?: number; basis?: SecEpsBasis; availableAt?: string } {
   const splits = entries(payload, "StockholdersEquityNoteStockSplitConversionRatio1", "pure")
     .filter((row) => row.val! > 0 && row.val !== 1)
     .sort((a, b) => a.filed!.localeCompare(b.filed!));
   if (splits.length === 0) return (fact) => ({ value: fact.val, availableAt: fact.filed });
-  const eventRows = new Map<string, Fact>();
-  const conflicts = new Set<string>();
+  // A filing that gives one split context two ratios contradicts itself.
+  const stated = new Map<string, number>();
+  const contradicted = new Set<string>();
   for (const split of splits) {
-    if (eventRows.has(split.end!) && eventRows.get(split.end!)!.val !== split.val) conflicts.add(split.end!);
-    if (!eventRows.has(split.end!)) eventRows.set(split.end!, split);
+    const context = `${split.accn}:${split.end}`;
+    if (stated.has(context) && stated.get(context) !== split.val) contradicted.add(context);
+    stated.set(context, split.val!);
   }
-  const latest = [...eventRows.values()].sort((a, b) => a.end!.localeCompare(b.end!)).at(-1)!;
+  const latest = [...splits].sort((a, b) => b.end!.localeCompare(a.end!))[0]!;
   const eps = uniqueObservations(entries(payload, "EarningsPerShareDiluted", "USD/shares"));
   const shares = uniqueObservations(entries(payload, "WeightedAverageNumberOfDilutedSharesOutstanding", "shares"));
   const income = uniqueObservations(entries(payload, "NetIncomeLoss", "USD"));
+  const key = (row: Fact) => `${row.accn}:${row.start}:${row.end}`;
   const graph = new Map<string, Edge[]>();
   const connect = (before: string, after: string, ratio: number, evidence?: SecEpsSplitEvidence) => {
     graph.set(after, [...graph.get(after) ?? [], { node: before, factor: ratio, evidence }]);
@@ -75,44 +133,116 @@ export function createSecEpsBasisResolver(payload: unknown): (fact: Fact) => { v
   };
   const identical = new Map<string, Row>();
   const periods = new Map<string, Row[]>();
-  for (const [key, row] of eps) {
+  for (const row of eps.values()) {
     const period = `${row.start}:${row.end}`;
     periods.set(period, [...periods.get(period) ?? [], row]);
-    const denominator = shares.get(key)?.val;
+    const denominator = shares.get(key(row))?.val;
     if (!row.val || !denominator || denominator <= 0) continue;
     const identity = `${period}:${row.val}:${denominator}`;
     const prior = identical.get(identity);
     if (prior && prior.accn !== row.accn) connect(prior.accn, row.accn, 1);
     else identical.set(identity, row);
   }
-  const proved = new Map<string, SecEpsSplitEvidence>();
-  for (const split of eventRows.values()) {
-    if (conflicts.has(split.end!)) continue;
+  // Not every filer tags diluted shares (Alphabet before 2024). Where a filing
+  // tags none for the period, a repeated EPS and net income connect instead,
+  // when no disclosed split ratio could leave that EPS unchanged at cent
+  // rounding. Diluted shares that differ still keep the bases apart.
+  const ratios = [...new Set(splits.map((split) => split.val!))];
+  const telling = (value: number) => ratios.every((ratio) => Math.abs(value - value / ratio) > .005 + .005 / ratio
+    && Math.abs(value - value * ratio) > .005 + .005 * ratio);
+  const tagged = new Set(entries(payload, "WeightedAverageNumberOfDilutedSharesOutstanding", "shares").map(key));
+  for (const rows of periods.values()) {
+    for (let i = 0; i < rows.length; i++) {
+      for (let j = i + 1; j < rows.length; j++) {
+        const [a, b] = [rows[i]!, rows[j]!];
+        if (a.accn === b.accn || a.val !== b.val || !a.val || !telling(a.val)) continue;
+        if (tagged.has(key(a)) && tagged.has(key(b))) continue;
+        const repeated = income.get(key(a))?.val;
+        if (repeated !== undefined && repeated !== 0 && repeated === income.get(key(b))?.val) connect(a.accn, b.accn, 1);
+      }
+    }
+  }
+  // A later filing restates an earlier one's EPS for the same period by the
+  // ratio, with income unchanged.
+  const restates = (before: Row, after: Row, ratio: number) => {
+    if (before.accn === after.accn || before.filed >= after.filed || before.val === after.val || before.val * after.val <= 0) return false;
+    const beforeIncome = income.get(key(before))?.val;
+    const afterIncome = income.get(key(after))?.val;
+    if (beforeIncome === undefined || beforeIncome === 0 || beforeIncome !== afterIncome) return false;
+    // EPS reports rounded to cents have overlapping rounding intervals.
+    // This accommodates 11.91 / 4 -> 2.98 without inventing precision.
+    const tolerance = .005 + .005 / ratio;
+    return Math.abs(before.val / ratio - after.val) <= tolerance + 1e-12 && Math.abs(before.val - after.val) > tolerance * 2;
+  };
+  const proofs: Proof[] = [];
+  for (const split of splits) {
+    if (contradicted.has(`${split.accn}:${split.end}`)) continue;
     for (const after of eps.values()) {
       if (after.accn !== split.accn || after.filed !== split.filed || after.end >= split.end! || after.val === 0) continue;
       for (const before of periods.get(`${after.start}:${after.end}`) ?? []) {
-        if (before.accn === after.accn || before.filed >= after.filed || before.val === after.val || before.val * after.val <= 0) continue;
-        const beforeIncome = income.get(`${before.accn}:${before.start}:${before.end}`)?.val;
-        const afterIncome = income.get(`${after.accn}:${after.start}:${after.end}`)?.val;
-        if (beforeIncome === undefined || beforeIncome === 0 || beforeIncome !== afterIncome) continue;
-        // EPS reports rounded to cents have overlapping rounding intervals.
-        // This accommodates 11.91 / 4 -> 2.98 without inventing precision.
-        const tolerance = .005 + .005 / split.val!;
-        if (Math.abs(before.val / split.val! - after.val) > tolerance + 1e-12
-          || Math.abs(before.val - after.val) <= tolerance * 2) continue;
-        const evidence: SecEpsSplitEvidence = {
+        if (!restates(before, after, split.val!)) continue;
+        proofs.push({ split, before, after, evidence: {
           date: split.end!, ratio: split.val!, accessionNumber: split.accn!, filed: split.filed!,
           comparativePeriodEnd: before.end, beforeAccessionNumber: before.accn, beforeEps: before.val, afterEps: after.val,
-        };
-        connect(before.accn, after.accn, split.val!, evidence);
-        proved.set(split.end!, evidence);
+        } });
       }
     }
   }
+  const events = splitEvents(proofs);
+  const consistent = events.filter((event) => event.consistent);
+  // The filings a split restated share one basis and its restating filings the
+  // next. Evidence that mixes splits only connects the two filings it compares.
+  const eventOf = new Map<Fact, SplitEvent>();
+  for (const event of events) {
+    if (!event.consistent) {
+      for (const proof of event.proofs) connect(proof.before.accn, proof.after.accn, event.ratio, proof.evidence);
+      continue;
+    }
+    connect(`${event.node}:before`, `${event.node}:after`, event.ratio, event.evidence);
+    for (const proof of event.proofs) {
+      connect(proof.before.accn, `${event.node}:before`, 1);
+      connect(`${event.node}:after`, proof.after.accn, 1);
+      eventOf.set(proof.split, event);
+    }
+  }
+  // A filing that repeats a proved split's restatement without stating its
+  // ratio (a 10-K after the split's 10-Qs) restates on that split when exactly
+  // one split fits: the restated filing before the split's first restating
+  // filing, the restating one after its last restated filing, and a period
+  // before the split's context dates.
+  const known = new Set([...proofs.flatMap((proof) => [proof.before.accn, proof.after.accn]),
+    ...splits.filter((split) => contradicted.has(`${split.accn}:${split.end}`)).map((split) => split.accn!)]);
+  for (const after of eps.values()) {
+    if (known.has(after.accn) || after.val === 0) continue;
+    for (const before of periods.get(`${after.start}:${after.end}`) ?? []) {
+      const fits = consistent.filter((event) => restates(before, after, event.ratio)
+        && before.filed < cut(event.proofs).firstRestating && after.filed > cut(event.proofs).lastRestated
+        && event.proofs.some((proof) => after.end < proof.split.end!));
+      if (fits.length !== 1) continue;
+      connect(before.accn, `${fits[0]!.node}:before`, 1);
+      connect(`${fits[0]!.node}:after`, after.accn, 1);
+    }
+  }
+  // A row that proves nothing itself repeats a proved split: the same ratio at
+  // the context date of a row that proves it, or else stated in one of that
+  // split's filings. Only an unambiguous match counts.
+  const proving = new Set(proofs.map((proof) => proof.split));
+  for (const split of splits) {
+    if (proving.has(split) || contradicted.has(`${split.accn}:${split.end}`)) continue;
+    const candidates = consistent.filter((event) => event.ratio === split.val);
+    const dated = candidates.filter((event) => event.proofs.some((proof) => proof.split.end === split.end));
+    const filed = candidates.filter((event) => event.proofs.some((proof) => proof.before.accn === split.accn || proof.after.accn === split.accn));
+    const match = dated.length ? dated : filed;
+    if (match.length === 1) eventOf.set(split, match[0]!);
+  }
+  // The latest disclosed split sets the current basis. Its filings must also be
+  // the latest restating filings, or the disclosures and the filings disagree.
+  const target = eventOf.get(latest);
+  let inconsistent = !!target && events.some((event) => event.consistent && event !== target
+    && cut(event.proofs).firstRestating >= cut(target.proofs).firstRestating);
   const paths = new Map<string, { factor: number; evidence: SecEpsSplitEvidence[] }>();
-  const queue = [latest.accn!];
-  paths.set(latest.accn!, { factor: 1, evidence: [] });
-  let inconsistent = false;
+  const queue = target ? [`${target.node}:after`] : [];
+  if (target) paths.set(queue[0]!, { factor: 1, evidence: [] });
   for (let i = 0; i < queue.length; i++) {
     const node = queue[i]!;
     const path = paths.get(node)!;
@@ -131,8 +261,7 @@ export function createSecEpsBasisResolver(payload: unknown): (fact: Fact) => { v
   return (fact) => {
     if (!fact.end || fact.end >= latest.end!) return { value: fact.val, availableAt: fact.filed };
     const path = fact.accn ? paths.get(fact.accn) : undefined;
-    const target = proved.get(latest.end!);
-    const evidence = [...new Map([...(path?.evidence ?? []), target ?? {
+    const evidence = [...new Map([...(path?.evidence ?? []), target?.evidence ?? {
       date: latest.end!, ratio: latest.val!, accessionNumber: latest.accn!, filed: latest.filed!,
     }].map((item) => [item.date, item])).values()].sort((a, b) => a.date.localeCompare(b.date));
     const basis: SecEpsBasis = {
@@ -140,7 +269,7 @@ export function createSecEpsBasisResolver(payload: unknown): (fact: Fact) => { v
       basisDate: latest.end!, evidence,
     };
     // Any unproved intervening disclosure can represent an additional share basis.
-    const unproved = [...eventRows.values()].some((event) => event.end! > fact.end! && !proved.has(event.end!));
+    const unproved = splits.some((split) => split.end! > fact.end! && !eventOf.has(split));
     if (!path || !target || inconsistent || unproved || !date(fact.filed)) return { basis };
     const value = fact.val! / path.factor;
     if (!Number.isFinite(value)) return { basis };

package/src/utils/sec.ts

@@ -1,4 +1,5 @@
 import type { TickerRecord } from "../types/ticker";
+import { tickerHasListingSuffix } from "../sources/listing-symbols";
 import { canonicalExchange, parsePublicTickerKey, US_LISTING_EXCHANGES } from "./exchanges";
 
 /** Canonical US equity venues: the listing exchanges plus other lit and OTC venues. */
@@ -39,40 +40,36 @@ function isFundType(value?: string): boolean {
   return FUND_TYPES.has(normalize(value).replace(/[\s_-]/g, ""));
 }
 
-export function isUsEquityTicker(ticker: TickerRecord | null | undefined): boolean {
-  return isUsListingOfType(ticker, isEquityType);
+/**
+ * Whether an equity SEC pane (filings, insider transactions) can show the
+ * ticker: an equity, or a type not filled in yet, that is not known to be
+ * listed outside the US. A ticker whose venue and currency were never filled
+ * in, as when its quote is unavailable, is looked up as a US ticker, as the
+ * SEC issuer lookup does with a symbol that names no venue.
+ */
+export function mayBeUsEquityTicker(ticker: TickerRecord | null | undefined): boolean {
+  return mayBeUsListingOfType(ticker, isEquityType);
 }
 
-/** A US equity, or a US-listed fund, which files fund forms with the SEC. */
-export function isUsEquityOrFundTicker(ticker: TickerRecord | null | undefined): boolean {
-  return isUsListingOfType(ticker, (type) => isEquityType(type) || isFundType(type));
+/** The same for a view that also lists a US-listed fund's filings, which funds file with the SEC. */
+export function mayBeUsEquityOrFundTicker(ticker: TickerRecord | null | undefined): boolean {
+  return mayBeUsListingOfType(ticker, (type) => isEquityType(type) || isFundType(type));
 }
 
-function isUsListingOfType(
+function mayBeUsListingOfType(
   ticker: TickerRecord | null | undefined,
   acceptsType: (type?: string) => boolean,
 ): boolean {
   if (!ticker) return false;
-
   const primaryContract = ticker.metadata.broker_contracts?.[0];
-  const type = primaryContract?.secType ?? ticker.metadata.assetCategory;
-  const currency = normalize(primaryContract?.currency ?? ticker.metadata.currency);
-  const exchangeCandidates = [
-    primaryContract?.primaryExchange,
-    primaryContract?.exchange,
-    ticker.metadata.exchange,
-  ];
-
-  // A listing saved without a known currency counts by its venue.
-  return acceptsType(type)
-    && (currency === "USD" || !currency)
-    && exchangeCandidates.some((exchange) => isUsExchange(exchange));
+  return acceptsType(primaryContract?.secType ?? ticker.metadata.assetCategory) && !isKnownNonUsListing(ticker);
 }
 
 /**
- * The metadata places the listing outside the US: a non-USD currency, or
- * venues none of which is a US exchange. A missing currency or venue is
- * unknown rather than foreign. SEC filings, FINRA short interest, 13F and
+ * The metadata places the listing outside the US: a non-USD currency, venues
+ * none of which is a US exchange, or, with no venue, a symbol that names one
+ * abroad (SAN:EPA, VOD.L, 7203.T). A missing currency or venue is unknown
+ * rather than foreign. SEC filings, FINRA short interest, 13F and
  * congressional disclosures only cover US listings.
  */
 export function isKnownNonUsListing(ticker: TickerRecord | null | undefined): boolean {
@@ -83,23 +80,20 @@ export function isKnownNonUsListing(ticker: TickerRecord | null | undefined): bo
   const venues = [primaryContract?.primaryExchange, primaryContract?.exchange, ticker.metadata.exchange]
     .map(normalize)
     .filter((exchange) => exchange.length > 0 && !ROUTING_EXCHANGES.has(exchange));
-  return venues.length > 0 && !venues.some((exchange) => isUsExchange(exchange));
+  if (venues.length > 0) return !venues.some((exchange) => isUsExchange(exchange));
+  const symbol = parsePublicTickerKey(ticker.metadata.ticker ?? "");
+  if (symbol.exchange) return !ROUTING_EXCHANGES.has(symbol.exchange) && !isUsExchange(symbol.exchange);
+  return tickerHasListingSuffix(symbol.symbol);
 }
 
 /**
- * The metadata shows the ticker is not a US equity: a non-USD currency, a
- * non-equity type, or only non-US exchanges. A USD ticker with no exchange is
- * unknown rather than foreign, e.g. an unsaved symbol from a quote without a
- * listing exchange.
+ * The metadata shows the ticker is not a US equity: a non-equity type or a
+ * listing known to be outside the US. A ticker with no venue or currency is
+ * unknown rather than foreign, e.g. an unsaved symbol whose quote is
+ * unavailable.
  */
 export function isKnownNonUsEquityTicker(ticker: TickerRecord | null | undefined): boolean {
-  if (!ticker || isUsEquityTicker(ticker)) return false;
-  const primaryContract = ticker.metadata.broker_contracts?.[0];
-  const currency = normalize(primaryContract?.currency ?? ticker.metadata.currency);
-  if (currency && currency !== "USD") return true;
-  if (!isEquityType(primaryContract?.secType ?? ticker.metadata.assetCategory)) return true;
-  return [primaryContract?.primaryExchange, primaryContract?.exchange, ticker.metadata.exchange]
-    .some((exchange) => normalize(exchange).length > 0);
+  return !!ticker && !mayBeUsEquityTicker(ticker);
 }
 
 /**
@@ -114,6 +108,16 @@ export function nonUsSecListingVenue(ticker: string, exchange?: string): string
   return venue;
 }
 
+/**
+ * The key an issuer read is cached and deduplicated under: the ticker as given
+ * for a US listing or a symbol with no venue, SYMBOL:VENUE for a listing
+ * elsewhere, so SAN in Paris and SAN in New York never share an entry.
+ */
+export function secListingKey(ticker: string, exchange?: string): string {
+  const venue = nonUsSecListingVenue(ticker, exchange);
+  return venue ? `${parsePublicTickerKey(ticker).symbol}:${venue}` : normalize(ticker);
+}
+
 /**
  * The item codes in EDGAR's `items` field ("2.02,9.01"). EDGAR fills the same
  * field with other values for some forms, such as the order dates of a CT

package/src/utils/throttled-fetch.ts

@@ -7,6 +7,7 @@
  *   const data = await client.fetch("https://api.example.com/data");
  */
 
+import { abortError, signalWithTimeout } from "./async-deadline";
 import { httpFetch } from "./http-transport";
 
 const DEFAULT_REQUESTS_PER_MINUTE = 30;
@@ -17,9 +18,9 @@ const BACKOFF_BASE_MS = 1_000;
 export interface ThrottledFetchOptions {
   /** Max requests per minute per host. Default: 30 */
   requestsPerMinute?: number;
-  /** Max retries on 429 or 5xx. Default: 2 */
+  /** Max retries on 429, 5xx, timeouts and network errors. Default: 2 */
   maxRetries?: number;
-  /** Request timeout in ms. Default: 10000 */
+  /** Timeout of each attempt in ms, also when the caller passes a signal. Default: 10000 */
   timeoutMs?: number;
   /** Initial retry backoff in ms. Default: 1000 */
   backoffBaseMs?: number;
@@ -103,33 +104,63 @@ export function createThrottledFetch(
     return Math.max(retryAfterMs, backoff);
   }
 
-  function isRetryableFetchError(
-    error: unknown,
-    retryAbortError: boolean,
-  ): boolean {
+  // Retry rule: a timeout or network error is retried while retries remain,
+  // unless the caller's own signal has aborted. Once the caller aborted, the
+  // request ends with their abort reason: no further attempt and no backoff,
+  // including while waiting on the rate limit or a backoff. An AbortError that
+  // is not the caller's can only come from the attempt's timeout (or the
+  // transport giving up), so it counts as a timeout.
+  function isRetryableFetchError(error: unknown): boolean {
     const detail =
       error instanceof Error
         ? `${error.name} ${error.message} ${String((error as { code?: unknown }).code ?? "")}`
         : String(error);
-    return (
-      /TimeoutError|ECONNRESET|ECONNREFUSED|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|socket connection|socket hang up|fetch failed|network connection|connection closed/i.test(
-        detail,
-      ) ||
-      (retryAbortError && /AbortError/i.test(detail))
+    return /TimeoutError|AbortError|ECONNRESET|ECONNREFUSED|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|socket connection|socket hang up|fetch failed|network connection|connection closed/i.test(
+      detail,
     );
   }
 
+  function abortReason(signal: AbortSignal): unknown {
+    return signal.reason ?? abortError("The operation was aborted.");
+  }
+
+  function throwIfAborted(signal: AbortSignal | null | undefined): void {
+    if (signal?.aborted) throw abortReason(signal);
+  }
+
+  /** Waits `ms`, or rejects with the caller's abort reason as soon as the signal fires. */
+  function wait(ms: number, signal: AbortSignal | null | undefined): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      if (signal?.aborted) {
+        reject(abortReason(signal));
+        return;
+      }
+      const onAbort = () => {
+        clearTimeout(timer);
+        reject(abortReason(signal!));
+      };
+      const timer = setTimeout(() => {
+        signal?.removeEventListener("abort", onAbort);
+        resolve();
+      }, ms);
+      signal?.addEventListener("abort", onAbort, { once: true });
+    });
+  }
+
   async function executeRequest(
     url: string,
     init: RequestInit | undefined,
     retriesLeft: number,
   ): Promise<Response> {
+    const callerSignal = init?.signal;
+    throwIfAborted(callerSignal);
+
     const host = getHost(url);
 
     // Wait for rate limit window
     const delay = getDelayMs(host);
     if (delay > 0) {
-      await new Promise((resolve) => setTimeout(resolve, delay));
+      await wait(delay, callerSignal);
     }
 
     recordRequest(host);
@@ -140,17 +171,16 @@ export function createThrottledFetch(
         ...defaultHeaders,
         ...((init?.headers as Record<string, string>) ?? {}),
       },
-      signal: init?.signal ?? AbortSignal.timeout(timeoutMs),
+      signal: signalWithTimeout(callerSignal ?? undefined, timeoutMs),
     };
 
     let resp: Response;
     try {
       resp = await fetchTransport(url, mergedInit);
     } catch (error) {
-      if (retriesLeft > 0 && isRetryableFetchError(error, !init?.signal)) {
-        await new Promise((resolve) =>
-          setTimeout(resolve, getBackoffMs(retriesLeft)),
-        );
+      throwIfAborted(callerSignal);
+      if (retriesLeft > 0 && isRetryableFetchError(error)) {
+        await wait(getBackoffMs(retriesLeft), callerSignal);
         return executeRequest(url, init, retriesLeft - 1);
       }
       throw error;
@@ -158,11 +188,10 @@ export function createThrottledFetch(
 
     // Retry on 429 or 5xx
     if ((resp.status === 429 || resp.status >= 500) && retriesLeft > 0) {
-      await new Promise((resolve) =>
-        setTimeout(
-          resolve,
-          getBackoffMs(retriesLeft, resp.headers.get("retry-after")),
-        ),
+      throwIfAborted(callerSignal);
+      await wait(
+        getBackoffMs(retriesLeft, resp.headers.get("retry-after")),
+        callerSignal,
       );
       return executeRequest(url, init, retriesLeft - 1);
     }