gloomberb 0.16.1 → 0.16.3

package/src/utils/exchanges.ts

@@ -225,6 +225,78 @@ export const EXCHANGE_TIME_ZONES: Record<string, string> = {
   CCC: "UTC",
 };
 
+/**
+ * Venue names by canonical code, for output that names the listing a command
+ * resolved ("Euronext Paris (EPA)"). Codes whose name is the code itself
+ * (NASDAQ, BSE) are left out.
+ */
+const EXCHANGE_NAMES: Record<string, string> = {
+  NYSE: "New York Stock Exchange",
+  AMEX: "NYSE American",
+  ARCA: "NYSE Arca",
+  BATS: "Cboe BZX",
+  OTC: "OTC Markets",
+  JPX: "Tokyo Stock Exchange",
+  HKEX: "Hong Kong Stock Exchange",
+  LSE: "London Stock Exchange",
+  TSX: "Toronto Stock Exchange",
+  TSXV: "TSX Venture Exchange",
+  CSE: "Canadian Securities Exchange",
+  NEO: "Cboe Canada",
+  ASX: "Australian Securities Exchange",
+  CXA: "Cboe Australia",
+  NZX: "New Zealand Exchange",
+  SWX: "SIX Swiss Exchange",
+  XETRA: "Xetra",
+  FWB2: "Frankfurt Stock Exchange",
+  EPA: "Euronext Paris",
+  AMS: "Euronext Amsterdam",
+  BRU: "Euronext Brussels",
+  LIS: "Euronext Lisbon",
+  BIT: "Borsa Italiana",
+  MCE: "Bolsa de Madrid",
+  SFB: "Nasdaq Stockholm",
+  HEL: "Nasdaq Helsinki",
+  CPH: "Nasdaq Copenhagen",
+  OSL: "Euronext Oslo",
+  ICEX: "Nasdaq Iceland",
+  WSE: "Warsaw Stock Exchange",
+  PSE: "Prague Stock Exchange",
+  VIE: "Vienna Stock Exchange",
+  TWSE: "Taiwan Stock Exchange",
+  TPEX: "Taipei Exchange",
+  NSE: "National Stock Exchange of India",
+  BSE: "BSE India",
+  SSE: "Shanghai Stock Exchange",
+  SZSE: "Shenzhen Stock Exchange",
+  KRX: "Korea Exchange",
+  SGX: "Singapore Exchange",
+  BMV: "Mexican Stock Exchange",
+  BYMA: "Bolsas y Mercados Argentinos",
+  JSE: "Johannesburg Stock Exchange",
+  TASE: "Tel Aviv Stock Exchange",
+};
+
+const KNOWN_EXCHANGE_CODES: ReadonlySet<string> = new Set([
+  ...Object.keys(CANONICAL_EXCHANGE_ALIASES),
+  ...Object.values(CANONICAL_EXCHANGE_ALIASES),
+  ...Object.keys(EXCHANGE_TIME_ZONES),
+  ...Object.keys(EXCHANGE_NAMES),
+]);
+
+/** Whether a code (any spelling the alias table takes) names a venue the app knows. */
+export function isKnownExchangeCode(value?: string): boolean {
+  const normalized = normalizeExchange(value);
+  return !!normalized && KNOWN_EXCHANGE_CODES.has(normalized);
+}
+
+/** "Euronext Paris (EPA)" for a venue with a name, the canonical code otherwise. */
+export function exchangeLabel(value?: string): string {
+  const code = canonicalExchange(value);
+  const name = EXCHANGE_NAMES[code];
+  return name ? `${name} (${code})` : code;
+}
+
 export function normalizeSymbol(value: string): string {
   return value.trim().toUpperCase();
 }

package/src/utils/fire-and-forget.ts

