gloomberb 0.13.2 → 0.14.0

package/src/sources/gloomberb-cloud/quote-metadata.test.ts

@@ -0,0 +1,50 @@
+import { afterEach, expect, spyOn, test } from "bun:test";
+import { apiClient, type CloudQuotePayload } from "../../api-client";
+import { createGloomberbCloudProvider } from "./index";
+
+let quoteSpy: ReturnType<typeof spyOn> | undefined;
+afterEach(() => { quoteSpy?.mockRestore(); quoteSpy = undefined; });
+
+test("static quote metadata preserves source facts while stale prices remain rejected", async () => {
+  const raw: CloudQuotePayload = { symbol: "EURUSD=X", listingExchangeName: "CCY", currency: "USD", instrumentType: "CURRENCY",
+    price: 1.1602274179458618, change: -0.001077882, changePercent: -0.0928, lastUpdated: Date.parse("2026-09-11T21:29Z"),
+    receivedAt: Date.parse("2026-09-12T03:48Z"), stale: true };
+  quoteSpy = spyOn(apiClient, "getCloudQuote").mockResolvedValue({ status: "success", data: raw, stale: true });
+  const provider = createGloomberbCloudProvider();
+  await expect(provider.getQuote("EURUSD=X")).rejects.toThrow("stale");
+  expect(await provider.getQuoteMetadata!("EURUSD=X")).toEqual({ symbol: "EURUSD=X", listingExchangeName: "CCY", currency: "USD", instrumentType: "CURRENCY",
+    source: { providerId: "gloomberb-cloud", lastUpdated: raw.lastUpdated, stale: true, provenance: undefined } });
+  expect(raw.price).toBe(1.1602274179458618);
+  raw.lastUpdated = NaN;
+  expect((await provider.getQuoteMetadata!("EURUSD=X"))?.source.lastUpdated).toBeUndefined();
+});
+
+test("metadata validates the requested listing and preserves normalized minor units without price fields", async () => {
+  const provider = createGloomberbCloudProvider();
+  quoteSpy = spyOn(apiClient, "getCloudQuote");
+  for (const [ticker, exchange, symbol, listing, currency, accepted] of [
+    ["ASML:XAMS", "NASDAQ", "ASML", "XAMS", "EUR", true],
+    ["ASML", "AMS", "ASML", "NASDAQ", "USD", false],
+    ["ASML", "AMS", "ASML", "", "EUR", false],
+    ["CL=F", "NYMEX", "CL=F", "NY MERCANTILE", "USD", true],
+    ["CL=F", "COMEX", "CL=F", "NY MERCANTILE", "USD", false],
+    ["ASML", "AMS", "ASML:XNAS", "AMS", "EUR", false],
+    ["ASML", "AMS", "OTHER", "AMS", "EUR", false],
+    ["VOD:XLON", "NASDAQ", "VOD.L", "LSE", "GBp", true],
+    ["9988", "HKEX", "9988.HK", "HKG", "HKD", true],
+    ["BTC-USD", "CCC", "BTC-USD", "CCC", "USD", true],
+  ] as const) {
+    quoteSpy.mockResolvedValue({ status: "success", stale: false, providerMeta: { stale: true },
+      data: { symbol, listingExchangeName: listing, currency, instrumentType: "EQUITY", price: 123, change: 0, changePercent: 0, lastUpdated: 1234 } });
+    const result = await provider.getQuoteMetadata!(ticker, exchange);
+    expect(result !== null).toBe(accepted);
+    if (result) {
+      expect(result.currency).toBe(currency === "GBp" ? "GBP" : currency);
+      expect(result.source).toMatchObject({ lastUpdated: 1234, stale: true });
+      expect(Object.keys(result).sort()).toEqual(["currency", "instrumentType", "listingExchangeName", "source", "symbol"]);
+      expect("price" in result || "receivedAt" in result.source).toBe(false);
+    }
+  }
+  quoteSpy.mockResolvedValue({ status: "unsupported", data: null });
+  await expect(provider.getQuoteMetadata!("UNKNOWN")).rejects.toThrow();
+});

package/src/sources/gloomberb-cloud/valuation-observations.ts

