gloomberb 0.13.2 → 0.14.0

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

@@ -0,0 +1,133 @@
+import { afterEach, expect, test } from "bun:test";
+import { AppPersistence } from "../../data/app-persistence";
+import { cacheRouterResource, listCachedResources } from "./cache";
+import { cleanupProviderRouterTestFiles, createTempDbPath, makeFinancials, makeQuote } from "./test-support";
+
+afterEach(cleanupProviderRouterTestFiles);
+
+test("legacy SEC EPS caches refresh for cloud and native without discarding unrelated resources", () => {
+  const persistence = new AppPersistence(createTempDbPath("eps-share-basis"));
+  const cachePolicy = { staleMs: 60_000, expireMs: 120_000 };
+  for (const sourceKey of ["provider:gloomberb-cloud", "provider:yahoo"]) {
+    const key = { namespace: "market", kind: "financials", entityKey: "AAPL", variantKey: "exchange=NASDAQ", sourceKey };
+    const old = makeFinancials({ annualStatements: [{ date: "2017-09-30", dateSource: "sec", eps: 9.21 }] });
+    persistence.resources.set(key, old, { cachePolicy, schemaVersion: 6 });
+    expect(listCachedResources(persistence.resources, "financials", "AAPL", [key.variantKey], [sourceKey], true)).toEqual([]);
+    const current = makeFinancials({ annualStatements: [{ date: "2017-09-30", dateSource: "sec", eps: 2.3025,
+      epsBasis: { status: "split-adjusted", source: "sec", originalValue: 9.21, basisDate: "2020-08-28", factor: 4, evidence: [] } }] });
+    cacheRouterResource(persistence.resources, "financials", "AAPL", key.variantKey, sourceKey, current, cachePolicy);
+    expect(listCachedResources(persistence.resources, "financials", "AAPL", [key.variantKey], [sourceKey], true)[0]!.value).toEqual(current);
+    persistence.resources.set({ ...key, entityKey: "MSFT" }, makeFinancials({ annualStatements: [{ date: "2025-06-30", totalRevenue: 100 }] }), { cachePolicy, schemaVersion: 6 });
+    expect(listCachedResources(persistence.resources, "financials", "MSFT", [key.variantKey], [sourceKey], true)).toHaveLength(1);
+  }
+  persistence.close();
+});
+
+test("legacy SEC income refreshes while vendor statements and repaired attribution survive cache roundtrips", () => {
+  const persistence = new AppPersistence(createTempDbPath("income-attribution"));
+  const cachePolicy = { staleMs: 60_000, expireMs: 120_000 };
+  for (const sourceKey of ["provider:gloomberb-cloud", "provider:yahoo"]) {
+    const key = { namespace: "market", kind: "financials", entityKey: "PLD", variantKey: "exchange=NYSE", sourceKey };
+    const old = makeFinancials({ annualStatements: [{ date: "2025-12-31", dateSource: "sec", netIncome: 120 }] });
+    const read = () => listCachedResources(persistence.resources, "financials", "PLD", [key.variantKey], [sourceKey], true);
+    persistence.resources.set(key, old, { cachePolicy, schemaVersion: 8 });
+    expect(read()).toEqual([]);
+    const vendor = makeFinancials({ annualStatements: [{ date: "2025-12-31", netIncome: 120 }] });
+    persistence.resources.set(key, vendor, { cachePolicy, schemaVersion: 8 });
+    expect(read()[0]!.value).toEqual(vendor);
+    const repaired = makeFinancials({ annualStatements: [{ date: "2025-12-31", dateSource: "sec", netIncomeIncludingNoncontrollingInterests: 120,
+      unavailableFields: ["netIncome"], fieldSources: { netIncomeIncludingNoncontrollingInterests: {
+        source: "sec", concept: "ProfitLoss", basis: "consolidated", unit: "USD", endDate: "2025-12-31", filed: "2026-02-01",
+      } } }] });
+    cacheRouterResource(persistence.resources, "financials", "PLD", key.variantKey, sourceKey, repaired, cachePolicy);
+    expect(read()[0]!.value).toEqual(repaired);
+  }
+  persistence.close();
+});
+
+test("legacy cloud yields refresh without discarding quotes, accounts or native provider values", () => {
+  const persistence = new AppPersistence(createTempDbPath("dividend-yield-provenance"));
+  const key = { namespace: "market", kind: "financials", entityKey: "NESN", variantKey: "exchange=SWX", sourceKey: "provider:gloomberb-cloud" };
+  const cachePolicy = { staleMs: 60_000, expireMs: 120_000 };
+  const old = makeFinancials({ quote: makeQuote({ symbol: "NESN", currency: "CHF" }),
+    fundamentals: { dividendYield: 0.16, revenue: 88775000064 }, profile: { description: "Nestle" },
+    annualStatements: [{ date: "2025-12-31", totalRevenue: 100 }] });
+  persistence.resources.set(key, old, { cachePolicy, schemaVersion: 4 });
+  persistence.resources.set({ ...key, sourceKey: "provider:yahoo" }, old, { cachePolicy, schemaVersion: 4 });
+  const read = (sourceKey = key.sourceKey) => listCachedResources(persistence.resources, "financials", "NESN", [key.variantKey], [sourceKey], true)[0]!;
+  const record = read(); const value = record.value as ReturnType<typeof makeFinancials>;
+  expect(record.stale).toBe(true);
+  expect(value.fundamentals?.dividendYield).toBeUndefined();
+  expect(value.quote).toEqual(old.quote);
+  expect(value.annualStatements).toEqual(old.annualStatements);
+  expect(value.fundamentals?.revenue).toBe(88775000064);
+  expect((read("provider:yahoo").value as ReturnType<typeof makeFinancials>).fundamentals?.dividendYield).toBe(0.16);
+  // A new client can cache an old backend response during a rolling deploy.
+  cacheRouterResource(persistence.resources, "financials", "NESN", key.variantKey, key.sourceKey, old, cachePolicy);
+  expect(read().schemaVersion).toBe(9);
+  expect(read().stale).toBe(true);
+  expect((read().value as ReturnType<typeof makeFinancials>).fundamentals?.dividendYield).toBeUndefined();
+  expect((read().value as ReturnType<typeof makeFinancials>).quote).toEqual(old.quote);
+  const corrected = { ...old, fundamentals: { ...old.fundamentals, dividendYield: 0.0399, dividendYieldBasis: "forward" as const, dividendYieldSource: "yahoo" as const } };
+  cacheRouterResource(persistence.resources, "financials", "NESN", key.variantKey, key.sourceKey, corrected, cachePolicy);
+  expect(read().schemaVersion).toBe(9);
+  expect(read().stale).toBe(false);
+  expect(read().value).toEqual(corrected);
+  persistence.close();
+});
+
+test("legacy cloud financial caches retain statements but refresh quotes whose freshness was lost", () => {
+  const persistence = new AppPersistence(createTempDbPath("nested-quote-freshness"));
+  const key = { namespace: "market", kind: "financials", entityKey: "7203", variantKey: "exchange=TYO", sourceKey: "provider:gloomberb-cloud" };
+  const cachePolicy = { staleMs: 60_000, expireMs: 120_000 };
+  const old = makeFinancials({ quote: makeQuote({ symbol: "7203", currency: "JPY", price: 2980.5, providerId: "gloomberb-cloud" }),
+    annualStatements: [{ date: "2026-03-31", totalRevenue: 100, fieldAvailability: { totalRevenue: "2026-05-08" } }],
+  });
+  persistence.resources.set(key, old, { cachePolicy, schemaVersion: 3 });
+  const quote = makeQuote({ symbol: "7203", currency: "JPY", price: 2994, providerId: "yahoo" });
+  persistence.resources.set({ ...key, kind: "quote", sourceKey: "provider:yahoo" }, quote, { cachePolicy });
+  const read = () => listCachedResources(persistence.resources, "financials", "7203", [key.variantKey], [key.sourceKey], true)[0]!.value as ReturnType<typeof makeFinancials>;
+  expect(read().quote).toBeUndefined();
+  expect(read().annualStatements).toEqual(old.annualStatements);
+  expect(listCachedResources(persistence.resources, "quote", "7203", [key.variantKey], ["provider:yahoo"], true)[0]!.value).toEqual(quote);
+  cacheRouterResource(persistence.resources, "financials", "7203", key.variantKey, key.sourceKey, { ...old, quote: { ...old.quote!, stale: true } }, cachePolicy);
+  expect(read().quote?.stale).toBe(true);
+  persistence.close();
+});
+
+test("refreshes legacy SEC annual caches without discarding unrelated data and accepts repaired writes", () => {
+  const persistence = new AppPersistence(createTempDbPath("sec-annual-cache-version"));
+  const key = { namespace: "market", kind: "financials", entityKey: "COST", variantKey: "exchange=NASDAQ", sourceKey: "provider:yahoo" };
+  const cachePolicy = { staleMs: 60_000, expireMs: 120_000 };
+  const legacy = makeFinancials({ annualStatements: [{ date: "2017-09-03", netIncome: 919_000_000, fieldAvailability: { netIncome: "2017-10-18" } }] });
+  persistence.resources.set(key, legacy, { cachePolicy });
+  persistence.resources.set({ ...key, sourceKey: "provider:gloomberb-cloud" }, makeFinancials({ annualStatements: [{ date: "2025-08-31", netIncome: 8_099_000_000 }] }), { cachePolicy });
+  persistence.resources.set({ ...key, kind: "quote" }, makeQuote({ symbol: "COST" }), { cachePolicy });
+  const read = (kind: string) => listCachedResources(persistence.resources, kind, "COST", ["exchange=NASDAQ"], ["provider:yahoo", "provider:gloomberb-cloud"], true);
+  expect(read("financials").map((row) => row.sourceKey)).toEqual(["provider:gloomberb-cloud"]);
+  expect(read("quote")).toHaveLength(1);
+
+  const repaired = makeFinancials({ annualStatements: [{ date: "2017-09-03", netIncome: 2_679_000_000, fieldAvailability: { netIncome: "2017-10-18" } }] });
+  cacheRouterResource(persistence.resources, "financials", "COST", key.variantKey, key.sourceKey, repaired, cachePolicy);
+  expect(read("financials").find((row) => row.sourceKey === "provider:yahoo")?.value).toEqual(repaired);
+  persistence.close();
+});
+
+test("refreshes schema-two quarterly availability while retaining undated statements and unrelated cached data", () => {
+  const persistence = new AppPersistence(createTempDbPath("field-availability-cache-version"));
+  const key = { namespace: "market", kind: "financials", entityKey: "MSFT", variantKey: "exchange=NASDAQ", sourceKey: "provider:yahoo" };
+  const cachePolicy = { staleMs: 60_000, expireMs: 120_000 };
+  const unsafe = makeFinancials({ annualStatements: [], quarterlyStatements: [{ date: "2025-12-31", totalRevenue: 100, grossProfit: 40,
+    availableAt: "2026-04-01", fieldAvailability: { totalRevenue: "2026-04-01", grossProfit: "2026-02-01" } }] });
+  persistence.resources.set(key, unsafe, { cachePolicy, schemaVersion: 2 });
+  persistence.resources.set({ ...key, sourceKey: "provider:gloomberb-cloud" }, makeFinancials({ annualStatements: [], quarterlyStatements: [{ date: "2025-12-31", totalRevenue: 100 }] }), { cachePolicy, schemaVersion: 2 });
+  persistence.resources.set({ ...key, kind: "quote" }, makeQuote({ symbol: "MSFT" }), { cachePolicy, schemaVersion: 2 });
+  const read = (kind: string) => listCachedResources(persistence.resources, kind, "MSFT", [key.variantKey], [key.sourceKey, "provider:gloomberb-cloud"], true);
+  expect(read("financials").map((row) => row.sourceKey)).toEqual(["provider:gloomberb-cloud"]);
+  expect(read("quote")).toHaveLength(1);
+  const repaired = makeFinancials({ annualStatements: [], quarterlyStatements: [{ date: "2025-12-31", totalRevenue: 100, grossProfit: 40,
+    fieldAvailability: { grossProfit: "2026-02-01" } }] });
+  cacheRouterResource(persistence.resources, "financials", "MSFT", key.variantKey, key.sourceKey, repaired, cachePolicy);
+  expect(read("financials").find((record) => record.sourceKey === key.sourceKey)?.value).toEqual(repaired);
+  persistence.close();
+});

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