@@ -0,0 +1,24 @@
+import { reportCrash } from "../telemetry/crash-reports";
+import { debugLog } from "./debug-log";
+import { RpcTimeoutError } from "./rpc-timeout-error";
+
+const log = debugLog.createLogger("desktop-rpc");
+
+/**
+ * Starts a desktop bridge call nobody awaits without leaving its rejection
+ * unhandled. A timed-out request is logged and reported once per session
+ * (never as a crash when the machine slept, see `reportCrash`) and swallowed:
+ * the next state change sends a fresh snapshot anyway. Any other error is
+ * rethrown, so a programming error still surfaces as an unhandled rejection.
+ *
+ * `onFailure` runs for every failure, so a caller that remembers what it
+ * already sent can forget it and send again.
+ */
+export function fireAndForget(request: Promise<unknown> | undefined, label: string, onFailure?: () => void): void {
+  request?.catch((error: unknown) => {
+    onFailure?.();
+    if (!(error instanceof RpcTimeoutError)) throw error;
+    log.warn(`${label} did not complete: ${error.message}`);
+    reportCrash(error, { kind: "unhandled-rejection" });
+  });
+}

package/src/utils/format.ts

@@ -130,6 +130,19 @@ export function formatNumber(value: number | undefined, decimals = 2): string {
   return getNumberFormatter(decimals).format(value);
 }
 
+/**
+ * A value to a count of significant digits, so a small ratio keeps its leading
+ * digits (0.0005664, not 0.0006) while a large one reads as a plain number
+ * (1,235). Decimals follow the rounded value, so 9.9996 reads 10.00.
+ */
+export function formatSignificant(value: number | undefined, digits = 4): string {
+  if (value == null || !Number.isFinite(value)) return formatNumber(undefined);
+  if (value === 0) return getNumberFormatter(0).format(0);
+  const rounded = Number(value.toPrecision(digits));
+  const decimals = Math.min(12, Math.max(0, digits - 1 - Math.floor(Math.log10(Math.abs(rounded)))));
+  return getNumberFormatter(decimals).format(rounded);
+}
+
 /** A percentile rank with its window: "73 pctl 1Y", "-- pctl 1Y" when unranked, "73 pctl" without a window. */
 export function formatPercentileRank(value: number | null | undefined, window?: string): string {
   const rank = value == null || !Number.isFinite(value) ? "--" : value.toFixed(0);

package/src/utils/fundamentals.ts

@@ -1,4 +1,4 @@
-import type { Fundamentals } from "../types/financials";
+import type { Fundamentals, TickerFinancials } from "../types/financials";
 
 export const RETRACTABLE_VALUATION_FIELDS = ["enterpriseValue", "enterpriseToRevenue"] as const;
 
@@ -13,3 +13,19 @@ export function redactUnavailableFundamentals(value: Fundamentals | undefined):
   for (const field of unavailableFields) delete result[field];
   return result;
 }
+
+/** A source's enterprise value, or undefined when it has none: banks and insurers come back as 0, which is a gap, not a value. */
+export function reportedEnterpriseValue(fundamentals: Pick<Fundamentals, "enterpriseValue"> | undefined): number | undefined {
+  const value = fundamentals?.enterpriseValue;
+  return typeof value === "number" && Number.isFinite(value) && value !== 0 ? value : undefined;
+}
+
+/**
+ * The currency of the trailing EPS, revenue, income and cash flows: the one the fundamentals declare, else the
+ * one the statements report in. Never the quote's, which a depositary receipt can differ from (USD quote, TWD books).
+ */
+export function fundamentalsCurrency(
+  financials: Pick<TickerFinancials, "fundamentals" | "financialCurrency"> | null | undefined,
+): string | undefined {
+  return financials?.fundamentals?.financialCurrency?.trim() || financials?.financialCurrency?.trim() || undefined;
+}

package/src/utils/price-earnings.ts

@@ -1,13 +1,80 @@
+import type { Fundamentals } from "../types/financials";
 import { formatNumber } from "./format";
 
 export const PRICE_EARNINGS_NOTICE = "N/M = not meaningful. Non-positive P/E values are excluded from ranking.";
 