@@ -0,0 +1,29 @@
+import type { TickerFinancials } from "../../types/financials";
+import { canonicalExchange, parsePublicTickerKey } from "../../utils/exchanges";
+import { redactUnavailableFundamentals } from "../../utils/fundamentals";
+
+/** Retire the exact mapped SAP observation still served by older Cloud
+ * deployments/caches. Raw share/period validation belongs to the backend;
+ * this narrower guard cannot classify a different source observation.
+ * See docs/data-quality/sap-us-valuation.md. */
+export function retractKnownCloudValuation(
+  financials: TickerFinancials,
+  target?: { symbol: string; exchange?: string },
+): TickerFinancials {
+  const value = redactUnavailableFundamentals(financials.fundamentals);
+  if (!value || (value.source && !["twelvedata", "cache"].includes(value.source)) ||
+    value.sharesOutstanding !== 1_154_204_232) return financials;
+  const quote = financials.quote ?? financials.quoteMetadata;
+  const identity = parsePublicTickerKey(quote?.symbol ?? target?.symbol ?? "");
+  const venue = canonicalExchange(quote?.listingExchangeName ||
+    financials.quote?.exchangeName || identity.exchange || target?.exchange);
+  if (identity.symbol !== "SAP" || (venue && venue !== "NYSE") ||
+    (quote?.currency ?? value.marketCapCurrency) !== "USD") return financials;
+  const unavailable = new Set(value.unavailableFields ?? []);
+  if (value.enterpriseValue === 4_095_338_359_014) unavailable.add("enterpriseValue");
+  if (value.enterpriseToRevenue === 92.879) unavailable.add("enterpriseToRevenue");
+  if (unavailable.size === (value.unavailableFields?.length ?? 0)) return financials;
+  return { ...financials, fundamentals: redactUnavailableFundamentals({
+    ...value, unavailableFields: [...unavailable],
+  }) };
+}

package/src/sources/history-coverage.test.ts

@@ -0,0 +1,40 @@
+import { expect, test } from "bun:test";
+import { applyYahooHistoryCoverage } from "./history-coverage";
+import { fetchYahooChart } from "./yahoo-finance/requests";
+import type { YahooHttpClient } from "./yahoo-finance/http";
+
+const meta = { symbol: "SHEL.L", exchangeName: "LSE", currency: "GBp" };
+const point = (date: string, close: number) => ({ date: new Date(date), close });
+
+test("the shared Yahoo request boundary removes spanning OHLC and retains source provenance", async () => {
+  const raw = { chart: { result: [{ meta: { ...meta, dataGranularity: "1wk" },
+    timestamp: [Date.parse("2005-07-18T07:00:00Z") / 1000, Date.parse("2005-07-25T07:00:00Z") / 1000],
+    indicators: { quote: [{ open: [1829.5, 1764], high: [1845, 1776], low: [1720, 1701], close: [1748, 1747], volume: [42, 58] }] },
+  }] } };
+  const http = { fetchJson: async () => structuredClone(raw) } as unknown as YahooHttpClient;
+  const chart = await fetchYahooChart(http, "SHEL.L", "max", "1wk");
+  expect(chart.history).toHaveLength(1);
+  expect(chart.history[0]).toMatchObject({ open: 1764, high: 1776, low: 1701, close: 1747, volume: 58,
+    historySource: { provider: "yahoo", symbol: "SHEL", exchange: "LSE", currency: "GBP", verifiedLineageStart: "2005-07-21" } });
+  expect(raw.chart.result[0]!.timestamp).toHaveLength(2);
+});
+
+test("daily and monthly coverage excludes earlier bars without altering retained observations", () => {
+  const daily = [point("1997-06-30", 6389.35986328125), point("1997-07-01", 1805.6500244140625),
+    point("2005-07-20", 1766.5), point("2005-07-21", 1753), point("2026-09-10", 3533)];
+  expect(applyYahooHistoryCoverage("SHEL.L", meta, "1d", daily).map((p) => p.close)).toEqual([1753, 3533]);
+  expect(applyYahooHistoryCoverage("SHEL.L", meta, "1mo", [point("2005-07-01", 1747), point("2005-08-01", 1800)])
+    .map((p) => p.close)).toEqual([1800]);
+  expect(() => applyYahooHistoryCoverage("SHEL.L", meta, "1d", daily.slice(0, 2))).toThrow("earlier share lineage is unverified");
+  expect(daily).toHaveLength(5);
+});
+
+test("foreign and US listings, other issuers, and intraday observations remain untouched", () => {
+  const points = [point("1997-06-30", 123), point("2026-09-10", 456)];
+  for (const symbol of ["SHEL", "SHELL.AS", "BP.L"]) expect(applyYahooHistoryCoverage(symbol, meta, "1d", points)).toBe(points);
+  expect(applyYahooHistoryCoverage("SHEL.L", meta, "5m", points)).toBe(points);
+  for (const invalid of [{ ...meta, symbol: "SHEL" }, { ...meta, currency: "USD" },
+    { ...meta, exchangeName: "AMS" }, { symbol: "SHEL.L", currency: "GBp" }]) {
+    expect(() => applyYahooHistoryCoverage("SHEL.L", invalid, "1d", points)).toThrow("identity");
+  }
+});

package/src/sources/history-coverage.ts

