gloomberb 0.16.3 → 0.16.4

package/src/sources/gloomberb-cloud/index.ts

@@ -39,13 +39,13 @@ import { normalizeNewsFeed } from "../../news/news-model";
 import { resolveCurrencyUnit } from "../../utils/currency-units";
 import { canonicalExchange, canonicalTickerKey, parsePublicTickerKey } from "../../utils/exchanges";
 import { normalizePriceHistory, priceHistoryIntervalMs, reachesLatestSettledSession } from "../../utils/price-history";
-import { createProviderMiss } from "../provider-errors";
+import { createProviderMiss, providerMissReason } from "../provider-errors";
 import { assertSecRegistrantMatches } from "../sec-registrant";
 import { nonUsSecListingVenue } from "../../utils/sec";
 import { publicListingTarget } from "../listing-target";
 import { canonicalHistoryInterval, HistoryRetentionError, parseHistoryRecoveryCandidate, parseHistoryRetention, type HistoryRetention } from "../history-retention";
 import { getRouterEntityKey } from "../provider-router/cache";
-import { tickerHasListingSuffix } from "../listing-symbols";
+import { hongKongListingCode, tickerHasListingSuffix } from "../listing-symbols";
 import { parseSecAcceptanceTime } from "../sec-edgar/acceptance-time";
 import { hasMalformedIntradayHistory } from "../../time-series/history-quality";
 import {
@@ -57,6 +57,7 @@ import {
   formatCloudDateTime,
   isEmptyCloudStatus,
   mapBatchError,
+  NOT_FOUND_REASON,
   mapCloudFinancials,
   mapOptionsChain,
   mapPricePoint,
@@ -124,7 +125,7 @@ async function withCloudFallback<T>(load: () => Promise<T>, message: string): Pr
     return await load();
   } catch (error) {
     if (isCloudProviderMiss(error)) {
-      throw createProviderMiss(message);
+      throw createProviderMiss(message, providerMissReason(error));
     }
     throw error;
   }
@@ -237,7 +238,7 @@ function cloudHistoryResolution(interval: string): ManualChartResolution | null
 }
 
 function quoteTargetKey(symbol: string, exchange?: string): string {
-  const target = publicListingTarget(symbol, exchange);
+  const target = cloudInstrumentTarget(symbol, exchange);
   const base = target.exchange && tickerHasListingSuffix(target.symbol) ? target.symbol.slice(0, target.symbol.indexOf(".")) : target.symbol;
   return canonicalTickerKey(base, target.exchange);
 }
@@ -251,7 +252,14 @@ function cloudResponseTargetKey(key: string, requested: Set<string>): string | u
     ? symbol : undefined;
 }
 
-const cloudInstrumentTarget = publicListingTarget;
+/**
+ * The listing as Gloom Cloud knows it. A Hong Kong code goes out with its four
+ * digits: Cloud has no 700 or 5 on HKEX, only 0700 and 0005.
+ */
+function cloudInstrumentTarget(symbol: string, exchange?: string) {
+  const target = publicListingTarget(symbol, exchange);
+  return target.exchange ? { ...target, symbol: hongKongListingCode(target.symbol, target.exchange) } : target;
+}
 
 function cloudHistoryRecovery(
   context: MarketDataRequestContext | undefined,
@@ -323,7 +331,7 @@ function unwrapRequiredCloudResponse<T>(response: CloudMarketResponse<T>, messag
     return response.data;
   }
   if (isEmptyCloudStatus(response.status)) {
-    throw createProviderMiss(response.reasonCode ?? message);
+    throw createProviderMiss(response.reasonCode ?? message, response.message, { notFound: response.reasonCode === NOT_FOUND_REASON });
   }
   throw new Error(response.reasonCode ?? message);
 }