@@ -1,12 +1,19 @@
+import { yahooSuffixExchange } from "../yahoo-finance/symbols";
 import type { CachedResourceRecord, ResourceStore } from "../../data/resource-store";
 import type { TimeRange } from "../../time-series/range";
 import type { BrokerContractRef } from "../../types/instrument";
-import type { PricePoint } from "../../types/financials";
+import type { PricePoint, Quote, TickerFinancials } from "../../types/financials";
+import { retractKnownCloudValuation } from "../gloomberb-cloud/valuation-observations";
+import { withdrawKnownProviderStatements } from "../../utils/statement-observations";
 import type { CachePolicy, CachePolicyMap } from "../../types/persistence";
-import { canonicalExchange } from "../../utils/exchanges";
+import { canonicalExchange, parsePublicTickerKey, resolveExchangeTimeZone } from "../../utils/exchanges";
+import { redactUnavailableFundamentals, RETRACTABLE_VALUATION_FIELDS } from "../../utils/fundamentals";
 import { isPriceHistoryStaleForCurrentWindow } from "../../utils/price-history";
+import { brokerContractIdentityKey } from "../../utils/instrument-identity";
 
 const MARKET_NAMESPACE = "market";
+const FINANCIALS_SCHEMA_VERSION = 9;
+const QUOTE_SCHEMA_VERSION = 2;
 
 const DEFAULT_CACHE_POLICIES = {
   brokerQuote: { staleMs: 15_000, expireMs: 15 * 60_000 },
@@ -48,10 +55,12 @@ export function buildVariantKey(parts: Array<[string, string | number | undefine
 }
 
 export function getRouterEntityKey(ticker: string, instrument?: BrokerContractRef | null): string {
-  if (instrument?.conId != null) return `contract:${instrument.conId}`;
-  if (instrument?.localSymbol) return `contract:${instrument.localSymbol.toUpperCase()}`;
-  if (instrument?.symbol) return `contract:${instrument.symbol.toUpperCase()}`;
-  return normalizeTicker(ticker);
+  if (instrument) return `contract:${brokerContractIdentityKey(instrument)}`;
+  const target = parsePublicTickerKey(ticker);
+  const suffixExchange = !target.exchange && yahooSuffixExchange(target.symbol);
+  // Earlier bare-suffix caches may have parsed dates using unrelated exchange
+  // metadata or UTC. A qualified entity bypasses those records on upgrade.
+  return suffixExchange ? `${target.symbol}:${suffixExchange}` : normalizeTicker(ticker);
 }
 
 export function getTickerVariantCandidates(exchange?: string): string[] {
@@ -66,8 +75,8 @@ export function isIntradayRange(range: TimeRange): boolean {
   return range === "1D" || range === "1W" || range === "1M" || range === "3M";
 }
 
-export function isStaleIntradayHistory(points: PricePoint[], enabled: boolean, exchange?: string): boolean {
-  return enabled && isPriceHistoryStaleForCurrentWindow(points, Date.now(), { exchange });
+export function isStaleIntradayHistory(points: PricePoint[], enabled: boolean, exchange?: string, intervalMs?: number | null): boolean {
+  return enabled && isPriceHistoryStaleForCurrentWindow(points, Date.now(), { exchange, intervalMs });
 }
 
 export function isCurrentHistoryWindow(endDate?: Date): boolean {
@@ -103,6 +112,8 @@ export function cacheRouterResource<T>(
     value,
     {
       cachePolicy,
+      ...(kind === "financials" ? { schemaVersion: FINANCIALS_SCHEMA_VERSION } : {}),
+      ...(kind === "quote" ? { schemaVersion: QUOTE_SCHEMA_VERSION } : {}),
     },
   );
 }
@@ -125,6 +136,24 @@ export function sortCachedRecords<T>(
   });
 }
 
+function hasUnverifiedLegacyAsmlValuation(record: CachedResourceRecord, value: TickerFinancials): boolean {
+  if (record.schemaVersion >= 6 || !RETRACTABLE_VALUATION_FIELDS.some((field) => value.fundamentals?.[field] != null)) return false;
+  const target = parsePublicTickerKey(record.entityKey);
+  const quote = parsePublicTickerKey(value.quote?.symbol ?? "");
+  if (![target.symbol, quote.symbol].some((symbol) => symbol === "ASML" || symbol === "ASML.AS")) return false;
+  const requested = target.exchange || (target.symbol === "ASML.AS" ? "AMS" : "")
+    || canonicalExchange(record.variantKey.match(/(?:^|;)exchange=([^;]+)/)?.[1]);
+  const rawListing = value.quote?.listingExchangeName || value.quote?.exchangeName || quote.exchange;
+  const listing = canonicalExchange(rawListing);
+  // Only corroborated non-US listings may retain their legacy valuation.
+  // A requested venue alone does not prove which listing supplied old data.
+  const verifiedForeign = ["ASML", "ASML.AS"].includes(quote.symbol) && resolveExchangeTimeZone(listing)
+    && rawListing?.trim().toUpperCase() !== "EURONEXT" && !["NASDAQ", "NYSE", "AMEX", "ARCA"].includes(listing)
+    && (!requested || requested === listing) && (!quote.exchange || quote.exchange === listing) && !!value.quote?.currency
+    && (listing !== "AMS" || value.quote.currency === "EUR");
+  return !verifiedForeign;
+}
+
 export function listCachedResources<T>(
   resources: ResourceStore | undefined,
   kind: string,
@@ -142,6 +171,82 @@ export function listCachedResources<T>(
     variantKeys,
     sourceKeys,
     allowExpired,
+  }).filter((record) => {
+    if (record.sourceKey.startsWith("provider:") && !entityKey.startsWith("contract:")
+      && (kind === "financials" || kind === "quote")) {
+      const requestedExchange = parsePublicTickerKey(entityKey).exchange
+        || canonicalExchange(variantKeys.find((key) => /(?:^|;)exchange=/.test(key))?.match(/(?:^|;)exchange=([^;]+)/)?.[1]);
+      const quote = kind === "quote" ? record.value as Quote : (record.value as TickerFinancials).quote;
+      const metadata = kind === "financials" ? (record.value as TickerFinancials).quoteMetadata : undefined;
+      const declaredExchange = canonicalExchange(quote?.listingExchangeName || quote?.exchangeName
+        || metadata?.listingExchangeName || parsePublicTickerKey(quote?.symbol ?? metadata?.symbol ?? "").exchange);
+      // Generic legacy entries can retain a venue normalized under old alias
+      // rules (PCX used to mean AMEX). Refetch a conflicting public listing;
+      // never relabel it or let it outrank a fresh exact-listing response.
+      if (requestedExchange && declaredExchange && requestedExchange !== declaredExchange) return false;
+      // An unqualified lookup cannot tell real AMEX metadata from old PCX
+      // normalization. Refresh only those legacy records; newly verified
+      // AMEX data and explicitly requested AMEX listings remain reusable.
+      if (!requestedExchange && declaredExchange === "AMEX"
+        && record.schemaVersion < (kind === "financials" ? 8 : 2)) return false;
+    }
+    // Earlier SEC projections used consolidated/common income as parent income.
+    // Refetch the filing evidence; unrelated vendor statements remain usable.
+    if (kind === "financials" && record.schemaVersion < 9) {
+      const value = record.value as TickerFinancials;
+      if ([...(value.annualStatements ?? []), ...(value.quarterlyStatements ?? [])]
+        .some((row) => row.dateSource === "sec"
+          && (row.netIncome !== undefined || row.netIncomeCommonStockholders !== undefined))) return false;
+    }
+    // Older SEC projections can mix pre/post-split EPS in one long history.
+    // Refresh the source evidence instead of relabeling old numbers locally.
+    if (kind === "financials" && record.schemaVersion < 7) {
+      const value = record.value as TickerFinancials;
+      if ([...(value.annualStatements ?? []), ...(value.quarterlyStatements ?? [])]
+        .some((row) => row.dateSource === "sec" && row.eps !== undefined)) return false;
+    }
+    if (kind !== "financials" || record.schemaVersion >= 3) return true;
+    // Earlier merges could date unknown fields from a partial availability map,
+    // in addition to the older SEC annual/concept errors. Cached dates cannot
+    // distinguish inferred metadata from source evidence; refresh dated rows.
+    // Unrelated quote/history/company and undated financial caches remain usable.
+    const value = record.value as TickerFinancials;
+    return ![...(value.annualStatements ?? []), ...(value.quarterlyStatements ?? [])]
+      .some((row) => row.availableAt || Object.keys(row.fieldAvailability ?? {}).length > 0);
+  }).map((record) => {
+    if (kind === "financials") {
+      const financials = record.value as TickerFinancials;
+      const ownSymbol = financials.quote?.symbol ?? financials.quoteMetadata?.symbol;
+      const withdrawn = withdrawKnownProviderStatements(financials, {
+        symbol: record.entityKey.startsWith("contract:") ? ownSymbol ?? "" : record.entityKey,
+        exchange: record.variantKey.match(/(?:^|;)exchange=([^;]+)/)?.[1],
+      }, record.sourceKey);
+      if (withdrawn !== record.value) record = { ...record, stale: true, value: withdrawn as T };
+    }
+    if (kind !== "financials" || record.sourceKey !== "provider:gloomberb-cloud") return record;
+    // Legacy cloud aggregates lost the nested quote's stale flag. Retain valid
+    // issuer data, but obtain the quote through its independent freshness route.
+    let value = record.value as TickerFinancials;
+    const retracted = retractKnownCloudValuation(value, {
+      symbol: record.entityKey,
+      exchange: record.variantKey.match(/(?:^|;)exchange=([^;]+)/)?.[1],
+    });
+    const knownInvalidValuation = retracted !== value;
+    value = retracted;
+    const legacyValuation = hasUnverifiedLegacyAsmlValuation(record, value);
+    if (record.schemaVersion < 4) value = { ...value, quote: undefined, quoteContributions: undefined };
+    // A new client can cache an old backend response during a rolling deploy.
+    // Require the metric's own provenance as well as the cache schema before
+    // reusing a cloud yield; retain valid quotes and other issuer data.
+    const statistics = value.fundamentals;
+    const hasDividendProvenance = ["forward", "trailing"].includes(statistics?.dividendYieldBasis ?? "")
+      && ["twelvedata", "yahoo"].includes(statistics?.dividendYieldSource ?? "");
+    const legacyYield = statistics?.dividendYield != null && (record.schemaVersion < 5 || !hasDividendProvenance);
+    if (legacyYield) value = { ...value, fundamentals: { ...value.fundamentals,
+      dividendYield: undefined, dividendYieldBasis: undefined, dividendYieldSource: undefined } };
+    if (legacyValuation) value = { ...value, fundamentals: redactUnavailableFundamentals({ ...value.fundamentals,
+      unavailableFields: [...RETRACTABLE_VALUATION_FIELDS] }) };
+    return { ...record, stale: record.stale || legacyYield || legacyValuation || knownInvalidValuation, value: value as T };
   });
   if (records.length === 0) return [];
 

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

@@ -1,7 +1,9 @@
-import { afterEach, describe, expect, test } from "bun:test";
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
 import { AppPersistence } from "../../data/app-persistence";
 import type { DataProvider } from "../../types/data-provider";
 import { AssetDataRouter } from "./index";
+import { getRouterEntityKey } from "./cache";
+import { mergeFinancials, sanitizeCachedFinancials } from "./financials";
 import {
   cleanupProviderRouterTestFiles,
   createTempDbPath,
@@ -10,10 +12,62 @@ import {
   makeQuote,
 } from "./test-support";
 
+let clock: ReturnType<typeof spyOn> | undefined;
+// These price-only fixtures describe regular trading; explicit freshness tests override it.
+beforeEach(() => { clock = spyOn(Date, "now").mockReturnValue(Date.parse("2026-09-14T18:00:00Z")); });
 afterEach(() => {
+  clock?.mockRestore();
+  clock = undefined;
   cleanupProviderRouterTestFiles();
 });
 
+test("confirmed fund classification prevents cached company accounts from returning after merge", () => {
+  const now = Date.now();
+  const fund = makeFinancials({ quote: makeQuote({ symbol: "IWDA.L", providerId: "gloomberb-cloud", instrumentType: "ETF", currency: "USD", lastUpdated: now }) });
+  const contaminated = makeFinancials({
+    quote: makeQuote({ symbol: "IWDA.L", providerId: "yahoo", currency: "USD", lastUpdated: now - 1000 }),
+    fundamentals: { trailingPE: 0.238, revenue: 0 }, profile: { industry: "Specialty Chemicals" },
+    annualStatements: [{ date: "2025-12-31", totalRevenue: 0 }],
+  });
+  const merged = mergeFinancials(fund, contaminated)!;
+  expect(merged.quote?.instrumentType).toBe("ETF");
+  expect(merged.fundamentals).toBeUndefined();
+  expect(merged.profile).toBeUndefined();
+  expect(merged.annualStatements).toEqual([]);
+  expect(sanitizeCachedFinancials({ ...contaminated, quote: fund.quote }, { includeStaleQuotes: true }).fundamentals).toBeUndefined();
+  expect(mergeFinancials(contaminated, null)?.fundamentals?.trailingPE).toBe(0.238);
+});
+
+test("fund research keeps distribution yield and description through cache and merge boundaries", () => {
+  const now = Date.now();
+  const fund = makeFinancials({
+    quote: makeQuote({ symbol: "SGOV", providerId: "gloomberb-cloud", instrumentType: "ETF", lastUpdated: now }),
+    fundamentals: { dividendYield: 0.036658540225881886, dividendYieldBasis: "forward", dividendYieldSource: "twelvedata", source: "twelvedata", fetchedAt: "2026-09-10T22:30:00Z", stale: true,
+      enterpriseValue: 0, revenue: 0, netIncome: 0, freeCashFlow: 0 },
+    profile: { description: "Short Treasury bond fund", sector: "Contaminated issuer sector" },
+    annualStatements: [{ date: "2025-12-31", totalRevenue: 0 }],
+  });
+  for (const value of [sanitizeCachedFinancials(fund, { includeStaleQuotes: true }), mergeFinancials(fund, null)!]) {
+    expect(value.fundamentals).toEqual({ dividendYield: 0.036658540225881886, dividendYieldBasis: "forward", dividendYieldSource: "twelvedata", source: "twelvedata", fetchedAt: "2026-09-10T22:30:00Z", stale: true });
+    expect(value.profile).toEqual({ description: "Short Treasury bond fund" });
+    expect(value.annualStatements).toEqual([]);
+  }
+  const company = makeFinancials({
+    quote: makeQuote({ symbol: "SGOV", providerId: "yahoo", instrumentType: "EQUITY", lastUpdated: now - 1000 }),
+    fundamentals: { dividendYield: 0.99, revenue: 0 }, profile: { description: "Wrong company" },
+  });
+  const emptyFund = makeFinancials({ quote: fund.quote });
+  for (const value of [mergeFinancials(emptyFund, company)!, mergeFinancials(company, emptyFund)!]) {
+    expect(value.quote?.instrumentType).toBe("ETF");
+    expect(value.fundamentals).toBeUndefined();
+    expect(value.profile).toBeUndefined();
+  }
+  expect(mergeFinancials(fund, company)?.profile?.description).toBe("Short Treasury bond fund");
+  expect(mergeFinancials(company, null)?.fundamentals?.revenue).toBe(0);
+  expect(sanitizeCachedFinancials({ ...fund, fundamentals: { dividendYield: 0 } }, { includeStaleQuotes: true }).fundamentals?.dividendYield).toBe(0);
+  expect(sanitizeCachedFinancials({ ...fund, quote: { ...fund.quote!, instrumentType: "INDEX" } }, { includeStaleQuotes: true }).profile).toBeUndefined();
+});
+
 describe("AssetDataRouter cached financials", () => {
   test("drops stale cached cloud quotes while preserving cached cloud fundamentals", () => {
     const dbPath = createTempDbPath("stale-cloud-cached-financials");
@@ -51,6 +105,7 @@ describe("AssetDataRouter cached financials", () => {
         },
       }),
       {
+        schemaVersion: 4,
         cachePolicy: { staleMs: 60_000, expireMs: 60_000 },
         fetchedAt: now,
       },
@@ -79,6 +134,7 @@ describe("AssetDataRouter cached financials", () => {
         }),
       }),
       {
+        schemaVersion: 4,
         cachePolicy: { staleMs: 60_000, expireMs: 60_000 },
         fetchedAt: now,
       },
@@ -115,6 +171,7 @@ describe("AssetDataRouter cached financials", () => {
   });
 
   test("drops cached premarket cloud quotes that lack an active-session price", () => {
+    clock = spyOn(Date, "now").mockReturnValue(Date.parse("2026-09-14T11:00:00Z"));
     const dbPath = createTempDbPath("stale-cloud-premarket-cache");
     const persistence = new AppPersistence(dbPath);
     const now = Date.now();
@@ -142,6 +199,7 @@ describe("AssetDataRouter cached financials", () => {
         }),
       }),
       {
+        schemaVersion: 4,
         cachePolicy: { staleMs: 60_000, expireMs: 60_000 },
         fetchedAt: now,
       },
@@ -172,6 +230,7 @@ describe("AssetDataRouter cached financials", () => {
         }),
       }),
       {
+        schemaVersion: 4,
         cachePolicy: { staleMs: 60_000, expireMs: 60_000 },
         fetchedAt: now,
       },
@@ -236,6 +295,7 @@ describe("AssetDataRouter cached financials", () => {
         },
       }),
       {
+        schemaVersion: 4,
         cachePolicy: { staleMs: 60_000, expireMs: 60_000 },
         fetchedAt: now,
       },
@@ -264,7 +324,7 @@ describe("AssetDataRouter cached financials", () => {
     persistence.close();
   });
 
-  test("derives cached market cap from quote price and shares outstanding", () => {
+  test("does not fabricate market cap from an unverified shares basis", () => {
     const dbPath = createTempDbPath("cached-derived-market-cap");
     const persistence = new AppPersistence(dbPath);
     const now = Date.now();
@@ -295,6 +355,7 @@ describe("AssetDataRouter cached financials", () => {
         },
       }),
       {
+        schemaVersion: 4,
         cachePolicy: { staleMs: 60_000, expireMs: 60_000 },
         fetchedAt: now,
       },
@@ -313,12 +374,12 @@ describe("AssetDataRouter cached financials", () => {
       allowExpired: true,
       includeStaleQuotes: true,
     });
-    expect(cached.get("AMD")?.quote?.marketCap).toBeCloseTo(725_969_400_000);
+    expect(cached.get("AMD")?.quote?.marketCap).toBeUndefined();
 
     persistence.close();
   });
 
-  test("uses symbol provider cache for broker-linked startup targets", () => {
+  test("keeps contract-owned prices separate from symbol-only startup enrichment", () => {
     const dbPath = createTempDbPath("cached-symbol-fallback-for-contract");
     const persistence = new AppPersistence(dbPath);
     const now = Date.now();
@@ -347,6 +408,7 @@ describe("AssetDataRouter cached financials", () => {
         }),
       }),
       {
+        schemaVersion: 4,
         cachePolicy: { staleMs: 60_000, expireMs: 7 * 24 * 60 * 60_000 },
         fetchedAt: old,
       },
@@ -355,7 +417,7 @@ describe("AssetDataRouter cached financials", () => {
       {
         namespace: "market",
         kind: "financials",
-        entityKey: "4092.T",
+        entityKey: getRouterEntityKey("4092.T"),
         variantKey: "exchange=JPX",
         sourceKey: "provider:yahoo",
       },
@@ -372,8 +434,10 @@ describe("AssetDataRouter cached financials", () => {
           exchangeName: "JPX",
           listingExchangeName: "JPX",
         }),
+        fundamentals: { revenue: 1234 },
       }),
       {
+        schemaVersion: 4,
         cachePolicy: { staleMs: 60_000, expireMs: 7 * 24 * 60 * 60_000 },
         fetchedAt: now,
       },
@@ -399,13 +463,20 @@ describe("AssetDataRouter cached financials", () => {
       },
     }], { allowExpired: true, includeStaleQuotes: true });
 
-    expect(cached.get("4092.T")?.quote?.price).toBe(3925);
-    expect(cached.get("4092.T")?.quote?.changePercent).toBe(0.51);
+    expect(cached.get("4092.T")?.quote?.price).toBe(3770);
+    expect(cached.get("4092.T")?.quote?.changePercent).toBe(4);
+    expect(cached.get("4092.T")?.quote?.lastUpdated).toBe(old);
+    expect(cached.get("4092.T")?.fundamentals?.revenue).toBe(1234);
+    const publicCached = router.getCachedFinancialsForTargets([{ symbol: "4092.T", exchange: "JPX" }], {
+      allowExpired: true, includeStaleQuotes: true,
+    });
+    expect(publicCached.get("4092.T")?.quote?.price).toBe(3925);
+    expect(publicCached.get("4092.T")?.quote?.changePercent).toBe(0.51);
 
     persistence.close();
   });
 