@@ -0,0 +1,97 @@
+import type { PriceHistorySource, PricePoint, TickerFinancials } from "../types/financials";
+import { canonicalExchange, parsePublicTickerKey } from "../utils/exchanges";
+import { getPricePointTimestamp } from "../utils/price-history";
+import { ProviderMissError } from "./provider-errors";
+
+export const SHELL_VERIFIED_LINEAGE_START = "2005-07-21";
+const coverageMessage = (providers: PriceHistorySource["provider"][]) => `${providers.map((provider) => provider === "yahoo" ? "Yahoo" : "Twelve Data").join(" and ")} London Shell coverage begins 2005-07-21; earlier share lineage is unverified.`;
+
+export class HistoryCoverageError extends ProviderMissError {
+  constructor(reason: PriceHistorySource["provider"] | { message: string } = "yahoo") {
+    super(typeof reason === "string" ? coverageMessage([reason]) : reason.message);
+    this.name = "HistoryCoverageError";
+  }
+}
+
+export function hasShellCoverageRestriction(value: unknown): value is { source: PriceHistorySource["provider"]; reasonCode: "UNVERIFIED_PREDECESSOR_LINEAGE"; verifiedLineageStart: "2005-07-21" } {
+  const coverage = value as { source?: unknown; reasonCode?: unknown; verifiedLineageStart?: unknown } | null;
+  return (coverage?.source === "yahoo" || coverage?.source === "twelvedata") && coverage.reasonCode === "UNVERIFIED_PREDECESSOR_LINEAGE"
+    && coverage.verifiedLineageStart === SHELL_VERIFIED_LINEAGE_START;
+}
+
+export function isShellLondonTarget(symbol: string, exchange?: string): boolean {
+  const parsed = parsePublicTickerKey(symbol);
+  const venue = canonicalExchange(parsed.exchange || exchange);
+  return (parsed.symbol === "SHEL" && venue === "LSE")
+    || (parsed.symbol === "SHEL.L" && (!venue || venue === "LSE"));
+}
+
+export function verifiedPriceHistorySource(value: unknown): PriceHistorySource | undefined {
+  const source = value as Partial<PriceHistorySource> | null;
+  if (!source || source.symbol !== "SHEL" || source.exchange !== "LSE" || source.currency !== "GBP"
+    || !["yahoo", "twelvedata"].includes(source.provider ?? "")
+    || source.verifiedLineageStart !== SHELL_VERIFIED_LINEAGE_START) return undefined;
+  return { provider: source.provider!, symbol: "SHEL", exchange: "LSE", currency: "GBP",
+    ...(source.verifiedLineageStart ? { verifiedLineageStart: source.verifiedLineageStart } : {}) };
+}
+
+/** Old cloud arrays lack upstream provenance. Retire only affected London
+ * source records; ordinary modern histories and independent providers survive.
+ * Both exact Yahoo and Twelve London histories share the unreconciled basis. */
+export function hasUnverifiedShellHistory(
+  points: readonly PricePoint[], target: { symbol: string; exchange?: string }, sourceKey: string,
+  requestedStart?: number,
+): boolean {
+  if (!isShellLondonTarget(target.symbol, target.exchange)
+    || !["provider:yahoo", "provider:gloomberb-cloud"].includes(sourceKey)) return false;
+  const cutoff = Date.parse(SHELL_VERIFIED_LINEAGE_START);
+  return points.some((point) => getPricePointTimestamp(point) < cutoff)
+    // Older clients dropped even corrected source provenance. Refetch those
+    // cached long windows to recover the explanation, without invalidating 1Y.
+    || (requestedStart !== undefined && requestedStart < cutoff && points.length > 0
+      && !points.some((point) => verifiedPriceHistorySource(point.historySource)));
+}
+
+export function historyCoverageNotice(points: readonly PricePoint[], requestedStart: number | null): string | null {
+  if (requestedStart !== null && requestedStart >= Date.parse(SHELL_VERIFIED_LINEAGE_START)) return null;
+  const providers = [...new Set(points.flatMap((point) => {
+    const source = verifiedPriceHistorySource(point.historySource);
+    return source ? [source.provider] : [];
+  }))];
+  return providers.length ? coverageMessage(providers) : null;
+}
+
+export function sanitizeShellFinancialHistory(
+  value: TickerFinancials, target: { symbol: string; exchange?: string }, sourceKey: string,
+): TickerFinancials {
+  return hasUnverifiedShellHistory(value.priceHistory, target, sourceKey)
+    ? { ...value, priceHistory: [] } : value;
+}
+
+/** The issuer's London A-share dataset starts here. Yahoo's preceding current-
+ * ticker history contains an unreconciled 1997 discontinuity. Corroborated
+ * post-unification samples establish A-share lineage, not every daily price.
+ * Do not reconstruct predecessor prices using an assumed split or FX ratio. */
+export function applyYahooHistoryCoverage(
+  symbol: string,
+  metadata: { symbol?: unknown; exchangeName?: unknown; currency?: unknown },
+  interval: string,
+  points: PricePoint[],
+): PricePoint[] {
+  if (symbol.toUpperCase() !== "SHEL.L" || /^\d+(m|h)$/i.test(interval)) return points;
+  if (metadata.symbol !== "SHEL.L" || typeof metadata.exchangeName !== "string"
+    || canonicalExchange(metadata.exchangeName) !== "LSE" || !["GBp", "GBP"].includes(String(metadata.currency))) {
+    throw new Error("Shell London history source identity could not be verified");
+  }
+  const historySource: PriceHistorySource = {
+    provider: "yahoo", symbol: "SHEL", exchange: "LSE", currency: "GBP",
+    verifiedLineageStart: SHELL_VERIFIED_LINEAGE_START,
+  };
+  // Yahoo timestamps identify the start of a bar. Drop a whole spanning weekly
+  // or monthly bar; retaining its close would leave unreconciled OHLC values.
+  const cutoff = Date.parse(SHELL_VERIFIED_LINEAGE_START);
+  const retained = points.filter((point) => point.date.getTime() >= cutoff)
+    .map((point) => ({ ...point, historySource }));
+  if (points.length > 0 && retained.length === 0) throw new HistoryCoverageError();
+  return retained;
+}

