gloomberb 0.16.2 → 0.16.4

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/batches.ts

@@ -66,7 +66,7 @@ export class ProviderRouterBatchRoutes {
       const rawCached = selectCachedResource<Quote>(this.deps.resources, "quote", entityKey, variantKeys, sourceKeys, false);
       const cached = rawCached && (brokerSourceKeys.includes(rawCached.sourceKey)
         ? !isQuoteStaleForCurrentSession(quoteWithFreshnessExchange(rawCached.value, target.exchange))
-        : isProviderQuoteUsableForCurrentSession(rawCached.value, target.exchange, target.symbol))
+        : isProviderQuoteUsableForCurrentSession(rawCached.value, target.exchange, target.symbol, { recentAnswer: !rawCached.stale }))
         ? rawCached
         : null;
       if (cached && !forceRefresh && !cached.stale) {
@@ -93,7 +93,7 @@ export class ProviderRouterBatchRoutes {
       const uniqueTargets = [...providerIndexes.values()].map((bucket) => bucket[0]!.target);
       const batchResults = await batchProvider.getQuotesBatch!(uniqueTargets, options).catch(() => []);
       for (const item of batchResults) {
-        if (!isProviderQuoteUsableForCurrentSession(item.quote, item.target.exchange, item.target.symbol)) continue;
+        if (!isProviderQuoteUsableForCurrentSession(item.quote, item.target.exchange, item.target.symbol, { recentAnswer: true })) continue;
         const key = this.quoteBatchKey(item.target);
         const sourceKey = this.deps.providerSourceKey(batchProvider);
         for (const entry of providerIndexes.get(key) ?? []) {
@@ -162,7 +162,7 @@ export class ProviderRouterBatchRoutes {
         const key = this.cachedFinancialsBatchKey(item.target);
         let value = resolveTickerFinancialsQuoteState(normalizeTickerFinancialsPriceHistory(item.financials));
         if (value && !item.target.instrument && !providerFinancialsMatchTarget(value, item.target.symbol, item.target.exchange)) continue;
-        if (value) value = dropUnusableProviderQuote(value, item.target.exchange);
+        if (value) value = dropUnusableProviderQuote(value, item.target.exchange, { recentAnswer: true });
         if (!value) continue;
         const sourceKey = this.deps.providerSourceKey(batchProvider);
         for (const entry of providerIndexes.get(key) ?? []) {

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;
   }
@@ -200,7 +202,7 @@ export class ProviderRouterFinancialRoutes {
     const rawCached = selectCachedResource<Quote>(this.deps.resources, "quote", entityKey, variantKeys, sourceKeys, false);
     const cachedIsStale = rawCached && (brokerSourceKeys.includes(rawCached.sourceKey)
       ? isQuoteContributionStaleForCurrentSession(quoteWithFreshnessExchange(rawCached.value, exchange))
-      : !isProviderQuoteUsableForCurrentSession(rawCached.value, exchange, ticker));
+      : !isProviderQuoteUsableForCurrentSession(rawCached.value, exchange, ticker, { recentAnswer: !rawCached.stale }));
     const cached = rawCached && !cachedIsStale
       ? rawCached
       : null;
@@ -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(
@@ -259,7 +265,7 @@ export class ProviderRouterFinancialRoutes {
       if (
         record
         && (includeStale || !record.stale)
-        && isProviderQuoteUsableForCurrentSession(record.value, exchange, ticker)
+        && isProviderQuoteUsableForCurrentSession(record.value, exchange, ticker, { recentAnswer: !record.stale })
       ) {
         return record.value;
       }

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

@@ -4,10 +4,19 @@ 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 { activeUsMarketSession, delayedFeedLagMs, isMiddayBreakPrint, isUsPriorSessionPremarketQuote } from "../../market-data/market/freshness";
+import { canonicalExchange, parsePublicTickerKey } from "../../utils/exchanges";
+import {
+  activeUsMarketSession,
+  delayedFeedLagMs,
+  isMiddayBreakPrint,
+  isRegularSessionTime,
+  isUsExtendedHoursSessionPrint,
+  isUsPriorSessionPremarketQuote,
+  isUsRegularCloseQuoteInPostSession,
+  latestRegularSessionOpen,
+} from "../../market-data/market/freshness";
 import {
   mergeQuoteContributionMaps,
   isQuoteContributionStaleForCurrentSession,
@@ -122,7 +131,50 @@ function isQuoteInActiveSession(quote: Quote, now: number): boolean {
   return false;
 }
 
-function isActiveProviderQuoteTooOld(quote: Quote, now = Date.now()): boolean {
+// An opening auction can print before the continuous open (Hong Kong's at 09:20).
+const OPENING_AUCTION_MS = 15 * 60_000;
+
+/**
+ * Whether Gloom Cloud vouches that a delayed quote is current, however long
+ * ago its last trade was. The service judges more than that trade's age: it
+ * knows when it asked for the quote and how often the listing trades, so a
+ * thinly traded listing's hour-old trade can be the current price while its
+ * venue trades. Its verdict stands in for the age bound when:
+ * - the service answered on this request, or a cache entry still inside its
+ *   TTL holds that answer (`recentAnswer`); a copy past the TTL is not vouched for;
+ * - the answer says `stale: false`. One without the flag vouches for nothing,
+ *   and one flagged stale never gets this far;
+ * - 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; 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 === "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);
+  return open != null && quote.lastUpdated >= open - OPENING_AUCTION_MS;
+}
+
+function isActiveProviderQuoteTooOld(quote: Quote, now = Date.now(), recentAnswer = false): boolean {
   // The shared freshness predicate already validates and dates a daily NAV.
   if (quote.priceObservation === "nav") return false;
   if (!isQuoteInActiveSession(quote, now)) return false;
@@ -132,12 +184,17 @@ function isActiveProviderQuoteTooOld(quote: Quote, now = Date.now()): boolean {
   if (isUsPriorSessionPremarketQuote(quote.lastUpdated, exchange, quote.marketState, now)) {
     return false;
   }
+  // Likewise today's regular close before any after-hours trade.
+  if (quote.postMarketPrice == null && isUsRegularCloseQuoteInPostSession(quote.lastUpdated, exchange, quote.marketState, now)) {
+    return false;
+  }
   if (!Number.isFinite(quote.lastUpdated)) return false;
   const delayed = quote.dataSource === "delayed";
   const maxAge = delayed ? ACTIVE_DELAYED_PROVIDER_QUOTE_MAX_AGE_MS : ACTIVE_PROVIDER_QUOTE_MAX_AGE_MS;
   if (now - quote.lastUpdated <= maxAge) return false;
   // While the venue pauses at midday, the morning's last print is the current price.
-  return !isMiddayBreakPrint(quote.lastUpdated, exchange, now, delayed ? delayedFeedLagMs(exchange) : 0);
+  if (isMiddayBreakPrint(quote.lastUpdated, exchange, now, delayed ? delayedFeedLagMs(exchange) : 0)) return false;
+  return !(recentAnswer && isVouchedCurrentByService(quote, exchange, now));
 }
 
 export function providerQuoteMatchesTarget(quote: Quote | null | undefined, symbol?: string, exchange?: string): quote is Quote {
@@ -157,26 +214,55 @@ export function providerQuoteMatchesTarget(quote: Quote | null | undefined, symb
   return true;
 }
 
-export function isProviderQuoteUsableForCurrentSession(quote: Quote | null | undefined, exchange?: string, symbol?: string): quote is Quote {
+/**
+ * `recentAnswer`: the source answered with this quote on this request, or a
+ * cache entry still inside its TTL holds it. Only then can the source's own
+ * verdict on a delayed quote stand in for the age bound.
+ */
+export function isProviderQuoteUsableForCurrentSession(
+  quote: Quote | null | undefined,
+  exchange?: string,
+  symbol?: string,
+  options: { recentAnswer?: boolean } = {},
+): quote is Quote {
   if (!providerQuoteMatchesTarget(quote, symbol, exchange)) return false;
   const normalized = quoteWithFreshnessExchange(quote, exchange);
   if (isQuoteStaleForCurrentSession(normalized)) return false;
-  if (isActiveProviderQuoteTooOld(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;
@@ -188,8 +274,12 @@ export function providerFinancialsMatchTarget(value: TickerFinancials, symbol: s
   return quoteMetadataMatchesTarget(metadata, hasListing ? symbol : parsePublicTickerKey(symbol).symbol, hasListing ? exchange : undefined);
 }
 
-export function dropUnusableProviderQuote(value: TickerFinancials, exchange?: string): TickerFinancials {
-  if (!value.quote || isProviderQuoteUsableForCurrentSession(value.quote, exchange)) {
+export function dropUnusableProviderQuote(
+  value: TickerFinancials,
+  exchange?: string,
+  options: { recentAnswer?: boolean } = {},
+): TickerFinancials {
+  if (!value.quote || isProviderQuoteUsableForCurrentSession(value.quote, exchange, undefined, options)) {
     return value;
   }
 

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),

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

@@ -4,7 +4,7 @@ import type { MarketDataRequestContext } from "../../types/data-provider";
 import type { Quote, TickerFinancials } from "../../types/financials";
 import { normalizeTickerFinancialsPriceHistory } from "../../utils/price-history";
 import { resolveTickerFinancialsQuoteState } from "../../market-data/quotes/resolution";
-import { shouldLogProviderError } from "../provider-errors";
+import { noteProviderAnswer, noteProviderMiss, shouldLogProviderError, type ProviderMissNote } from "../provider-errors";
 import { quoteMetadataFromQuote } from "../../market-data/quotes/metadata";
 import {
   dropUnusableProviderQuote,
@@ -14,12 +14,19 @@ import {
   needsFinancialProfile,
   profileForSameListing,
   isProviderQuoteUsableForCurrentSession,
+  lastKnownProviderQuote,
   providerFinancialsMatchTarget,
   mergeMissingStatementArrays,
   mergeFinancials,
 } from "./financials";
 import type { ProviderRouterCoreDeps, SourceResult } from "./route-types";
 
+/** What the providers of one quote request said when none had a current quote. */
+export interface ProviderQuoteMissNote extends ProviderMissNote {
+  /** The newest priced answer for the target that was not current for its session, flagged stale. */
+  lastKnownQuote?: Quote;
+}
+
 export class ProviderRouterPrimaryRoutes {
   constructor(private readonly options: ProviderRouterCoreDeps) {}
 
@@ -61,6 +68,7 @@ export class ProviderRouterPrimaryRoutes {
     ticker: string,
     exchange?: string,
     context?: MarketDataRequestContext,
+    misses?: ProviderMissNote,
   ): Promise<SourceResult<TickerFinancials> | null> {
     const entityKey = this.options.getEntityKey(ticker, context?.instrument);
     const variantKey = financialHistoryVariants(this.options.getTickerVariantCandidates(exchange), context)[0] ?? "";
@@ -70,11 +78,11 @@ export class ProviderRouterPrimaryRoutes {
     for (const provider of this.options.providersInPriorityOrder()) {
       try {
         const rawValue = await provider.getTickerFinancials(ticker, exchange, context);
-        if (rawValue && !context?.instrument && !providerFinancialsMatchTarget(rawValue, ticker, exchange)) continue;
+        if (rawValue && !context?.instrument && !providerFinancialsMatchTarget(rawValue, ticker, exchange)) { noteProviderAnswer(misses); continue; }
         const resolvedValue = resolveTickerFinancialsQuoteState(normalizeTickerFinancialsPriceHistory(rawValue));
-        if (resolvedValue && !context?.instrument && !providerFinancialsMatchTarget(resolvedValue, ticker, exchange)) continue;
-        let value = resolvedValue ? dropUnusableProviderQuote(resolvedValue, exchange) : null;
-        if (!value) continue;
+        if (resolvedValue && !context?.instrument && !providerFinancialsMatchTarget(resolvedValue, ticker, exchange)) { noteProviderAnswer(misses); continue; }
+        let value = resolvedValue ? dropUnusableProviderQuote(resolvedValue, exchange, { recentAnswer: true }) : null;
+        if (!value) { noteProviderAnswer(misses); continue; }
         const sourceKey = this.options.providerSourceKey(provider);
         if (context?.statementHistory === "extended" && !hasReusableExtendedHistory(value)) {
           const previous = selectCachedResource<TickerFinancials>(this.options.resources, "financials", entityKey, [variantKey], [sourceKey], true);
@@ -131,6 +139,7 @@ export class ProviderRouterPrimaryRoutes {
           if (!needsFinancialProfile(primaryResult.value) && (context?.statementHistory === "extended" ? primaryResult.value.statementHistory?.status === "available" : hasDetailedStatementRows(primaryResult.value) && hasDeepStatementHistory(primaryResult.value))) return primaryResult;
         }
       } catch (error) {
+        noteProviderMiss(misses, error);
         if (shouldLogProviderError(error)) {
           this.options.logProviderError(`${provider.id} failed: ${error}`);
         }
@@ -181,13 +190,21 @@ export class ProviderRouterPrimaryRoutes {
     ticker: string,
     exchange?: string,
     context?: MarketDataRequestContext,
+    misses?: ProviderQuoteMissNote,
   ): Promise<SourceResult<Quote> | null> {
     const entityKey = this.options.getEntityKey(ticker, context?.instrument);
     const variantKey = this.options.getTickerVariantCandidates(exchange)[0] ?? "";
     for (const provider of this.options.providersInPriorityOrder()) {
       try {
         const quote = await provider.getQuote(ticker, exchange, context);
-        if (!isProviderQuoteUsableForCurrentSession(quote, exchange, ticker)) continue;
+        if (!isProviderQuoteUsableForCurrentSession(quote, exchange, ticker, { recentAnswer: true })) {
+          noteProviderAnswer(misses);
+          const lastKnown = misses && lastKnownProviderQuote(quote, exchange, ticker);
+          if (lastKnown && (misses.lastKnownQuote?.lastUpdated ?? -Infinity) < lastKnown.lastUpdated) {
+            misses.lastKnownQuote = lastKnown;
+          }
+          continue;
+        }
         const sourceKey = this.options.providerSourceKey(provider);
         this.options.cacheResource(
           "quote",
@@ -199,6 +216,7 @@ export class ProviderRouterPrimaryRoutes {
         );
         return { sourceKey, value: quote };
       } catch (error) {
+        noteProviderMiss(misses, error);
         if (shouldLogProviderError(error)) {
           this.options.logProviderError(`${provider.id} failed: ${error}`);
         }