@@ -404,13 +412,14 @@ export class GloomberbCloudProvider implements AssetDataProvider {
     return withCloudFallback(
       async () => {
         const response = await apiClient.getCloudQuote(target.symbol, target.exchange);
-        if (isStaleCloudResponse(response)) {
-          throw createProviderMiss(`Cloud quotes are stale for ${ticker}`);
-        }
-        return retainRequestedQuoteSymbol(mapQuote(
+        const quote = retainRequestedQuoteSymbol(mapQuote(
           unwrapRequiredCloudResponse(response, `Cloud quotes are unavailable for ${ticker}`),
           response.providerMeta,
         ), ticker);
+        // A stale answer is the last price the service has. It stays flagged, so
+        // no freshness check passes it and only a request with no current quote
+        // from any source falls back to it.
+        return isStaleCloudResponse(response) ? { ...quote, stale: true } : quote;
       },
       `Cloud quotes are unavailable for ${ticker}`,
     );

package/src/sources/gloomberb-cloud/normalizers.ts

@@ -306,6 +306,9 @@ export function mapOptionsChain(
   };
 }
 
+/** The reason code Gloom Cloud gives an empty answer for a symbol no listing carries. */
+export const NOT_FOUND_REASON = "NOT_FOUND";
+
 export function isEmptyCloudStatus(
   status: CloudMarketResponse<unknown>["status"],
 ): boolean {
@@ -317,7 +320,7 @@ export function mapBatchError<T>(
   fallbackMessage: string,
 ): Error {
   if (isEmptyCloudStatus(item.status)) {
-    return createProviderMiss(item.reasonCode ?? fallbackMessage);
+    return createProviderMiss(item.reasonCode ?? fallbackMessage, item.message, { notFound: item.reasonCode === NOT_FOUND_REASON });
   }
   return new Error(item.reasonCode ?? fallbackMessage);
 }

package/src/sources/listing-symbols.ts

@@ -23,7 +23,7 @@ const EXCHANGE_SUFFIX_MAP: Record<string, string> = {
   TASE: ".TA",
   JSE: ".JO",
   BVMF: ".SA", MEXI: ".MX", BYMA: ".BA", BCS: ".SN",
-  TADAWUL: ".SAU", QSE: ".QA", DFM: ".AE",
+  TADAWUL: ".SR", QE: ".QA", DFM: ".AE",
 };
 
 const EXCHANGE_FALLBACKS: Record<string, string[]> = {
@@ -143,11 +143,17 @@ export function listingSuffixExchange(ticker: string): string | undefined {
   return venues.size === 1 ? [...venues][0] : undefined;
 }
 
+/**
+ * A Hong Kong listing's four-digit code. Brokers such as Interactive Brokers
+ * report Tencent as 700 and HSBC as 5; the exchange and market data know
+ * them as 0700 and 0005.
+ */
+export function hongKongListingCode(ticker: string, exchange: string): string {
+  return isHongKongExchange(exchange) && /^\d+$/.test(ticker) ? ticker.padStart(4, "0") : ticker;
+}
+
 function normalizeListingTicker(ticker: string, exchange: string): string {
-  if (isHongKongExchange(exchange) && /^\d+$/.test(ticker)) {
-    return ticker.padStart(4, "0");
-  }
-  return ticker.replace(/ /g, "-");
+  return hongKongListingCode(ticker, exchange).replace(/ /g, "-");
 }
 
 function isHongKongExchange(exchange: string): boolean {

package/src/sources/provider-errors.ts

@@ -1,17 +1,45 @@
 const PROVIDER_MISS_BRAND = Symbol("provider-miss");
 const EXPECTED_PROVIDER_MISS = /No data found|symbol may be delisted|"code":"Not Found"|No history for /i;
 
+const MAX_REASON_LENGTH = 200;
+// Whole ANSI sequences go first, so their printable tail does not outlive the escape byte.
+const ANSI_SEQUENCE = /\u001b(?:\[[0-9;?]*[ -/]*[@-~]|\][^\u0007\u001b]*(?:\u0007|\u001b\\)?)/g;
+const LINE_BREAKS = /[\r\n\t\v\f\u0085\u2028\u2029]+/g;
+// Remaining controls, and the bidirectional overrides that can reorder text in a terminal.
+const CONTROL_CHARACTERS = /[\p{Cc}\u200e\u200f\u202a-\u202e\u2066-\u2069]/gu;
+
+/**
+ * A reason a data service wrote for an empty answer, made safe to show: one
+ * line, no control characters, at most 200 characters. Anything that is not a
+ * non-empty string has no reason.
+ */
+export function cleanProviderReason(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const line = value.replace(ANSI_SEQUENCE, "").replace(LINE_BREAKS, " ").replace(CONTROL_CHARACTERS, "").replace(/\s+/g, " ").trim();
+  if (!line) return undefined;
+  const characters = Array.from(line);
+  return characters.length > MAX_REASON_LENGTH
+    ? `${characters.slice(0, MAX_REASON_LENGTH - 1).join("").trimEnd()}…`
+    : line;
+}
+
 export class ProviderMissError extends Error {
   readonly [PROVIDER_MISS_BRAND] = true;
+  /** Why the service has nothing, in its own words, when it said. */
+  readonly reason?: string;
+  /** The service found no listing for the symbol: it is not a ticker, which differs from a ticker it has no data for. */
+  readonly notFound: boolean;
 
-  constructor(message = "Provider could not satisfy request") {
+  constructor(message = "Provider could not satisfy request", reason?: unknown, options: { notFound?: boolean } = {}) {
     super(message);
     this.name = "ProviderMissError";
+    this.reason = cleanProviderReason(reason);
+    this.notFound = options.notFound === true;
   }
 }
 
-export function createProviderMiss(message?: string): ProviderMissError {
-  return new ProviderMissError(message);
+export function createProviderMiss(message?: string, reason?: unknown, options?: { notFound?: boolean }): ProviderMissError {
+  return new ProviderMissError(message, reason, options);
 }
 
 function isProviderMiss(error: unknown): error is ProviderMissError {
@@ -19,6 +47,63 @@ function isProviderMiss(error: unknown): error is ProviderMissError {
     || (!!error && typeof error === "object" && PROVIDER_MISS_BRAND in error);
 }
 
+/** The reason a provider gave for a miss, or undefined when it gave none. */
+export function providerMissReason(error: unknown): string | undefined {
+  return isProviderMiss(error) ? error.reason : undefined;
+}
+
+/** Collects the latest reason across the providers of one request. */
+export interface ProviderMissNote {
+  reason?: string;
+  /** True while every provider that failed said it found no listing; one that failed another way (a timeout) clears it. */
+  notFound?: boolean;
+}
+
+export function noteProviderMiss(note: ProviderMissNote | undefined, error: unknown): void {
+  if (!note) return;
+  const reason = providerMissReason(error);
+  if (reason) note.reason = reason;
+  note.notFound = note.notFound !== false && isProviderMiss(error) && error.notFound === true;
+}
+
+/** A provider answered with data the router could not use: whatever else is missing, the symbol exists. */
+export function noteProviderAnswer(note: ProviderMissNote | undefined): void {
+  if (note) note.notFound = false;
+}
+
+const NOT_A_TICKER = /^Not a ticker: (.+)\.$/;
+
+/** "Not a ticker: APPLE.", what a request for a symbol no listing carries ends in. */
+function notATickerMessage(symbol: string): string {
+  return `Not a ticker: ${symbol}.`;
+}
+
+/** The symbol of a "Not a ticker: APPLE." message, or null for any other text. */
+export function notATickerSymbol(message: string): string | null {
+  return NOT_A_TICKER.exec(message.split("\n")[0] ?? "")?.[1] ?? null;
+}
+
+/**
+ * Whether a message is the router's answer that no source serves a symbol: "No history provider
+ * available for 2222", or "Not a ticker: 2222." when the service found no listing for it.
+ * A timeout or any other failure is not.
+ */
+export function isNoProviderMessage(message: string): boolean {
+  return /\bprovider available for\b/i.test(message) || notATickerSymbol(message) !== null;
+}
+
+/**
+ * The router's final error when no provider answered. A reason a provider gave
+ * replaces the generic wording, and so does the service's answer that no
+ * listing exists for `symbol` ("Not a ticker"); a timeout or any other failure
+ * keeps the generic message.
+ */
+export function noProviderError(message: string, note: ProviderMissNote | undefined, symbol?: string): Error {
+  if (note?.reason) return createProviderMiss(note.reason, note.reason);
+  if (note?.notFound === true && symbol) return createProviderMiss(notATickerMessage(symbol), undefined, { notFound: true });
+  return new Error(message);
+}
+
 export function shouldLogProviderError(error: unknown): boolean {
   if (isProviderMiss(error)) return false;
   const message = error instanceof Error ? error.message : String(error);

package/src/sources/provider-router/cached-routes.ts

@@ -4,7 +4,7 @@ import type { CachedAssetArgs, CachedAssetMethod, CachedAssetValue, DataProvider
 import type { AnalystResearchData, CorporateActionsData, HolderData } from "../../types/financials";
 import { canonicalExchange } from "../../utils/exchanges";
 import { nonUsSecListingVenue } from "../../utils/sec";
-import { shouldLogProviderError } from "../provider-errors";
+import { noProviderError, noteProviderMiss, shouldLogProviderError, type ProviderMissNote } from "../provider-errors";
 import { hasBrokerContext, withBrokerTimeout } from "./brokers";
 import { publicListingExchange } from "../listing-target";
 import { buildVariantKey, compactUrl, listCachedResources, resolveCachePolicy, type ProviderRouterCachePolicyKey } from "./cache";
@@ -18,6 +18,8 @@ interface Route {
   variants: string[];
   request: (provider: DataProvider, force: boolean) => Promise<unknown> | undefined;
   error: string;
+  /** The symbol the request is for, so an answer that no listing exists can name it. */
+  symbol?: string;
   rank?: (value: any, fetchedAt?: number) => number;
   acceptCached?: (value: any) => boolean;
   decode?: (value: any) => unknown;
@@ -111,6 +113,7 @@ export class ProviderRouterCachedRoutes {
         let best: CachedValue<unknown> | null = null;
         let bestRank = -1;
         let lastError: unknown;
+        const misses: ProviderMissNote = {};
         for (const provider of providers) {
           try {
             const request = route.request(provider, force);
@@ -123,6 +126,7 @@ export class ProviderRouterCachedRoutes {
             if (rank > bestRank) { best = result; bestRank = rank; }
           } catch (error) {
             lastError = error;
+            noteProviderMiss(misses, error);
             if (shouldLogProviderError(error)) this.deps.logProviderError(`${provider.id} failed: ${error}`);
           }
         }
@@ -133,7 +137,7 @@ export class ProviderRouterCachedRoutes {
           const policy = resolveCachePolicy(undefined, route.policy);
           return { value: route.empty(), fetchedAt, staleAt: fetchedAt + policy.staleMs, expiresAt: fetchedAt + policy.expireMs, source: "" };
         }
-        throw new Error(route.error);
+        throw noProviderError(route.error, misses, route.symbol);
       },
     });
     this.queries.set(key, query);
@@ -175,8 +179,8 @@ export class ProviderRouterCachedRoutes {
       && !hasBrokerContext(instrumentContext) && !instrumentContext?.instrument) {
       exchange = publicListingExchange(ticker, exchange);
     }
-    const tickerRoute = (kind: string, policy: ProviderRouterCachePolicyKey): Pick<Route, "kind" | "policy" | "entityKey" | "variants"> => ({
-      kind, policy, entityKey: this.deps.getEntityKey(ticker, instrumentContext?.instrument),
+    const tickerRoute = (kind: string, policy: ProviderRouterCachePolicyKey): Pick<Route, "kind" | "policy" | "entityKey" | "variants" | "symbol"> => ({
+      kind, policy, symbol: ticker, entityKey: this.deps.getEntityKey(ticker, instrumentContext?.instrument),
       variants: this.deps.getTickerVariantCandidates(exchange),
     });
     switch (method) {

package/src/sources/provider-router/financial-routes.ts

@@ -15,6 +15,7 @@ import {
   selectCachedResource,
   sortCachedRecords,
 } from "./cache";
+import { noProviderError, type ProviderMissNote } from "../provider-errors";
 import { withBrokerTimeout } from "./brokers";
 import {
   hasMeaningfulProfile,
@@ -31,7 +32,7 @@ import {
   type CachedFinancialsReadOptions,
   type CachedFinancialsSelection,
 } from "./financials";
-import type { ProviderRouterPrimaryRoutes } from "./primary";
+import type { ProviderQuoteMissNote, ProviderRouterPrimaryRoutes } from "./primary";
 import type { ProviderRouterCoreDeps, SourceResult } from "./route-types";
 
 export interface ProviderRouterFinancialRouteDeps extends Pick<
@@ -178,13 +179,14 @@ export class ProviderRouterFinancialRoutes {
     }
 
     const brokerResult = await withBrokerTimeout(this.deps.primaryRoutes.fetchBrokerFinancials(ticker, exchange, context));
-    const fallback = await this.deps.primaryRoutes.fetchProviderFinancials(ticker, exchange, context);
+    const misses: ProviderMissNote = {};
+    const fallback = await this.deps.primaryRoutes.fetchProviderFinancials(ticker, exchange, context, misses);
     const merged = mergeFinancials(brokerResult?.value ?? null, fallback?.value ?? null);
     if (isOptionTicker && !merged?.quote) {
       return quoteOnlyFinancials(merged);
     }
     if (!merged) {
-      throw new Error(`No provider available for ${ticker}`);
+      throw noProviderError(`No provider available for ${ticker}`, misses, ticker);
     }
     return merged;
   }
@@ -221,12 +223,16 @@ export class ProviderRouterFinancialRoutes {
       );
     }
 
-    const providerQuote = await this.deps.primaryRoutes.fetchProviderQuote(ticker, exchange, context);
+    const misses: ProviderQuoteMissNote = {};
+    const providerQuote = await this.deps.primaryRoutes.fetchProviderQuote(ticker, exchange, context, misses);
     if (providerQuote) {
       return providerQuote.value;
     }
     if (cached) return cached.value;
-    throw new Error(`No quote provider available for ${ticker}`);
+    // No source has a current quote: the last price one answered with, flagged
+    // stale and dated by its own time, rather than none.
+    if (misses.lastKnownQuote) return misses.lastKnownQuote;
+    throw noProviderError(`No quote provider available for ${ticker}`, misses, ticker);
   }
 
   private async getProviderReferenceQuote(

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

@@ -4,15 +4,15 @@ import { hasLikelyQuoteUnitMismatch } from "../../utils/currency-units";
 import { coalesceFinancialPeriodAliases, mergeFinancialStatementRows } from "../../utils/financial-statements";
 import { normalizePriceHistory, normalizeTickerFinancialsPriceHistory } from "../../utils/price-history";
 import { redactUnavailableFundamentals, RETRACTABLE_VALUATION_FIELDS } from "../../utils/fundamentals";
-import { isExtendedHoursExchange, isQuoteStaleForCurrentSession } from "../../market-data/quotes/freshness";
+import { hasValidQuoteObservationTime, isExtendedHoursExchange, isQuoteStaleForCurrentSession } from "../../market-data/quotes/freshness";
 import { mergeQuoteMetadata, quoteMetadataFromQuote, quoteMetadataMatchesTarget } from "../../market-data/quotes/metadata";
-import { parsePublicTickerKey } from "../../utils/exchanges";
+import { canonicalExchange, parsePublicTickerKey } from "../../utils/exchanges";
 import {
   activeUsMarketSession,
   delayedFeedLagMs,
   isMiddayBreakPrint,
   isRegularSessionTime,
-  isUsPostSessionPrint,
+  isUsExtendedHoursSessionPrint,
   isUsPriorSessionPremarketQuote,
   isUsRegularCloseQuoteInPostSession,
   latestRegularSessionOpen,
@@ -147,19 +147,27 @@ const OPENING_AUCTION_MS = 15 * 60_000;
  * - the quote is delayed. The service bounds a delayed quote's feed age itself
  *   but not a real-time one's, so real-time quotes keep the age bound;
  * - it reports the regular session, the venue's session is in progress as
- *   the delayed feed shows it, and the trade belongs to that session; or it
- *   reports a US after-hours price, the after-hours session is in progress and
- *   the trade belongs to it.
+ *   the delayed feed shows it, and the trade belongs to that session; a
+ *   currency pair's session is the service's to judge; or
+ * - it reports a US extended-hours session and the trade is no older than
+ *   the regular session that session extends: after the close, today's
+ *   regular session or its after-hours; before the open, the previous
+ *   regular session or anything since. Whether the quote carries the
+ *   session's price is the freshness rule's call, made before this one.
  * The answer says nothing about how often a listing trades, so a liquid
  * listing the service wrongly vouches for is accepted too. The service's own
  * bound for liquid listings, about twenty minutes, is tighter than this one.
  */
 function isVouchedCurrentByService(quote: Quote, exchange: string | undefined, now: number): boolean {
   if (quote.providerId !== "gloomberb-cloud" || quote.stale !== false || quote.dataSource !== "delayed") return false;
-  if (quote.marketState === "POST") {
-    return finitePositiveNumber(quote.postMarketPrice) && isUsPostSessionPrint(quote.lastUpdated, exchange, now);
+  if (quote.marketState === "PRE" || quote.marketState === "POST") {
+    return isUsExtendedHoursSessionPrint(quote.lastUpdated, exchange, quote.marketState, now);
   }
   if (quote.marketState !== "REGULAR") return false;
+  // A currency pair trades around the clock through the week, and the service
+  // measures its silence against how often that pair prints: a pegged or
+  // exotic pair such as SAR=X goes hours without a print while its feed is fine.
+  if (canonicalExchange(exchange) === "CCY") return true;
   const feedTime = now - delayedFeedLagMs(exchange);
   if (isRegularSessionTime(exchange, feedTime) !== true) return false;
   const open = latestRegularSessionOpen(exchange, feedTime);
@@ -221,21 +229,40 @@ export function isProviderQuoteUsableForCurrentSession(
   const normalized = quoteWithFreshnessExchange(quote, exchange);
   if (isQuoteStaleForCurrentSession(normalized)) return false;
   if (isActiveProviderQuoteTooOld(normalized, Date.now(), options.recentAnswer === true)) return false;
+  return hasQuotedPrice(normalized);
+}
+
+function hasQuotedPrice(quote: Quote): boolean {
   // Futures may trade or settle at zero or negative prices. Require explicit
   // source type metadata; an alias alone cannot establish the price domain.
-  const futures = ["FUT", "FUTURE", "FUTURES"].includes(normalized.instrumentType?.trim().toUpperCase() ?? "");
+  const futures = ["FUT", "FUTURE", "FUTURES"].includes(quote.instrumentType?.trim().toUpperCase() ?? "");
   return [
-    normalized.price,
-    normalized.preMarketPrice,
-    normalized.postMarketPrice,
-    normalized.bid,
-    normalized.ask,
-    normalized.mark,
+    quote.price,
+    quote.preMarketPrice,
+    quote.postMarketPrice,
+    quote.bid,
+    quote.ask,
+    quote.mark,
   ].some((value) => futures
     ? typeof value === "number" && Number.isFinite(value)
     : finitePositiveNumber(value));
 }
 
+/**
+ * A source's answer for the target that is priced and dated but not current
+ * for its session, flagged stale: the last price there is, for when no source
+ * has a current one. It keeps its own observation time, which dates it
+ * wherever it is shown, and the flag keeps it out of anything that needs a
+ * current price. Null for an answer that names another listing, carries no
+ * price or no valid time.
+ */
+export function lastKnownProviderQuote(quote: Quote | null | undefined, exchange?: string, symbol?: string): Quote | null {
+  if (!providerQuoteMatchesTarget(quote, symbol, exchange)) return null;
+  const normalized = quoteWithFreshnessExchange(quote, exchange);
+  if (!hasValidQuoteObservationTime(normalized) || !hasQuotedPrice(normalized)) return null;
+  return { ...quote, stale: true };
+}
+
 export function providerFinancialsMatchTarget(value: TickerFinancials, symbol: string, exchange?: string): boolean {
   if (value.quote && !providerQuoteMatchesTarget(value.quote, symbol, exchange)) return false;
   if (Object.values(value.quoteContributions ?? {}).some((quote) => !providerQuoteMatchesTarget(quote, symbol, exchange))) return false;

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

@@ -23,7 +23,7 @@ import { isRoundTheClockCoin } from "../../utils/crypto-pair";
 import { zonedDateKey } from "../../utils/zoned-date-time";
 import { resolvePriceHistoryCurrencyUnit } from "../../utils/currency-units";
 import { calendarHistoryFetchState, calendarHistoryLastBarDate, dropLeadingPlaceholderBars, getPricePointTimestamp, hasUsablePriceHistory, preservePriceHistoryGaps, isPriceHistoryStaleForCurrentWindow, normalizePriceHistory, priceHistoryIntervalMs, type CalendarHistoryFetchState } from "../../utils/price-history";
-import { shouldLogProviderError } from "../provider-errors";
+import { noProviderError, noteProviderAnswer, noteProviderMiss, shouldLogProviderError, type ProviderMissNote } from "../provider-errors";
 import { HistoryCoverageError } from "../history-coverage";
 import {
   buildVariantKey,
@@ -66,6 +66,8 @@ interface HistoryAttempts {
   outcomes: Map<string, HistorySourceOutcome>;
   candidates: Map<string, HistoryRecoveryCandidate>;
   pending: Set<string>;
+  /** Whether every provider that failed said it found no listing for the symbol. */
+  misses: ProviderMissNote;
   coverageError?: HistoryCoverageError;
   retention?: HistoryRetention;
 }
@@ -105,6 +107,7 @@ function candidateForRequest(request: HistoryRequestDescriptor, sourceKey: strin
 
 function recordHistoryError(attempts: HistoryAttempts | undefined, request: HistoryRequestDescriptor, sourceKey: string, error: unknown): void {
   if (!attempts) return;
+  noteProviderMiss(attempts.misses, error);
   if (error instanceof InvalidHistoryResultError) {
     recordHistoryOutcome(attempts, sourceKey, "malformed");
   } else if (isHistoryRetentionError(error)) {
@@ -286,8 +289,13 @@ function calendarRecheckMarkerKey(request: HistoryRequestDescriptor) {
     variantKey: request.identity.variantKey, sourceKey: "router" };
 }
 
+interface HistoryRouteDeps extends ProviderRouterCoreDeps {
+  /** False in a short-lived process that must await refreshes of stale copies. */
+  revalidatesInBackground?(): boolean;
+}
+
 export class ProviderRouterHistoryRoutes {
-  constructor(private readonly deps: ProviderRouterCoreDeps) {}
+  constructor(private readonly deps: HistoryRouteDeps) {}
   private readonly historyRefreshInFlight = new Map<string, Promise<unknown>>();
   private readonly calendarRecheckAt = new Map<string, number>();
 
@@ -557,8 +565,9 @@ export class ProviderRouterHistoryRoutes {
       || hasRangeBarSize(record.value.points, request.requestedRange));
     // A background revalidation cannot correct bars from before a close in
     // time: a one-shot CLI exits first, and this caller keeps the old bars.
-    // Broader variants answer the same way. A current copy under another key
-    // (such as the refetch of this range) answers first. Next come copies
+    // That holds for daily bars and for intraday bars that stop short of the
+    // close. Broader variants answer the same way. A current copy under
+    // another key (such as the refetch of this range) answers first. Next come copies
     // fetched after the latest settled close that are behind, due a re-check
     // or not, the one reaching furthest first. A copy fetched before that close
     // answers only when no later copy exists: its latest bar may be the session
@@ -606,12 +615,16 @@ export class ProviderRouterHistoryRoutes {
     if (cachedBeforeClose) this.markCalendarChecked(request, now);
     const usableCached = hasUsablePriceHistory(cachedValue.points) && cached && !cached.expired && !cachedHistoryStale
       && !cachedBeforeClose;
-    if (usableCached && !forceRefresh) {
+    // 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
+    // background refresh lands, so it refetches a copy past its TTL before
+    // answering and falls back to that copy.
+    const refreshDue = !!cached?.stale && servedState === "current";
+    const awaitRefresh = refreshDue && !(this.deps.revalidatesInBackground?.() ?? true);
+    if (usableCached && !forceRefresh && !awaitRefresh) {
       const exactHit = request.exactCacheVariantKeys.includes(cached.variantKey);
-      // 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.
-      if (cached.stale && servedState === "current") {
+      if (refreshDue) {
         scheduleRouterRevalidation(this.historyRefreshInFlight, request.identity.revalidationKey, () => this.refreshHistory(request));
       }
       return exactHit || !request.requestedRange
@@ -623,7 +636,7 @@ export class ProviderRouterHistoryRoutes {
     const onUnavailable = (sourceKey: string, value: PriceHistoryResult) => {
       if (value.points.length && !hasUsablePriceHistory(value.points)) supersededCacheSources.add(sourceKey);
     };
-    const attempts: HistoryAttempts = { outcomes: new Map(), candidates: new Map(), pending: new Set() };
+    const attempts: HistoryAttempts = { outcomes: new Map(), candidates: new Map(), pending: new Set(), misses: {} };
     const brokerResult = await withBrokerTimeout(this.fetchBrokerHistory(request, brokerCandidates, onUnavailable, attempts));
     for (const sourceKey of [...attempts.pending]) recordHistoryOutcome(attempts, sourceKey, "timeout");
     if (brokerResult && hasUsablePriceHistory(brokerResult.value.points)) return withReportedGaps(brokerResult.value);
@@ -662,7 +675,9 @@ export class ProviderRouterHistoryRoutes {
       // 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");
-      throw new Error(behind ? `Latest history for ${target.symbol} is behind` : request.missingProviderError);
+      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);
     }
     return withReportedGaps(providerResult?.value ?? { points: [], resolution: historyResolutionForInterval(request.interval) });
   }
@@ -739,6 +754,7 @@ export class ProviderRouterHistoryRoutes {
       attempts?.pending.add(sourceKey);
       try {
         const fetched = await request.fetchProvider(provider);
+        noteProviderAnswer(attempts?.misses);
         if (fetched === null) { recordHistoryOutcome(attempts, sourceKey, "empty"); return null; }
         if (!Array.isArray(fetched.points)) { recordHistoryOutcome(attempts, sourceKey, "malformed"); return null; }
         const value = normalizeRequestResult({ ...fetched, sourceKey }, request);

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

@@ -109,7 +109,7 @@ export class AssetDataRouter implements DataProvider {
       getQuote: (ticker, exchange, context) => this.financialRoutes.getQuote(ticker, exchange, context),
       getTickerFinancials: (ticker, exchange, context) => this.financialRoutes.getTickerFinancials(ticker, exchange, context),
     });
-    this.historyRoutes = new ProviderRouterHistoryRoutes(routeDeps);
+    this.historyRoutes = new ProviderRouterHistoryRoutes({ ...routeDeps, revalidatesInBackground: () => this.revalidateInBackground });
     this.newsRoutes = new ProviderRouterNewsRoutes({
       newsSourcesInPriorityOrder: () => this.newsSourcesInPriorityOrder(),
       logProviderError: (message) => providerLog.error(message),