package/src/sources/listing-history.ts

@@ -0,0 +1,52 @@
+import type { PricePoint, TickerFinancials } from "../types/financials";
+import { canonicalExchange, parsePublicTickerKey } from "../utils/exchanges";
+import { getPricePointTimestamp } from "../utils/price-history";
+import { HistoryCoverageError } from "./history-coverage";
+
+const CIRCLE_IPO_MONTH = Date.parse("2025-06-01");
+const CIRCLE_FIRST_SESSION_END = Date.parse("2025-06-06");
+
+/** The June 4 offer was $31; NYSE trading began June 5. Captured Cloud
+ * daily history inserts that offer as OHLC, and its inception week/month
+ * carries the same $31 open/low. Its first-session intraday feed also
+ * inserts the offer before the opening auction (13:40 UTC in 5m data),
+ * though independent daily trading OHLC is 69/103.75/64/83.23.
+ * This is an exact attested source defect,
+ * not a general zero-volume or pre-inception-bar heuristic.
+ * https://www.circle.com/pressroom/circle-announces-pricing-of-upsized-initial-public-offering
+ */
+export function hasCircleOfferingPriceHistory(
+  points: readonly PricePoint[],
+  target: { symbol: string; exchange?: string },
+  sourceKey: string,
+): boolean {
+  if (sourceKey !== "provider:gloomberb-cloud") return false;
+  const parsed = parsePublicTickerKey(target.symbol);
+  const exchange = canonicalExchange(parsed.exchange || target.exchange);
+  // The unqualified Cloud CRCL endpoint is the same US default listing. An
+  // explicit other venue remains a distinct target, even with similar values.
+  if (parsed.symbol !== "CRCL" || (exchange && exchange !== "NYSE")) return false;
+  return points.some((point) => {
+    const time = getPricePointTimestamp(point);
+    return time >= CIRCLE_IPO_MONTH && time < CIRCLE_FIRST_SESSION_END
+      && point.open === 31 && point.low === 31;
+  });
+}
+
+export function assertTradingPriceHistory(
+  points: PricePoint[], target: { symbol: string; exchange?: string }, sourceKey: string,
+): PricePoint[] {
+  if (hasCircleOfferingPriceHistory(points, target, sourceKey)) {
+    // Reject the entire requested source window. Dropping the bad bar alone
+    // could silently move a comparison baseline or claim a complete month.
+    throw new HistoryCoverageError({ message: "CRCL NYSE history includes the June 4, 2025 IPO offer price as market history. Trading began June 5; the affected source window is unavailable." });
+  }
+  return points;
+}
+
+export function sanitizeListingFinancialHistory(
+  value: TickerFinancials, target: { symbol: string; exchange?: string }, sourceKey: string,
+): TickerFinancials {
+  return hasCircleOfferingPriceHistory(value.priceHistory, target, sourceKey)
+    ? { ...value, priceHistory: [] } : value;
+}

package/src/sources/listing-target.ts