+/** A multiple over a loss or zero base: there is no number to show, rank or export. */
+export const NOT_MEANINGFUL = "not-meaningful";
+export type PriceEarnings = number | typeof NOT_MEANINGFUL;
+
+function nonPositive(value: number | null | undefined): boolean {
+  return typeof value === "number" && Number.isFinite(value) && value <= 0;
+}
+
+/**
+ * A P/E checked against the earnings it divides by. Zero or negative earnings
+ * make it not meaningful whatever multiple a source served beside them: a
+ * source P/E priced at an older, profitable period stays positive after the
+ * trailing EPS turns into a loss (MSTR's 5.47 beside EPS -99.08). Unknown
+ * earnings leave the multiple as served.
+ */
+export function priceEarningsOnEarnings(
+  multiple: number | null | undefined,
+  earnings: number | null | undefined,
+): PriceEarnings | undefined {
+  if (nonPositive(earnings)) return NOT_MEANINGFUL;
+  return typeof multiple === "number" && Number.isFinite(multiple) ? multiple : undefined;
+}
+
 /** Negative earnings do not make a security cheaper than a profitable peer. */
-export function comparablePriceEarnings(value: number | null | undefined): number | null {
-  return value != null && Number.isFinite(value) && value > 0 ? value : null;
+export function comparablePriceEarnings(value: PriceEarnings | null | undefined): number | null {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : null;
 }
 
-export function formatPriceEarnings(value: number | null | undefined, precision = 1): string {
+/** P/E, forward P/E or PEG: N/M below zero, as the multiple says nothing there. */
+export function formatPriceEarnings(value: PriceEarnings | null | undefined, precision = 1): string {
+  if (value === NOT_MEANINGFUL) return "N/M";
   if (value == null || !Number.isFinite(value)) return "—";
   return value <= 0 ? "N/M" : formatNumber(value, precision);
 }
+
+type PriceEarningsField = "trailingPE" | "forwardPE" | "pegRatio";
+
+/**
+ * Why each earnings multiple of a fundamentals block is not meaningful, if it
+ * is not: a trailing or forward EPS at or below zero, or a multiple that is
+ * itself at or below zero. Forward P/E is judged on its own estimate only, so
+ * a trailing loss leaves a positive forward multiple alone.
+ */
+export function notMeaningfulMultiples(
+  fundamentals: Pick<Fundamentals, PriceEarningsField | "eps" | "forwardEps"> | undefined,
+): Partial<Record<PriceEarningsField, string>> {
+  const reasons: Partial<Record<PriceEarningsField, string>> = {};
+  if (!fundamentals) return reasons;
+  if (nonPositive(fundamentals.eps)) reasons.trailingPE = "trailing EPS is not positive";
+  else if (nonPositive(fundamentals.trailingPE)) reasons.trailingPE = "trailing earnings are not positive";
+  if (nonPositive(fundamentals.forwardEps)) reasons.forwardPE = "forward EPS is not positive";
+  else if (nonPositive(fundamentals.forwardPE)) reasons.forwardPE = "forward earnings are not positive";
+  if (nonPositive(fundamentals.pegRatio)) reasons.pegRatio = "P/E or expected growth is not positive";
+  return reasons;
+}
+
+/**
+ * The fundamentals block as JSON exports it: a multiple that is not meaningful
+ * reads null, with the reason under `notMeaningful`, never as a number.
+ */
+export function exportedFundamentals<T extends Fundamentals>(
+  fundamentals: T | undefined,
+): (Omit<T, PriceEarningsField> & Partial<Record<PriceEarningsField, number | null>> & {
+  notMeaningful?: Partial<Record<PriceEarningsField, string>>;
+}) | undefined {
+  if (!fundamentals) return fundamentals;
+  const reasons = notMeaningfulMultiples(fundamentals);
+  const fields = Object.keys(reasons) as PriceEarningsField[];
+  if (fields.length === 0) return fundamentals;
+  return {
+    ...fundamentals,
+    ...Object.fromEntries(fields.map((field) => [field, null])),
+    notMeaningful: reasons,
+  };
+}

package/src/utils/price-history-integrity.ts

@@ -27,13 +27,26 @@ function above(left: number, right: number): boolean {
   return left - right > 8 * Number.EPSILON * Math.max(Math.abs(left), Math.abs(right));
 }
 
-/** Missing OHLC fields are not contradictory: close-only histories remain usable. */
-export function pricePointIntegrity(point: PricePoint): PriceHistoryIntegrity | undefined {
+/**
+ * Each way a bar's prices contradict each other, as short codes such as
+ * `high<open` or `low>close`; empty when they agree. Missing OHLC fields are
+ * not contradictory: close-only histories remain usable.
+ */
+export function pricePointIntegrityFlags(point: PricePoint): string[] {
   const { open, high, low, close } = point;
-  const invalid = (isFiniteNumber(high) && isFiniteNumber(low) && above(low, high))
-    || [open, close].some((value) => isFiniteNumber(value)
-      && ((isFiniteNumber(high) && above(value, high)) || (isFiniteNumber(low) && above(low, value))));
-  if (!invalid) return undefined;
+  const flags: string[] = [];
+  for (const [name, value] of [["open", open], ["close", close]] as const) {
+    if (isFiniteNumber(value) && isFiniteNumber(high) && above(value, high)) flags.push(`high<${name}`);
+  }
+  for (const [name, value] of [["open", open], ["close", close]] as const) {
+    if (isFiniteNumber(value) && isFiniteNumber(low) && above(low, value)) flags.push(`low>${name}`);
+  }
+  if (isFiniteNumber(high) && isFiniteNumber(low) && above(low, high)) flags.push("low>high");
+  return flags;
+}
+
+export function pricePointIntegrity(point: PricePoint): PriceHistoryIntegrity | undefined {
+  if (pricePointIntegrityFlags(point).length === 0) return undefined;
   const date = new Date(point.date);
   return Object.freeze({
     reason: "inconsistent-ohlc",

package/src/utils/price-history.ts

@@ -1,5 +1,6 @@
 import type { PricePoint, TickerFinancials } from "../types/financials";
 import { canonicalExchange, resolveExchangeTimeZone } from "./exchanges";
+import { isRoundTheClockCoin } from "./crypto-pair";
 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";
@@ -10,9 +11,20 @@ const MAX_CURRENT_INTRADAY_HISTORY_LAG_MS = 18 * 60 * 60 * 1000;
 const MAX_SAME_SESSION_HISTORY_LAG_MS = 30 * 60 * 1000;
 const DELAYED_HISTORY_ALLOWANCE_MS = 15 * 60 * 1000;
 const DAY_MS = 24 * 60 * 60 * 1000;
+// A series that never closes must reach the present without a break: no hole
+// this long (or three bars, if larger) in the stretch before now that a
+// current window is read over.
+const ROUND_THE_CLOCK_RECENT_MS = 6 * 60 * 60 * 1000;
+const ROUND_THE_CLOCK_GAP_MS = 2 * 60 * 60 * 1000;
 
 interface PriceHistoryFreshnessOptions {
   exchange?: string;
+  /**
+   * The listing's symbol. A coin quoted in dollars (BTC-USD) trades around the
+   * clock whether or not the exchange says CCC; without the symbol a bare
+   * pair is read as a US listing and judged on the NYSE session.
+   */
+  symbol?: string;
   intervalMs?: number | null;
   session?: HistorySession;
 }
@@ -140,6 +152,29 @@ function normalizePriceHistoryUncached(points: PricePoint[]): PricePoint[] {
   return validPoints.length === points.length ? points : validPoints;
 }
 
+/**
+ * A round-the-clock series is current while its latest bar is within two bars
+ * and the publishing allowance of now, with no hole in the last hours. Cloud
+ * applies the same rule to the bars it serves.
+ */
+function isRoundTheClockHistoryBehind(
+  points: PricePoint[], latestTime: number, now: number, intervalMs: number | null,
+): boolean {
+  const allowedLag = intervalMs != null ? 2 * intervalMs + DELAYED_HISTORY_ALLOWANCE_MS : MAX_SAME_SESSION_HISTORY_LAG_MS;
+  if (now - latestTime > allowedLag) return true;
+  const maxGap = Math.max(3 * (intervalMs ?? 0), ROUND_THE_CLOCK_GAP_MS);
+  let later = latestTime;
+  for (let index = points.length - 1; index >= 0 && later >= now - ROUND_THE_CLOCK_RECENT_MS; index--) {
+    const point = points[index]!;
+    if (!hasFiniteClose(point)) continue;
+    const time = getPricePointTimestamp(point);
+    if (!(time < later)) continue;
+    if (later - time > maxGap) return true;
+    later = time;
+  }
+  return false;
+}
+
 export function isPriceHistoryStaleForCurrentWindow(
   points: PricePoint[],
   now = Date.now(),
@@ -149,7 +184,9 @@ export function isPriceHistoryStaleForCurrentWindow(
   const latest = normalized.findLast(hasFiniteClose);
   if (!latest) return false;
 
-  const session = options.session?.exchange === canonicalExchange(options.exchange)
+  const coin = isRoundTheClockCoin(options.symbol, options.exchange);
+  // A coin has no session to read its bars against.
+  const session = !coin && options.session?.exchange === canonicalExchange(options.exchange)
     ? options.session : undefined;
   const sessionInterval = session ? priceHistoryIntervalMs(session.interval) : null;
   const intervalMs = options.intervalMs ?? sessionInterval ?? inferredHistoryIntervalMs(normalized);
@@ -159,6 +196,9 @@ export function isPriceHistoryStaleForCurrentWindow(
 
   const latestTime = getPricePointTimestamp(latest);
   if (!Number.isFinite(latestTime)) return false;
+  // Before any exchange logic: a bare BTC-USD is not a US listing, and the
+  // always-open venue's own rule lets a bar up to two hours old stand.
+  if (coin) return isRoundTheClockHistoryBehind(normalized, latestTime, now, intervalMs);
   if (session && (options.intervalMs == null || options.intervalMs === sessionInterval)) {
     const regularStale = regularHistorySessionStaleness(latestTime, now, session);
     if (regularStale !== null) return regularStale;
@@ -171,15 +211,12 @@ export function isPriceHistoryStaleForCurrentWindow(
     intervalMs != null ? 2 * intervalMs + DELAYED_HISTORY_ALLOWANCE_MS : 0);
   if (age <= allowedLag) return false;
   const exchange = options.exchange || "NASDAQ";
-  if (
-    resolveExchangeTimeZone(exchange)
-    && isTimestampStaleForExchangeSession(latestTime, exchange, now)
-  ) {
-    return true;
-  }
   // Bars that reach the close of the venue's latest session stay current
   // once it has closed, so a closed market keeps its last session until the
   // next one opens. A copy taken earlier in that session is still behind.
+  // Asked before the quote rule below, which reads any US bar dated before
+  // today as behind from 04:00 ET: right for a last price, wrong for bars
+  // waiting for the next session's first one.
   const regularSession = isRegularSessionTime(exchange, now);
   if (regularSession !== null) {
     const open = latestRegularSessionOpen(exchange, now);
@@ -190,6 +227,12 @@ export function isPriceHistoryStaleForCurrentWindow(
       if (regularSession && close < open && latestTime < open && now - open <= allowedLag) return false;
     }
   }
+  if (
+    resolveExchangeTimeZone(exchange)
+    && isTimestampStaleForExchangeSession(latestTime, exchange, now)
+  ) {
+    return true;
+  }
   const hasExchangeSession = Boolean(resolveExchangeTimeZone(exchange));
   if (age <= MAX_CURRENT_INTRADAY_HISTORY_LAG_MS) return hasExchangeSession;
   return !hasExchangeSession;
@@ -209,7 +252,7 @@ const BEHIND_RECHECK_BACKOFF = 4;
 // re-check fails, answers nothing usable, or is rejected.
 const UNSETTLED_RETRY_MS = 5 * 60 * 1000;
 
-interface CalendarHistoryFetchOptions extends Pick<PriceHistoryFreshnessOptions, "exchange" | "intervalMs"> {
+interface CalendarHistoryFetchOptions extends Pick<PriceHistoryFreshnessOptions, "exchange" | "intervalMs" | "symbol"> {
   /**
    * The latest check of this request, including a failed or empty one; the
    * fetch of the copy itself when absent.
@@ -243,12 +286,13 @@ function barDate(time: number, timeZone: string): string {
  * The venue date of the latest bar, read as calendarHistoryFetchState reads
  * it, so copies whose sources label a session differently compare equal.
  */
-export function calendarHistoryLastBarDate(points: PricePoint[], exchange?: string): string | null {
+export function calendarHistoryLastBarDate(points: PricePoint[], exchange?: string, symbol?: string): string | null {
   const latest = normalizePriceHistory(points).findLast(hasFiniteClose);
   if (!latest) return null;
   const time = getPricePointTimestamp(latest);
   if (!Number.isFinite(time)) return null;
-  // Bare symbols resolve to their US listing at the sources.
+  // Bare symbols resolve to their US listing at the sources, a coin to its UTC date.
+  if (isRoundTheClockCoin(symbol, exchange)) return barDate(time, "UTC");
   return barDate(time, sessionCalendarTimeZone(canonicalExchange(exchange) || "NYSE") ?? "UTC");
 }
 
@@ -270,7 +314,7 @@ function isBarBeforeSession(latestTime: number, session: string, intervalMs: num
  * 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
  * after it but without its bar is behind only where the venue's closures are
- * published (US venues, JPX): elsewhere, and for a bare symbol whose venue is
+ * published (hasPublishedSessionCalendar): elsewhere, and for a bare symbol whose venue is
  * unknown, a local holiday would read as a missing session. A copy of a 24/7
  * series goes out of date within the hour.
  */
@@ -285,7 +329,7 @@ export function calendarHistoryFetchState(
   const intervalMs = options.intervalMs ?? inferredHistoryIntervalMs(normalized);
   if (intervalMs == null || intervalMs < DAY_MS) return "current";
   const exchange = canonicalExchange(options.exchange);
-  if (exchange === "CCC") {
+  if (isRoundTheClockCoin(options.symbol, options.exchange)) {
     return now - fetchedAt > CRYPTO_BAR_MAX_AGE_MS
       ? unsettledState(fetchedAt + CRYPTO_BAR_MAX_AGE_MS, options.checkedAt, now) : "current";
   }
@@ -309,12 +353,13 @@ export function calendarHistoryFetchState(
 export function reachesLatestSettledSession(
   points: PricePoint[],
   now = Date.now(),
-  options: Pick<PriceHistoryFreshnessOptions, "exchange" | "intervalMs"> = {},
+  options: Pick<PriceHistoryFreshnessOptions, "exchange" | "intervalMs" | "symbol"> = {},
 ): boolean {
   const normalized = normalizePriceHistory(points);
   const latest = normalized.findLast(hasFiniteClose);
   const latestTime = latest ? getPricePointTimestamp(latest) : Number.NaN;
   if (!Number.isFinite(latestTime)) return false;
+  if (isRoundTheClockCoin(options.symbol, options.exchange)) return false;
   // Bare symbols resolve to their US listing at the sources.
   const session = latestRegularSessionClose(canonicalExchange(options.exchange) || "NYSE", now - SESSION_BAR_SETTLE_MS);
   if (!session) return false;

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

@@ -0,0 +1,27 @@
+/** A timeout this many times past its limit means the machine slept through it. */
+const SLEEP_TIMEOUT_FACTOR = 5;
+
+/**
+ * A call to the desktop's Bun process that did not complete in time: the
+ * request timer ran out, or the bridge socket never opened. `name` stays
+ * "Error", so crash reports and filters see the same type as before.
+ */
+export class RpcTimeoutError extends Error {
+  readonly elapsedMs: number;
+  readonly limitMs: number;
+
+  constructor(message: string, { elapsedMs, limitMs, cause }: { elapsedMs: number; limitMs: number; cause?: unknown }) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.elapsedMs = elapsedMs;
+    this.limitMs = limitMs;
+  }
+}
+
+/**
+ * A timeout whose timer fired long after its limit. A laptop that sleeps
+ * suspends the page, and on wake the timer runs once for a request the Bun
+ * process already lost. Nothing the user did failed, so it is not a crash.
+ */
+export function isSleepRpcTimeout(error: unknown): boolean {
+  return error instanceof RpcTimeoutError && error.elapsedMs > SLEEP_TIMEOUT_FACTOR * error.limitMs;
+}

package/src/utils/sec.ts

@@ -1,5 +1,5 @@
 import type { TickerRecord } from "../types/ticker";
-import { canonicalExchange, US_LISTING_EXCHANGES } from "./exchanges";
+import { canonicalExchange, parsePublicTickerKey, US_LISTING_EXCHANGES } from "./exchanges";
 
 /** Canonical US equity venues: the listing exchanges plus other lit and OTC venues. */
 const US_EQUITY_EXCHANGES = new Set([
@@ -102,6 +102,18 @@ export function isKnownNonUsEquityTicker(ticker: TickerRecord | null | undefined
     .some((exchange) => normalize(exchange).length > 0);
 }
 
+/**
+ * The venue an SEC issuer lookup has to respect: a listing outside the US,
+ * whose bare symbol the SEC may know as another company (SAN is Banco
+ * Santander in New York, Sanofi in Paris). Null for a US venue, a routing
+ * destination or no venue at all, which look the symbol up as a US ticker.
+ */
+export function nonUsSecListingVenue(ticker: string, exchange?: string): string | null {
+  const venue = parsePublicTickerKey(ticker).exchange ?? canonicalExchange(exchange);
+  if (!venue || ROUTING_EXCHANGES.has(venue) || isUsExchange(venue)) return null;
+  return venue;
+}
+
 /**
  * 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/utc-time.ts

@@ -0,0 +1,79 @@
+/**
+ * Times in CLI and report text print in UTC with the zone named, so a value
+ * copied out of a report means the same thing on every machine and in every
+ * time zone. JSON keeps the raw ISO or epoch values.
+ */
+
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+/** An ISO date and time with an explicit zone; one without a zone cannot be placed in UTC. */
+const ZONED_ISO_DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})$/i;
+// Epoch milliseconds between 2001 and 2286, so counts and prices are never read as times.
+const EPOCH_MS_MIN = 1e12;
+const EPOCH_MS_MAX = 1e13;
+
+export interface ReportTime {
+  /** Epoch milliseconds; a date-only value sits at UTC midnight. */
+  time: number;
+  /** The value named a calendar date, not an instant. */
+  dateOnly: boolean;
+}
+
+export function isEpochMilliseconds(value: number): boolean {
+  return Number.isFinite(value) && value >= EPOCH_MS_MIN && value < EPOCH_MS_MAX;
+}
+
+export function isZonedIsoDateTime(value: string): boolean {
+  return ZONED_ISO_DATE_TIME.test(value);
+}
+
+/**
+ * Reads a Date, epoch milliseconds, an ISO date or a zoned ISO date and time.
+ * A date and time without a zone, or anything else, is not a report time.
+ */
+export function parseReportTime(value: unknown): ReportTime | null {
+  if (value instanceof Date) {
+    const time = value.getTime();
+    return Number.isFinite(time) ? { time, dateOnly: false } : null;
+  }
+  if (typeof value === "number") return isEpochMilliseconds(value) ? { time: value, dateOnly: false } : null;
+  if (typeof value !== "string") return null;
+  const text = value.trim();
+  if (DATE_ONLY.test(text)) {
+    const time = Date.parse(`${text}T00:00:00Z`);
+    return Number.isFinite(time) ? { time, dateOnly: true } : null;
+  }
+  if (!ZONED_ISO_DATE_TIME.test(text)) return null;
+  const time = Date.parse(text);
+  return Number.isFinite(time) ? { time, dateOnly: false } : null;
+}
+
+/**
+ * `2026-10-09 00:08 UTC`. Only an explicitly date-only value prints
+ * as `2026-10-09`; midnight instants keep their time and zone.
+ */
+export function formatUtcTime(value: ReportTime | Date | number | string): string {
+  const parsed = typeof value === "object" && !(value instanceof Date) ? value : parseReportTime(value);
+  if (!parsed) return typeof value === "string" ? value : "";
+  const iso = new Date(parsed.time).toISOString();
+  if (parsed.dateOnly) return iso.slice(0, 10);
+  return `${iso.slice(0, 16).replace("T", " ")} UTC`;
+}
+
+/** The newest of some report times, as given, so a loader can declare its as-of from the rows it means. */
+export function newestReportTime<T>(values: Iterable<T>): T | null {
+  let best: { value: T; time: number } | null = null;
+  for (const value of values) {
+    const parsed = parseReportTime(value);
+    if (parsed && (!best || parsed.time > best.time)) best = { value, time: parsed.time };
+  }
+  return best?.value ?? null;
+}
+
+export function oldestReportTime<T>(values: Iterable<T>): T | null {
+  let best: { value: T; time: number } | null = null;
+  for (const value of values) {
+    const parsed = parseReportTime(value);
+    if (parsed && (!best || parsed.time < best.time)) best = { value, time: parsed.time };
+  }
+  return best?.value ?? null;
+}