-  test("uses symbol provider quote reference for broker-linked snapshot reads", async () => {
+  test("requires exact contract identity for cached quote reference enrichment", async () => {
     const dbPath = createTempDbPath("cached-symbol-reference-for-contract-snapshot");
     const persistence = new AppPersistence(dbPath);
     const now = Date.now();
@@ -441,6 +512,7 @@ describe("AssetDataRouter cached financials", () => {
         },
       }),
       {
+        schemaVersion: 4,
         cachePolicy: { staleMs: 60_000, expireMs: 7 * 24 * 60 * 60_000 },
         fetchedAt: now,
       },
@@ -457,6 +529,7 @@ describe("AssetDataRouter cached financials", () => {
         annualStatements: [{ date: "2025-12-31", totalRevenue: 100 }],
       }),
       {
+        schemaVersion: 4,
         cachePolicy: { staleMs: 60_000, expireMs: 7 * 24 * 60 * 60_000 },
         fetchedAt: now + 1_000,
       },
@@ -486,6 +559,7 @@ describe("AssetDataRouter cached financials", () => {
         }),
       }),
       {
+        schemaVersion: 4,
         cachePolicy: { staleMs: 60_000, expireMs: 7 * 24 * 60 * 60_000 },
         fetchedAt: now - 1_000,
       },
@@ -508,7 +582,7 @@ describe("AssetDataRouter cached financials", () => {
       },
     }], persistence.resources);
 