@@ -0,0 +1,41 @@
+import { canonicalExchange, parsePublicTickerKey } from "../utils/exchanges";
+import { createProviderMiss } from "./provider-errors";
+import { yahooSuffixConflictsWithExchange, yahooSuffixExchange } from "./yahoo-finance/symbols";
+
+/** Explicit public qualifications must agree; bare suffixes outrank remembered metadata. */
+export function publicListingTarget(symbol: string, exchange?: string) {
+  const parsed = parsePublicTickerKey(symbol);
+  if (parsed.exchange && yahooSuffixConflictsWithExchange(parsed.symbol, parsed.exchange)) {
+    throw createProviderMiss(`Listing suffix conflicts with exchange ${parsed.exchange}: ${symbol}`);
+  }
+  return {
+    symbol: parsed.symbol,
+    exchange: parsed.exchange ?? yahooSuffixExchange(parsed.symbol) ?? (exchange ? canonicalExchange(exchange) : exchange),
+  };
+}
+
+/** Preserve a provider's venue spelling when the symbol itself has no listing hint. */
+export function publicListingExchange(symbol: string, exchange?: string): string | undefined {
+  const parsed = parsePublicTickerKey(symbol);
+  return parsed.exchange || yahooSuffixExchange(parsed.symbol)
+    ? publicListingTarget(symbol, exchange).exchange : exchange;
+}
+
+/** Keep each caller's target object when normalized requests are returned out of order. */
+export function mapListingTargets<T extends { symbol: string; exchange?: string }>(
+  targets: T[],
+  resolveExchange: (target: T) => string | undefined = (target) => publicListingTarget(target.symbol, target.exchange).exchange,
+) {
+  const originals = new Map<T, T>();
+  const valid: T[] = [];
+  const invalid: Array<{ target: T; error: unknown }> = [];
+  for (const target of targets) {
+    try {
+      const exchange = resolveExchange(target);
+      const resolved = exchange === target.exchange ? target : { ...target, exchange };
+      originals.set(resolved, target);
+      valid.push(resolved);
+    } catch (error) { invalid.push({ target, error }); }
+  }
+  return { valid, invalid, original: (target: T) => originals.get(target) ?? target };
+}

package/src/sources/provider-router/arca-cache.test.ts

@@ -0,0 +1,97 @@
+import { expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { AssetDataRouter } from "./index";
+import { AppPersistence } from "../../data/app-persistence";
+import { createTestDataProvider } from "../../test-support/data-provider";
+import type { Quote, TickerFinancials } from "../../types/financials";
+import { activeUsExtendedHoursSession } from "../../market-data/market/freshness";
+
+function financials(exchange: string, price: number, instrumentType: string): TickerFinancials {
+  const quote: Quote = { symbol: "TIP", listingExchangeName: exchange, exchangeName: exchange,
+    currency: "USD", price, change: 0, changePercent: 0, lastUpdated: Date.now(),
+    marketState: activeUsExtendedHoursSession(Date.now()) ?? "REGULAR", preMarketPrice: price, postMarketPrice: price, instrumentType };
+  return { quote, annualStatements: instrumentType === "ETF" ? [] : [{ date: "2025-12-31", currency: "USD", totalRevenue: 666 }],
+    quarterlyStatements: [], priceHistory: [] };
+}
+
+test("legacy PCX normalization cannot outrank a fresh Arca fund or survive a cache restart", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "gloom-arca-cache-"));
+  const path = join(dir, "cache.sqlite");
+  let store = new AppPersistence(path);
+  const old = financials("AMEX", 666, "EQUITY");
+  const fresh = financials("ARCA", 105, "ETF");
+  let requests = 0;
+  const provider = createTestDataProvider({ getTickerFinancials: async () => { requests++; return fresh; } });
+  try {
+    for (const variantKey of ["", "exchange=AMEX"]) {
+      store.resources.set({ namespace: "market", kind: "financials", entityKey: "TIP", variantKey, sourceKey: "provider:test-provider" },
+        old, { schemaVersion: 7, cachePolicy: { staleMs: 60_000, expireMs: 600_000 } });
+      store.resources.set({ namespace: "market", kind: "quote", entityKey: "TIP", variantKey, sourceKey: "provider:test-provider" },
+        old.quote, { schemaVersion: 1, cachePolicy: { staleMs: 60_000, expireMs: 600_000 } });
+    }
+    store.close(); store = new AppPersistence(path);
+    const router = new AssetDataRouter(provider, [], store.resources);
+    for (const exchange of [undefined, "PCX", "ARCA"]) {
+      expect(router.getCachedFinancialsForTargets([{ symbol: "TIP", exchange }]).get("TIP")?.quote?.price).not.toBe(666);
+      const result = await router.getTickerFinancials("TIP", exchange);
+      expect(result.quote).toMatchObject({ price: 105, listingExchangeName: "ARCA", instrumentType: "ETF" });
+      expect(result.annualStatements).toEqual([]);
+    }
+    expect(router.getCachedFinancialsForTargets([{ symbol: "TIP", exchange: "AMEX" }]).get("TIP")?.quote?.price).toBe(666);
+    const count = requests;
+    store.close(); store = new AppPersistence(path);
+    const reopened = new AssetDataRouter(provider, [], store.resources);
+    expect(reopened.getCachedFinancialsForTargets([{ symbol: "TIP", exchange: "PCX" }]).get("TIP")?.quote?.price).toBe(105);
+    expect(reopened.getCachedFinancialsForTargets([{ symbol: "TIP" }]).get("TIP")?.quote?.price).toBe(105);
+    expect(requests).toBe(count);
+    // A newly verified genuine American listing is reusable even unqualified.
+    const american = createTestDataProvider({ getTickerFinancials: async () => old });
+    const verifiedStore = new AppPersistence(":memory:");
+    try {
+      const verified = new AssetDataRouter(american, [], verifiedStore.resources);
+      expect((await verified.getTickerFinancials("TIP")).quote?.price).toBe(666);
+      expect(verified.getCachedFinancialsForTargets([{ symbol: "TIP" }]).get("TIP")?.quote?.price).toBe(666);
+    } finally { verifiedStore.close(); }
+  } finally { store.close(); rmSync(dir, { recursive: true, force: true }); }
+});
+
+for (const mode of ["single", "batch"] as const) test(`${mode} rejects wrong-listing research before unusable quotes lose their identity`, async () => {
+  for (const kind of ["quote", "metadata", "contribution", "malformed-metadata"] as const) {
+    const store = new AppPersistence(":memory:");
+    const old = financials("AMEX", 666, "EQUITY");
+    const invalidQuote = { ...old.quote!, price: NaN, preMarketPrice: undefined, postMarketPrice: undefined };
+    const wrong = { ...old, quote: kind === "quote" ? invalidQuote : undefined,
+      ...(kind === "contribution" ? { quoteContributions: { fixture: { ...invalidQuote, providerId: "fixture" } } } : {}),
+      ...(kind.includes("metadata") ? { quoteMetadata: { symbol: kind === "malformed-metadata" ? 42 : "TIP", listingExchangeName: "AMEX" } } : {}) } as TickerFinancials;
+    const good = { ...financials("ARCA", 105, "ETF"), quote: { ...financials("ARCA", 105, "ETF").quote!, symbol: "SPY" } };
+    const provider = createTestDataProvider({
+      getTickerFinancials: async (symbol) => symbol === "TIP" ? wrong : good,
+      getTickerFinancialsBatch: async (targets) => targets.map((target) => ({ target, financials: target.symbol === "TIP" ? wrong : good })),
+      getQuote: async () => { throw new Error("No independent quote"); },
+    });
+    try {
+      const router = new AssetDataRouter(provider, [], store.resources);
+      if (mode === "single") await expect(router.getTickerFinancials("TIP", "ARCA")).rejects.toThrow();
+      else {
+        const result = await router.getTickerFinancialsBatch([{ symbol: "TIP", exchange: "ARCA" }, { symbol: "SPY", exchange: "ARCA" }]);
+        expect(result.find((row) => row.target.symbol === "TIP")?.financials?.annualStatements[0]?.totalRevenue).not.toBe(666);
+        expect(result.find((row) => row.target.symbol === "SPY")?.financials?.quote?.symbol).toBe("SPY");
+      }
+      expect(router.getCachedFinancialsForTargets([{ symbol: "TIP", exchange: "ARCA" }]).get("TIP")?.annualStatements[0]?.totalRevenue).not.toBe(666);
+    } finally { store.close(); }
+  }
+});
+
+test("same-listing research remains usable when only its quote is stale", async () => {
+  const store = new AppPersistence(":memory:");
+  const value = financials("ARCA", 105, "EQUITY");
+  value.quote = { ...value.quote!, stale: true, lastUpdated: 1 };
+  const provider = createTestDataProvider({ getTickerFinancials: async () => value, getQuote: async () => { throw new Error("Quote unavailable"); } });
+  try {
+    const result = await new AssetDataRouter(provider, [], store.resources).getTickerFinancials("TIP", "ARCA");
+    expect(result.quote).toBeUndefined();
+    expect(result.annualStatements[0]?.totalRevenue).toBe(666);
+  } finally { store.close(); }
+});

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