-    const financials = await router.getTickerFinancials("VICR", "NASDAQ", {
+    const context = {
       brokerId: "ibkr",
       brokerInstanceId: "ibkr-work",
       instrument: {
@@ -517,13 +591,27 @@ describe("AssetDataRouter cached financials", () => {
         conId: 275759,
         symbol: "VICR",
       },
-    });
+    };
+    const financials = await router.getTickerFinancials("VICR", "NASDAQ", context);
 
     expect(financials.quote?.providerId).toBe("gloomberb-cloud");
     expect(financials.quote?.price).toBe(292.83);
-    expect(financials.quote?.previousClose).toBe(282.95);
-    expect(financials.quote?.changePercent).toBeCloseTo(((292.83 - 282.95) / 282.95) * 100, 10);
-    expect(financials.quote?.provenance?.fields?.previousClose?.providerId).toBe("yahoo");
+    expect(financials.quote?.previousClose).toBe(380.07);
+    expect(financials.quote?.changePercent).toBeCloseTo(((292.83 - 380.07) / 380.07) * 100, 10);
+    expect(financials.quote?.provenance?.fields?.previousClose?.providerId).toBe("gloomberb-cloud");
+
+    // A reference captured for this exact target can still enrich its quote.
+    const referenceKey = { namespace: "market", kind: "financials", entityKey: "VICR",
+      variantKey: "exchange=NASDAQ", sourceKey: "provider:yahoo" };
+    const reference = persistence.resources.get<ReturnType<typeof makeFinancials>>(referenceKey)!.value;
+    persistence.resources.set({ ...referenceKey, entityKey: "contract:275759" }, reference, {
+      schemaVersion: 4, cachePolicy: { staleMs: 60_000, expireMs: 7 * 24 * 60 * 60_000 }, fetchedAt: now,
+    });
+    const exact = await router.getTickerFinancials("VICR", "NASDAQ", context);
+    expect(exact.quote?.price).toBe(292.83);
+    expect(exact.quote?.previousClose).toBe(282.95);
+    expect(exact.quote?.changePercent).toBeCloseTo(((292.83 - 282.95) / 282.95) * 100, 10);
+    expect(exact.quote?.provenance?.fields?.previousClose?.providerId).toBe("yahoo");
 
     persistence.close();
   });
@@ -561,6 +649,7 @@ describe("AssetDataRouter cached financials", () => {
         },
       }),
       {
+        schemaVersion: 4,
         cachePolicy: { staleMs: 60_000, expireMs: 7 * 24 * 60 * 60_000 },
         fetchedAt: old,
       },
@@ -586,6 +675,7 @@ describe("AssetDataRouter cached financials", () => {
         listingExchangeName: "JPX",
       }),
       {
+        schemaVersion: 4,
         cachePolicy: { staleMs: 60_000, expireMs: 7 * 24 * 60 * 60_000 },
         fetchedAt: now,
       },
@@ -613,7 +703,7 @@ describe("AssetDataRouter cached financials", () => {
 
     expect(cached.get("6315.T")?.quote?.price).toBe(2688);
     expect(cached.get("6315.T")?.quote?.changePercent).toBe(0.49);
-    expect(cached.get("6315.T")?.quote?.marketCap).toBe(201_601_241_856);
+    expect(cached.get("6315.T")?.quote?.marketCap).toBeUndefined();
     expect(cached.get("6315.T")?.fundamentals?.trailingPE).toBe(37.2);
 
     persistence.close();