@@ -1,3 +1,5 @@
+import { sanitizeListingFinancialHistory } from "../listing-history";
+import { withdrawKnownProviderStatements } from "../../utils/statement-observations";
 import type {
   CachedFinancialsTarget,
   MarketDataRequestContext,
@@ -11,11 +13,15 @@ import { normalizeTickerFinancialsPriceHistory } from "../../utils/price-history
 import { isQuoteStaleForCurrentSession } from "../../market-data/quotes/freshness";
 import { resolveTickerFinancialsQuoteState } from "../../market-data/quotes/resolution";
 import { selectCachedResource } from "./cache";
+import { financialHistoryVariants } from "./statement-history";
 import {
   dropUnusableProviderQuote,
   hasDeepStatementHistory,
+  needsFinancialProfile,
+  hasRecentFinancialProfileAttempt,
   hasDetailedStatementRows,
   isProviderQuoteUsableForCurrentSession,
+  providerFinancialsMatchTarget,
   quoteWithFreshnessExchange,
   type CachedFinancialsSelection,
 } from "./financials";
@@ -39,7 +45,7 @@ export class ProviderRouterBatchRoutes {
   constructor(private readonly deps: ProviderRouterBatchDeps) {}
 
   private needsSingleFinancialsRoute(value: TickerFinancials): boolean {
-    return !(hasDetailedStatementRows(value) && hasDeepStatementHistory(value));
+    return !value.quote || needsFinancialProfile(value) || !(hasDetailedStatementRows(value) && hasDeepStatementHistory(value));
   }
 
   async getQuotesBatch(
@@ -60,7 +66,9 @@ export class ProviderRouterBatchRoutes {
         ...this.deps.getProviderSourceKeys(),
       ];
       const rawCached = selectCachedResource<Quote>(this.deps.resources, "quote", entityKey, variantKeys, sourceKeys, false);
-      const cached = rawCached && !isQuoteStaleForCurrentSession(quoteWithFreshnessExchange(rawCached.value, target.exchange))
+      const cached = rawCached && (brokerSourceKeys.includes(rawCached.sourceKey)
+        ? !isQuoteStaleForCurrentSession(quoteWithFreshnessExchange(rawCached.value, target.exchange))
+        : isProviderQuoteUsableForCurrentSession(rawCached.value, target.exchange, target.symbol))
         ? rawCached
         : null;
       if (cached && !forceRefresh && !cached.stale) {
@@ -87,7 +95,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)) continue;
+        if (!isProviderQuoteUsableForCurrentSession(item.quote, item.target.exchange, item.target.symbol)) continue;
         const key = this.quoteBatchKey(item.target);
         const sourceKey = this.deps.providerSourceKey(batchProvider);
         for (const entry of providerIndexes.get(key) ?? []) {
@@ -127,7 +135,11 @@ export class ProviderRouterBatchRoutes {
     targets.forEach((target, index) => {
       const context = this.deps.contextFromCachedTarget(target);
       const cached = this.deps.readCachedMergedFinancialsSelection(target.symbol, target.exchange, context, true);
-      if (cached.value && !forceRefresh) {
+      const profileAttempted = !cached.stale && hasRecentFinancialProfileAttempt(
+        this.deps.resources, this.deps.getEntityKey(target.symbol, context.instrument),
+        financialHistoryVariants(this.deps.getTickerVariantCandidates(target.exchange), context)[0] ?? "", this.deps.getProviderSourceKeys(),
+      );
+      if (cached.value?.quote && !forceRefresh && target.statementHistory !== "extended" && (!needsFinancialProfile(cached.value) || profileAttempted)) {
         results[index] = { target, financials: cached.value };
         return;
       }
@@ -135,7 +147,7 @@ export class ProviderRouterBatchRoutes {
     });
 
     const batchProvider = this.deps.providersInPriorityOrder().find((provider) => provider.getTickerFinancialsBatch);
-    const providerMisses = misses.filter(({ target }) => !this.deps.hasCachedTargetBrokerContext(target));
+    const providerMisses = misses.filter(({ target }) => target.statementHistory !== "extended" && !this.deps.hasCachedTargetBrokerContext(target));
     const providerIndexes = new Map<string, Array<{ index: number; target: CachedFinancialsTarget }>>();
     if (batchProvider && providerMisses.length > 0) {
       for (const entry of providerMisses) {
@@ -148,11 +160,15 @@ export class ProviderRouterBatchRoutes {
       const batchResults = await batchProvider.getTickerFinancialsBatch!(uniqueTargets, options).catch(() => []);
       for (const item of batchResults) {
         if (!item.financials) continue;
+        if (!item.target.instrument && !providerFinancialsMatchTarget(item.financials, item.target.symbol, item.target.exchange)) continue;
         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) continue;
         const sourceKey = this.deps.providerSourceKey(batchProvider);
+        value = sanitizeListingFinancialHistory(value, item.target, sourceKey);
+        value = withdrawKnownProviderStatements(value, item.target, sourceKey);
         for (const entry of providerIndexes.get(key) ?? []) {
           const entityKey = this.deps.getEntityKey(entry.target.symbol, entry.target.instrument ?? undefined);
           const variantKey = this.deps.getTickerVariantCandidates(entry.target.exchange)[0] ?? "";

package/src/sources/provider-router/broker-session.test.ts

@@ -0,0 +1,52 @@
+import { expect, spyOn, test } from "bun:test";
+import { AppPersistence } from "../../data/app-persistence";
+import type { Quote } from "../../types/financials";
+import { isQuoteStaleForCurrentSession } from "../../market-data/quotes/freshness";
+import { AssetDataRouter } from "./index";
+import { attachTestRegistry, brokerInstance, fallbackProvider, makeFinancials, setBrokerInstances } from "./test-support";
+
+test("broker price and provider session survive scalar, batch and cached financials composition", async () => {
+  for (const [time, marketState] of [["2026-04-08T11:00:00Z", "PRE"], ["2026-04-08T22:00:00Z", "POST"]] as const) {
+    const now = Date.parse(time);
+    const clock = spyOn(Date, "now").mockReturnValue(now);
+    const store = new AppPersistence(":memory:");
+    try {
+      const brokerQuote: Quote = { symbol: "AMD", providerId: "ibkr", dataSource: "live", price: 100.25,
+        currency: "USD", change: 1, changePercent: 1, lastUpdated: now - 60_000,
+        listingExchangeName: "NASDAQ", routingExchangeName: "SMART", sessionConfidence: "unknown" };
+      const yahoo: Quote = { ...brokerQuote, providerId: "yahoo", dataSource: "delayed", price: 99.7,
+        lastUpdated: now - 180_000, routingExchangeName: undefined, marketState, sessionConfidence: "derived",
+        ...(marketState === "PRE" ? { preMarketPrice: 101 } : { postMarketPrice: 102 }) };
+      let brokerCalls = 0;
+      const router = new AssetDataRouter({ ...fallbackProvider, id: "yahoo",
+        getQuote: async () => yahoo, getTickerFinancials: async () => makeFinancials({ quote: yahoo }) }, [], store.resources);
+      attachTestRegistry(router, { brokers: [["ibkr", {
+        id: "ibkr", name: "Test broker", configSchema: [], validate: async () => true, importPositions: async () => [],
+        getQuote: async () => { brokerCalls += 1; return brokerQuote; },
+        getTickerFinancials: async () => makeFinancials({ quote: { ...brokerQuote, price: 100 } }),
+      }]] });
+      setBrokerInstances(router, [brokerInstance()]);
+      const context = { brokerId: "ibkr", brokerInstanceId: "ibkr-work" };
+      const target = { symbol: "AMD", exchange: "NASDAQ", ...context };
+      function expectComposed(quote: Quote | undefined | null, price: number) {
+        expect(quote).toMatchObject({ price, lastUpdated: brokerQuote.lastUpdated, marketState, routingExchangeName: "SMART" });
+        expect(quote?.provenance).toMatchObject({ price: { providerId: "ibkr" }, session: { providerId: "yahoo" } });
+        expect(isQuoteStaleForCurrentSession(quote, now)).toBe(false);
+      }
+      expectComposed((await router.getTickerFinancials("AMD", "NASDAQ", context)).quote, 100);
+      expectComposed(router.getCachedFinancialsForTargets([target]).get("AMD")?.quote, 100);
+      expectComposed(await router.getQuote("AMD", "NASDAQ", context), 100.25);
+      expectComposed(await router.getQuote("AMD", "NASDAQ", context), 100.25);
+      expectComposed((await router.getQuotesBatch([{ symbol: "AMD", exchange: "NASDAQ", context }]))[0]?.quote, 100.25);
+      expect(brokerCalls).toBe(1);
+      expectComposed(router.getCachedFinancialsForTargets([target]).get("AMD")?.quote, 100.25);
+      brokerQuote.stale = true;
+      store.resources.set({ namespace: "market", kind: "quote", entityKey: "AMD", variantKey: "exchange=NASDAQ", sourceKey: "broker:ibkr:ibkr-work" }, brokerQuote,
+        { schemaVersion: 1, cachePolicy: { staleMs: 60_000, expireMs: 60_000 }, fetchedAt: now });
+      expect((await router.getQuote("AMD", "NASDAQ", context)).price).toBe(99.7);
+    } finally {
+      store.close();
+      clock.mockRestore();
+    }
+  }
+});

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

@@ -107,6 +107,7 @@ export function hasCachedTargetBrokerContext(target: CachedFinancialsTarget): bo
 
 export function contextFromCachedTarget(target: CachedFinancialsTarget): MarketDataRequestContext {
   return {
+    statementHistory: target.statementHistory,
     brokerId: target.brokerId,
     brokerInstanceId: target.brokerInstanceId,
     instrument: target.instrument ?? null,