gloomberb 0.13.2 → 0.14.0

package/src/utils/exchanges.ts

@@ -4,6 +4,7 @@ export const CANONICAL_EXCHANGE_ALIASES: Record<string, string> = {
   XNAS: "NASDAQ",
   NMS: "NASDAQ",
   NGM: "NASDAQ",
+  NASDAQGM: "NASDAQ",
   NCM: "NASDAQ",
   NYQ: "NYSE",
   NYS: "NYSE",
@@ -12,7 +13,9 @@ export const CANONICAL_EXCHANGE_ALIASES: Record<string, string> = {
   ASE: "AMEX",
   AMEX: "AMEX",
   XASE: "AMEX",
-  PCX: "AMEX",
+  PCX: "ARCA",
+  NYSEARCA: "ARCA",
+  "NYSE ARCA": "ARCA",
   ARCA: "ARCA",
   ARCX: "ARCA",
   BATS: "BATS",
@@ -32,9 +35,11 @@ export const CANONICAL_EXCHANGE_ALIASES: Record<string, string> = {
   TSX: "TSX",
   XTSE: "TSX",
   TSXV: "TSXV",
+  XTSX: "TSXV",
   VAN: "TSXV",
   CN: "CSE",
   CNSX: "CSE",
+  XCNQ: "CSE",
   CSE: "CSE",
   ASX: "ASX",
   XASX: "ASX",
@@ -243,20 +248,26 @@ export function parsePublicTickerKey(value: string): { symbol: string; exchange?
   const normalized = normalizeSymbol(value);
   const separator = normalized.lastIndexOf(":");
   if (separator <= 0 || separator === normalized.length - 1) return { symbol: normalized };
-  return {
-    symbol: normalized.slice(0, separator),
-    exchange: canonicalExchange(normalized.slice(separator + 1)),
-  };
+  const exchange = canonicalExchange(normalized.slice(separator + 1));
+  let symbol = normalized.slice(0, separator);
+  // Older callers could append the same exchange more than once. Repair only
+  // repeated aliases of that exchange, preserving any other symbol content.
+  for (let nested = symbol.lastIndexOf(":"); nested > 0; nested = symbol.lastIndexOf(":")) {
+    if (canonicalExchange(symbol.slice(nested + 1)) !== exchange) break;
+    symbol = symbol.slice(0, nested);
+  }
+  return { symbol, exchange };
 }
 
 export function canonicalTickerKey(symbol: string, exchange?: string): string {
-  const normalizedSymbol = normalizeSymbol(symbol);
-  const canonical = canonicalExchange(exchange);
-  return canonical ? `${normalizedSymbol}:${canonical}` : normalizedSymbol;
+  const parsed = parsePublicTickerKey(symbol);
+  // An explicit listing in the symbol wins over remembered/default metadata.
+  const canonical = parsed.exchange ?? canonicalExchange(exchange);
+  return canonical ? `${parsed.symbol}:${canonical}` : parsed.symbol;
 }
 
 export function publicTickerKey(symbol: string, exchange?: string): string {
-  const normalizedSymbol = normalizeSymbol(symbol);
-  const publicValue = publicExchange(exchange);
-  return publicValue ? `${normalizedSymbol}:${publicValue}` : normalizedSymbol;
+  const parsed = parsePublicTickerKey(symbol);
+  const publicValue = publicExchange(parsed.exchange ?? exchange);
+  return publicValue ? `${parsed.symbol}:${publicValue}` : parsed.symbol;
 }

package/src/utils/financial-statements.test.ts

@@ -1,7 +1,48 @@
 import { describe, expect, test } from "bun:test";
-import { mergeFinancialStatementRows } from "./financial-statements";
+import { coalesceFinancialPeriodAliases, mergeFinancialStatementRows } from "./financial-statements";
+import { computeTTM } from "../plugins/builtin/ticker-detail/financials/aggregation";
+import type { FinancialStatement } from "../types/financials";
+
+test("period evidence follows the selected fiscal date without inventing field availability", () => {
+  const dateEvidence = { accessionNumber: "0000909832-26-000050", filed: "2026-06-04", startDate: "2026-02-16" };
+  const fiscal: FinancialStatement = { date: "2026-05-10", currency: "USD", dateSource: "sec", dateEvidence, totalRevenue: 70527, netIncome: 2192, totalAssets: 81639 };
+  const provider: FinancialStatement = { ...fiscal, date: "2026-05-31", dateSource: "provider", dateEvidence: undefined };
+  for (const [primary, fallback] of [[provider, fiscal], [fiscal, provider]] as const) {
+    const [merged] = mergeFinancialStatementRows([primary], [fallback]);
+    expect(merged).toMatchObject({ date: fiscal.date, dateSource: "sec", dateEvidence });
+    expect(merged?.availableAt).toBeUndefined();
+    expect(merged?.fieldAvailability).toBeUndefined();
+  }
+  const sameDate = mergeFinancialStatementRows([{ ...provider, date: fiscal.date }], [fiscal])[0]!;
+  expect(sameDate.dateEvidence).toEqual(dateEvidence);
+  const different = mergeFinancialStatementRows([{ ...provider, date: "2026-05-09", totalRevenue: 1 }], [{ ...fiscal, availableAt: "2026-06-04" }])[0]!;
+  expect(different.date).toBe("2026-05-09");
+  expect(different.dateSource).toBe("provider");
+  expect(different.dateEvidence).toBeUndefined();
+});
 
 describe("mergeFinancialStatementRows", () => {
+  test("merging and JSON roundtrips preserve unknown fields in an authoritative availability map", () => {
+    const primary: FinancialStatement = {
+      date: "2025-12-31", availableAt: "2026-04-01", totalRevenue: 100, grossProfit: 40,
+      fieldAvailability: { grossProfit: "2026-02-01" },
+    };
+    const fallback: FinancialStatement = { date: primary.date, netIncome: 10, availableAt: "2026-03-01" };
+    const merged = JSON.parse(JSON.stringify(mergeFinancialStatementRows([primary], [fallback])[0])) as FinancialStatement;
+    expect(merged).toMatchObject({ totalRevenue: 100, grossProfit: 40, netIncome: 10,
+      fieldAvailability: { grossProfit: "2026-02-01", netIncome: "2026-03-01" } });
+    expect(merged.availableAt).toBeUndefined();
+    expect(merged.fieldAvailability?.totalRevenue).toBeUndefined();
+    expect(mergeFinancialStatementRows([merged], [fallback])[0]).toEqual(merged);
+    // Independent evidence may date a matching retained value, but not a different one.
+    const [corroborated] = mergeFinancialStatementRows([merged], [{ date: primary.date, totalRevenue: 100, availableAt: "2026-02-15" }]);
+    expect(corroborated?.fieldAvailability?.totalRevenue).toBe("2026-02-15");
+    expect(corroborated?.availableAt).toBe("2026-03-01");
+    const [emptyMap] = mergeFinancialStatementRows([{ ...primary, fieldAvailability: {} }], [{ date: primary.date }]);
+    expect(emptyMap?.fieldAvailability).toEqual({});
+    expect(emptyMap?.availableAt).toBeUndefined();
+  });
+
   test("preserves per-field availability across providers", () => {
     const [merged] = mergeFinancialStatementRows(
       [{
@@ -136,3 +177,35 @@ describe("mergeFinancialStatementRows", () => {
     expect(merged[0]?.date).toBe("2025-06-28");
   });
 });
+
+
+test("does not fill a reporting-currency row from differently denominated statements", () => {
+  expect(mergeFinancialStatementRows(
+    [{ date: "2025-12-31", currency: "TWD", totalRevenue: 3_800_000_000_000 }],
+    [{ date: "2025-12-31", currency: "USD", totalRevenue: 120_000_000_000, netIncome: 60_000_000_000 }],
+  )).toEqual([{ date: "2025-12-31", currency: "TWD", totalRevenue: 3_800_000_000_000 }]);
+});
+
+test("filing-backed fiscal dates coalesce proven month-end aliases, including older cached duplicates", () => {
+  const provider = { date: "2026-05-31", currency: "USD", totalRevenue: 70_527_000_000, netIncome: 2_192_000_000, operatingIncome: 2_815_000_000 };
+  const fiscal = { date: "2026-05-10", totalRevenue: provider.totalRevenue, netIncome: provider.netIncome, operatingIncome: provider.operatingIncome, availableAt: "2026-06-04" };
+  const [merged] = coalesceFinancialPeriodAliases([provider, fiscal]);
+  expect(merged).toMatchObject({ date: "2026-05-10", currency: "USD", availableAt: "2026-06-04" });
+  expect(coalesceFinancialPeriodAliases([fiscal, provider])).toEqual([merged!]);
+  expect(coalesceFinancialPeriodAliases([merged!, provider, fiscal])).toEqual([merged!]);
+  const quarters = coalesceFinancialPeriodAliases([
+    { date: "2025-08-31", currency: "USD", totalRevenue: 86_156_000_000 },
+    { date: "2025-11-23", currency: "USD", totalRevenue: 67_307_000_000 },
+    { date: "2026-02-15", currency: "USD", totalRevenue: 69_597_000_000 },
+    provider, fiscal,
+  ]);
+  expect(computeTTM(quarters)?.totalRevenue).toBe(293_587_000_000);
+  for (const distinct of [
+    { ...fiscal, netIncome: fiscal.netIncome + 1 },
+    { ...fiscal, currency: "CAD" },
+    { ...fiscal, date: "2026-06-10" },
+    { ...fiscal, availableAt: undefined },
+  ]) {
+    expect(coalesceFinancialPeriodAliases([provider, distinct])).toHaveLength(2);
+  }
+});

package/src/utils/financial-statements.ts

@@ -1,8 +1,28 @@
 import type { FinancialStatement } from "../types/financials";
+import { copyIncomeField, incomeFieldOwner, INCOME_STATEMENT_FIELDS, isIncomeStatementField } from "./income-statement";
+import { hasStatementWithdrawals, mergeStatementWithdrawals, redactWithdrawnStatement } from "./statement-observations";
 
-const STATEMENT_METADATA_KEYS = new Set(["date", "availableAt", "fieldAvailability"]);
+export const FINANCIAL_VINTAGE_NOTICE = "Latest available statements may include restatements. Historical as-of values are not reconstructed.";
+export const SEC_EPS_BASIS_NOTICE = "SEC EPS uses corroborated split-adjusted share bases. Unverified bases are unavailable.";
+
+const STATEMENT_METADATA_KEYS = new Set(["date", "dateSource", "providerDate", "dateEvidence", "currency", "availableAt", "fieldAvailability", "epsBasis", "fieldSources", "unavailableFields", "withdrawnObservations"]);
 const NEARBY_PERIOD_END_MS = 7 * 24 * 60 * 60 * 1_000;
 
+/** An explicit field map is authoritative: omitted fields have unknown availability. */
+export function statementFieldAvailability(row: FinancialStatement | undefined, field: string): string | undefined {
+  const filed = isIncomeStatementField(field) ? row?.fieldSources?.[field]?.filed : undefined;
+  const value = filed ?? (row?.fieldAvailability !== undefined ? row.fieldAvailability?.[field] : row?.availableAt);
+  return value && Number.isFinite(Date.parse(value)) ? value : undefined;
+}
+
+/** A derived value is dated only when every input's availability is known. */
+export function completeAvailability(values: readonly (string | null | undefined)[]): string | undefined {
+  if (values.length === 0 || values.some((value) => !value || !Number.isFinite(Date.parse(value)))) return undefined;
+  return values.reduce<string | undefined>((latest, value) => (
+    !latest || Date.parse(value!) > Date.parse(latest) ? value! : latest
+  ), undefined);
+}
+
 function metricKeys(...rows: Array<FinancialStatement | undefined>): string[] {
   return [...new Set(rows.flatMap((row) => Object.keys(row ?? {})))]
     .filter((key) => !STATEMENT_METADATA_KEYS.has(key));
@@ -25,6 +45,9 @@ function canonicalStatementDate(
   fallback: FinancialStatement | undefined,
 ): string {
   if (!fallback) return primary.date;
+  if (primary.dateSource === "sec") return primary.date;
+  if (fallback.dateSource === "sec") return hasMatchingFinancialValues(primary, fallback) ? fallback.date : primary.date;
+  if (isVerifiedCalendarAlias(primary, fallback)) return [primary.date, fallback.date].sort()[0]!;
   return hasAvailabilityEvidence(fallback) && !hasAvailabilityEvidence(primary)
     ? fallback.date
     : primary.date;
@@ -46,6 +69,39 @@ export function areNearbyFinancialPeriodEnds(
     && Math.abs(leftTime - rightTime) <= NEARBY_PERIOD_END_MS;
 }
 
+function hasMatchingFinancialValues(left: FinancialStatement, right: FinancialStatement): boolean {
+  if (left.currency && right.currency && left.currency !== right.currency) return false;
+  const shared = metricKeys(left, right).filter((key) => hasMetricValue(left, key) && hasMetricValue(right, key));
+  return shared.every((key) => Object.is(metricValue(left, key), metricValue(right, key)))
+    && shared.filter((key) => Number.isFinite(metricValue(left, key)) && metricValue(left, key) !== 0).length >= 3;
+}
+
+function isVerifiedCalendarAlias(left: FinancialStatement, right: FinancialStatement): boolean {
+  if (hasStatementWithdrawals(left) || hasStatementWithdrawals(right)) return false;
+  if (left.date === right.date || left.date.slice(0, 7) !== right.date.slice(0, 7)) return false;
+  const monthEnd = (row: FinancialStatement) => {
+    const date = new Date(`${row.date}T00:00:00Z`);
+    return Number.isFinite(date.getTime()) && new Date(date.getTime() + 86_400_000).getUTCDate() === 1;
+  };
+  if (monthEnd(left) === monthEnd(right)) return false;
+  const fiscal = monthEnd(left) ? right : left;
+  if (fiscal.dateSource !== "sec" && !hasAvailabilityEvidence(fiscal)) return false;
+  // A month-end approximation can be weeks away for a 52/53-week issuer.
+  // Require corroborating values, not just proximity or common zero fields.
+  return hasMatchingFinancialValues(left, right);
+}
+
+export function coalesceFinancialPeriodAliases(rows: FinancialStatement[]): FinancialStatement[] {
+  const result: FinancialStatement[] = [];
+  for (const row of rows) {
+    const index = result.findIndex((existing) => isVerifiedCalendarAlias(existing, row)
+      || (existing.date === row.date && hasMatchingFinancialValues(existing, row)));
+    if (index < 0) result.push(row);
+    else result[index] = mergeFinancialStatementRows([result[index]!], [row])[0]!;
+  }
+  return result.sort((left, right) => left.date.localeCompare(right.date));
+}
+
 function matchFallbackRow(
   primary: FinancialStatement,
   fallbackRows: FinancialStatement[],
@@ -58,10 +114,11 @@ function matchFallbackRow(
   return fallbackRows
     .flatMap((row) => {
       if (usedFallbackRows.has(row)) return [];
+      if (hasStatementWithdrawals(primary) || hasStatementWithdrawals(row)) return [];
       const fallbackTime = statementDateTime(row);
       if (fallbackTime === null) return [];
       const distance = Math.abs(fallbackTime - primaryTime);
-      return areNearbyFinancialPeriodEnds(primary.date, row.date) ? [{ row, distance }] : [];
+      return areNearbyFinancialPeriodEnds(primary.date, row.date) || isVerifiedCalendarAlias(primary, row) ? [{ row, distance }] : [];
     })
     .sort((left, right) => left.distance - right.distance || left.row.date.localeCompare(right.row.date))[0]?.row;
 }
@@ -70,6 +127,8 @@ export function mergeFinancialStatementRows(
   primaryRows: FinancialStatement[],
   fallbackRows: FinancialStatement[],
 ): FinancialStatement[] {
+  primaryRows = coalesceFinancialPeriodAliases(primaryRows.map(redactWithdrawnStatement));
+  fallbackRows = coalesceFinancialPeriodAliases(fallbackRows.map(redactWithdrawnStatement));
   if (primaryRows.length === 0) return fallbackRows;
   if (fallbackRows.length === 0) return primaryRows;
 
@@ -77,17 +136,66 @@ export function mergeFinancialStatementRows(
   const mergedRows = primaryRows.map((row) => {
     const fallback = matchFallbackRow(row, fallbackRows, usedFallbackRows);
     if (fallback) usedFallbackRows.add(fallback);
-    const merged = {
+    // Keep the preferred report intact when providers use different reporting currencies.
+    if (row.currency && fallback?.currency && row.currency !== fallback.currency) return row;
+    let merged = {
       ...fallback,
       ...row,
       // Prefer the date backed by filing provenance. Generic provider merges
       // otherwise retain their primary provider's period identity.
       date: canonicalStatementDate(row, fallback),
     } as FinancialStatement;
+    mergeStatementWithdrawals(merged, [row, ...(fallback ? [fallback] : [])]);
+    const correctedFallbackEps = !row.epsBasis && !!fallback?.epsBasis && row.eps === fallback.epsBasis.originalValue;
+    if (row.eps !== undefined && !row.epsBasis && !correctedFallbackEps) delete merged.epsBasis;
+    // Period provenance belongs to the selected date. It must not leak from a
+    // different fallback period or become publication evidence for any value.
+    const dateOwner = [row, fallback].find((candidate) => candidate?.date === merged.date && candidate.dateSource === "sec")
+      ?? (row.date === merged.date ? row : fallback);
+    for (const key of ["dateSource", "providerDate", "dateEvidence"] as const) delete merged[key];
+    if (dateOwner?.dateSource) merged.dateSource = dateOwner.dateSource;
+    if (dateOwner?.providerDate) merged.providerDate = dateOwner.providerDate;
+    if (dateOwner?.dateEvidence) merged.dateEvidence = dateOwner.dateEvidence;
+    if (merged.dateSource === "sec" && row.date !== merged.date && !merged.providerDate) merged.providerDate = row.date;
     const fieldAvailability: Record<string, string> = {};
-    const keys = metricKeys(row, fallback);
+    const keys = [...new Set([...metricKeys(row, fallback), ...INCOME_STATEMENT_FIELDS])];
 
     for (const key of keys) {
+      // Nearby vendor dates alone do not corroborate the identity of an income
+      // observation. Retain the primary's own value and attribution together.
+      if (isIncomeStatementField(key) && fallback && row.date !== fallback.date
+        && (row.fieldSources?.[key] || fallback.fieldSources?.[key]
+          || row.unavailableFields?.includes(key) || fallback.unavailableFields?.includes(key))) {
+        const owner = row.date === merged.date ? row : fallback;
+        copyIncomeField(merged, owner, key);
+        if (typeof merged[key] === "number") {
+          const available = statementFieldAvailability(owner, key);
+          if (available) fieldAvailability[key] = available;
+        }
+        continue;
+      }
+      const incomeOwner = isIncomeStatementField(key) ? incomeFieldOwner(key, row, fallback) : undefined;
+      if (incomeOwner && isIncomeStatementField(key)) {
+        copyIncomeField(merged, incomeOwner, key);
+        if (typeof merged[key] === "number") {
+          const available = statementFieldAvailability(incomeOwner, key);
+          if (available) fieldAvailability[key] = available;
+        }
+        continue;
+      }
+      // A refreshed SEC decision supersedes precisely the original EPS still
+      // held by a primary cache; unrelated provider values keep their priority.
+      if (key === "eps" && correctedFallbackEps) {
+        if (fallback!.epsBasis!.status === "unresolved") delete merged.eps;
+        else merged.eps = fallback!.eps;
+        const available = statementFieldAvailability(fallback, "eps");
+        if (available && merged.eps !== undefined) fieldAvailability.eps = available;
+        continue;
+      }
+      if (key === "eps" && row.epsBasis?.status === "unresolved") {
+        delete merged.eps;
+        continue;
+      }
       const primaryHasValue = hasMetricValue(row, key);
       const fallbackHasValue = hasMetricValue(fallback, key);
       if (!primaryHasValue && fallbackHasValue) {
@@ -95,29 +203,26 @@ export function mergeFinancialStatementRows(
       }
 
       if (primaryHasValue) {
-        const primaryAvailability = row.fieldAvailability?.[key] ?? row.availableAt;
+        const primaryAvailability = statementFieldAvailability(row, key);
         const valuesMatch = fallbackHasValue && Object.is(metricValue(row, key), metricValue(fallback, key));
         const availability = primaryAvailability
-          ?? (valuesMatch ? fallback?.fieldAvailability?.[key] ?? fallback?.availableAt : undefined);
+          ?? (valuesMatch ? statementFieldAvailability(fallback, key) : undefined);
         if (availability) fieldAvailability[key] = availability;
       } else if (fallbackHasValue) {
-        const availability = fallback?.fieldAvailability?.[key] ?? fallback?.availableAt;
+        const availability = statementFieldAvailability(fallback, key);
         if (availability) fieldAvailability[key] = availability;
       }
     }
 
     // A fallback row-level date cannot safely date a different primary value.
     // Retained fallback fields still carry their own per-field provenance.
-    const primaryHasMetrics = keys.some((key) => hasMetricValue(row, key));
+    merged = redactWithdrawnStatement(merged);
+    for (const key of keys) if (!hasMetricValue(merged, key)) delete fieldAvailability[key];
     const retainedMetricKeys = keys.filter((key) => hasMetricValue(merged, key));
-    const completeFieldAvailability = retainedMetricKeys.length > 0
-      && retainedMetricKeys.every((key) => !!fieldAvailability[key]);
-    const availableAt = completeFieldAvailability
-      ? Object.values(fieldAvailability).sort().at(-1)
-      : row.availableAt ?? (!primaryHasMetrics ? fallback?.availableAt : undefined);
+    const availableAt = completeAvailability(retainedMetricKeys.map((key) => fieldAvailability[key]));
     if (availableAt) merged.availableAt = availableAt;
     else delete merged.availableAt;
-    if (Object.keys(fieldAvailability).length > 0) merged.fieldAvailability = fieldAvailability;
+    if (Object.keys(fieldAvailability).length > 0 || row.fieldAvailability !== undefined || fallback?.fieldAvailability !== undefined) merged.fieldAvailability = fieldAvailability;
     else delete merged.fieldAvailability;
     return merged;
   });

package/src/utils/format.test.ts

@@ -1,7 +1,27 @@
 import { describe, expect, test } from "bun:test";
-import { displayWidth, formatTimeAgo, padTo, truncateToDisplayWidth } from "./format";
+import { convertCurrency, displayWidth, formatCompact, formatCurrency, formatNumber, formatPercent, formatPercentRaw, formatTimeAgo, padTo, truncateToDisplayWidth } from "./format";
 import { normalizeTimestamp } from "./timestamp";
 
+test("currency conversion never presents a missing or invalid FX leg as parity", () => {
+  const rates = new Map([["EUR", 1.2], ["JPY", 0.008]]);
+  expect(convertCurrency(100, "EUR", "USD", rates)).toBe(120);
+  expect(convertCurrency(120, "USD", "EUR", rates)).toBe(100);
+  expect(convertCurrency(100, "EUR", "JPY", rates)).toBe(15_000);
+  expect(convertCurrency(100, "EUR", "EUR", new Map())).toBe(100);
+  expect(convertCurrency(0, "EUR", "USD", new Map())).toBe(0);
+
+  for (const invalidRate of [undefined, 0, -1, Number.NaN, Number.POSITIVE_INFINITY]) {
+    const invalid = invalidRate === undefined ? new Map<string, number>() : new Map([["EUR", invalidRate]]);
+    expect(convertCurrency(100, "EUR", "USD", invalid)).toBeNaN();
+    expect(convertCurrency(100, "USD", "EUR", invalid)).toBeNaN();
+  }
+  for (const value of [Number.NaN, Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY]) {
+    for (const format of [formatCurrency, formatCompact, formatNumber, formatPercent, formatPercentRaw]) {
+      expect(format(value)).toBe("—");
+    }
+  }
+});
+
 describe("formatTimeAgo", () => {
   test("handles UTC ISO timestamps with explicit offsets", () => {
     const fiveMinutesAgo = new Date(Date.now() - 5 * 60_000).toISOString().replace("Z", "+00:00");

package/src/utils/format.ts

@@ -3,16 +3,17 @@ import { toTimestampMillis } from "./timestamp";
 const currencyFormatters = new Map<string, Intl.NumberFormat>();
 const numberFormatters = new Map<number, Intl.NumberFormat>();
 
-function getCurrencyFormatter(currency: string): Intl.NumberFormat {
-  let formatter = currencyFormatters.get(currency);
+function getCurrencyFormatter(currency: string, maximumFractionDigits = 2): Intl.NumberFormat {
+  const key = `${currency}:${maximumFractionDigits}`;
+  let formatter = currencyFormatters.get(key);
   if (!formatter) {
     formatter = new Intl.NumberFormat("en-US", {
       style: "currency",
       currency,
       minimumFractionDigits: 2,
-      maximumFractionDigits: 2,
+      maximumFractionDigits,
     });
-    currencyFormatters.set(currency, formatter);
+    currencyFormatters.set(key, formatter);
   }
   return formatter;
 }
@@ -30,28 +31,34 @@ function getNumberFormatter(decimals: number): Intl.NumberFormat {
 }
 
 /** Format a number as currency (e.g., $1,234.56) */
-export function formatCurrency(value: number | undefined, currency = "USD"): string {
-  if (value === undefined || value === null || Number.isNaN(value)) return "—";
-  return getCurrencyFormatter(currency).format(value);
+export function formatCurrency(value: number | undefined, currency = "USD", maximumFractionDigits = 2): string {
+  if (value == null || !Number.isFinite(value)) return "—";
+  return getCurrencyFormatter(currency, maximumFractionDigits).format(value);
+}
+
+/** Preserve fractional per-share distributions, including split-adjusted history. */
+export function formatDistributionAmount(value: number | undefined, currency = "USD"): string {
+  if (value == null || !Number.isFinite(value)) return "—";
+  return getCurrencyFormatter(currency, 6).format(value);
 }
 
 /** Format a number as percentage (e.g., +1.23%) */
 export function formatPercent(value: number | undefined): string {
-  if (value === undefined || value === null) return "—";
+  if (value == null || !Number.isFinite(value)) return "—";
   const sign = value > 0 ? "+" : "";
   return `${sign}${(value * 100).toFixed(2)}%`;
 }
 
 /** Format a percentage that's already in percent form (e.g., 1.23 -> +1.23%) */
 export function formatPercentRaw(value: number | undefined): string {
-  if (value === undefined || value === null) return "—";
+  if (value == null || !Number.isFinite(value)) return "—";
   const sign = value > 0 ? "+" : "";
   return `${sign}${value.toFixed(2)}%`;
 }
 
 /** Format large numbers compactly (e.g., 1.5T, 234B, 12.3M, 5k) */
 export function formatCompact(value: number | undefined): string {
-  if (value === undefined || value === null) return "—";
+  if (value == null || !Number.isFinite(value)) return "—";
   const abs = Math.abs(value);
   const sign = value < 0 ? "-" : "";
   const fmt = (n: number, decimals: number, suffix: string) => {
@@ -69,13 +76,13 @@ export function formatCompact(value: number | undefined): string {
 
 /** Format a compact value with an explicit currency code (e.g., 1.5T USD) */
 export function formatCompactCurrency(value: number | undefined, currency = "USD"): string {
-  if (value === undefined || value === null) return "—";
+  if (value == null || !Number.isFinite(value)) return "—";
   return `${formatCompact(value)} ${currency}`;
 }
 
 /** Format a plain number with commas */
 export function formatNumber(value: number | undefined, decimals = 2): string {
-  if (value === undefined || value === null) return "—";
+  if (value == null || !Number.isFinite(value)) return "—";
   return getNumberFormatter(decimals).format(value);
 }
 
@@ -114,13 +121,31 @@ const EMOJI_PRESENTATION_RE = /\p{Emoji_Presentation}/u;
 const EXTENDED_PICTOGRAPHIC_RE = /\p{Extended_Pictographic}/u;
 const REGIONAL_INDICATOR_RE = /\p{Regional_Indicator}/u;
 
+/**
+ * Printable ASCII is always one cell per code unit. Table cells are mostly
+ * numbers, tickers, and dates, so this skips grapheme segmentation on the
+ * render hot path.
+ */
+const SINGLE_WIDTH_ASCII_RE = /^[\x20-\x7e]*$/;
+
+let graphemeSegmenter: { segment(value: string): Iterable<{ segment: string }> } | null | undefined;
+
+// Constructing Intl.Segmenter costs about 10us; segmenting with a shared one
+// costs a fraction of that, and the instance carries no per-call state.
+function getGraphemeSegmenter(): typeof graphemeSegmenter {
+  if (graphemeSegmenter === undefined) {
+    const Segmenter = (Intl as any).Segmenter;
+    graphemeSegmenter = typeof Segmenter === "function"
+      ? new Segmenter(undefined, { granularity: "grapheme" })
+      : null;
+  }
+  return graphemeSegmenter;
+}
+
 function segmentGraphemes(value: string): string[] {
-  const Segmenter = (Intl as any).Segmenter;
-  if (typeof Segmenter === "function") {
-    return Array.from(
-      new Segmenter(undefined, { granularity: "grapheme" }).segment(value),
-      (entry: any) => entry.segment as string,
-    );
+  const segmenter = getGraphemeSegmenter();
+  if (segmenter) {
+    return Array.from(segmenter.segment(value), (entry) => entry.segment);
   }
   return Array.from(value);
 }
@@ -170,11 +195,13 @@ function graphemeWidth(segment: string): number {
 }
 
 export function displayWidth(value: string): number {
+  if (SINGLE_WIDTH_ASCII_RE.test(value)) return value.length;
   return segmentGraphemes(value).reduce((total, segment) => total + graphemeWidth(segment), 0);
 }
 
 function truncateToWidth(value: string, width: number): string {
   if (width <= 0) return "";
+  if (SINGLE_WIDTH_ASCII_RE.test(value)) return value.slice(0, width);
   let output = "";
   let used = 0;
   for (const segment of segmentGraphemes(value)) {
@@ -242,17 +269,23 @@ export function padTo(str: string, width: number, align: "left" | "right" | "cen
   return clipped + " ".repeat(padding);
 }
 
-/** Convert a value from one currency to base currency using cached exchange rates */
+/**
+ * Convert using USD-per-unit rates. Missing FX remains unavailable (NaN), so
+ * totals cannot silently mix source currency with base currency. Numeric
+ * formatters render this as a dash and JSON encodes it as null.
+ */
 export function convertCurrency(
   value: number,
   fromCurrency: string,
   baseCurrency: string,
   exchangeRates: Map<string, number>,
 ): number {
-  if (fromCurrency === baseCurrency) return value;
-  const fromRate = exchangeRates.get(fromCurrency);
-  const baseRate = exchangeRates.get(baseCurrency);
-  if (fromRate == null || baseRate == null || baseRate === 0) return value;
+  if (!Number.isFinite(value)) return Number.NaN;
+  if (fromCurrency === baseCurrency || value === 0) return value;
+  const fromRate = fromCurrency === "USD" ? 1 : exchangeRates.get(fromCurrency);
+  const baseRate = baseCurrency === "USD" ? 1 : exchangeRates.get(baseCurrency);
+  if (fromRate == null || baseRate == null || !Number.isFinite(fromRate) || !Number.isFinite(baseRate)
+    || fromRate <= 0 || baseRate <= 0) return Number.NaN;
   return (value * fromRate) / baseRate;
 }
 

package/src/utils/fundamentals.ts

@@ -0,0 +1,15 @@
+import type { Fundamentals } from "../types/financials";
+
+export const RETRACTABLE_VALUATION_FIELDS = ["enterpriseValue", "enterpriseToRevenue"] as const;
+
+/** A retraction survives serialization and overrides a contradictory cached number. */
+export function redactUnavailableFundamentals(value: Fundamentals | undefined): Fundamentals | undefined {
+  if (!value || value.unavailableFields === undefined) return value;
+  const unavailableFields = Array.isArray(value.unavailableFields)
+    ? RETRACTABLE_VALUATION_FIELDS.filter((field) => value.unavailableFields!.includes(field)) : [];
+  const result = { ...value };
+  if (unavailableFields.length) result.unavailableFields = unavailableFields;
+  else delete result.unavailableFields;
+  for (const field of unavailableFields) delete result[field];
+  return result;
+}

package/src/utils/fx-status.test.ts

@@ -0,0 +1,16 @@
+import { expect, test } from "bun:test";
+import { summarizeFxRates, fxStatusLabel } from "./fx-status";
+import { createIdleEntry } from "../market-data/result-types";
+
+test("cross-currency status exposes oldest source time, stale fallback, missing and undated rates separately", () => {
+  const now = Date.parse("2026-09-10T21:00:00Z");
+  const eur = { ...createIdleEntry<number>(), phase: "ready" as const, data: 1.16, source: "yahoo", asOf: now - 45 * 60_000, fetchedAt: now - 30 * 60_000, staleAt: now + 30 * 60_000 };
+  const jpy = { ...eur, data: 1 / 154, asOf: now - 2 * 60 * 60_000, fetchedAt: now - 2 * 60 * 60_000, staleAt: now - 60 * 60_000, error: { reasonCode: "offline", message: "offline" } };
+  const read = (currency: string) => currency === "EUR" ? eur : currency === "JPY" ? jpy : null;
+  const rates = new Map([["USD", 1], ["EUR", 1.16], ["JPY", 1 / 154], ["GBP", 1.33]]);
+  const status = summarizeFxRates(["USD", "EUR", "JPY", "GBP", "CHF", "EUR"], rates, read, now);
+  expect(status).toMatchObject({ unavailable: 1, stale: 1, unknownTime: 1, oldestAsOf: jpy.asOf, latestFetchedAt: eur.fetchedAt, sources: ["yahoo"] });
+  expect(fxStatusLabel(status)).toContain("oldest rate 2026-09-10 19:00 UTC");
+  expect(fxStatusLabel(status)).toContain("1 rate time unknown");
+  expect(summarizeFxRates(["USD"], rates, read, now).oldestAsOf).toBeNull();
+});

package/src/utils/fx-status.ts

@@ -0,0 +1,46 @@
+import type { QueryEntry } from "../market-data/result-types";
+
+export interface FxRateStatus {
+  loading: number;
+  unavailable: number;
+  stale: number;
+  unknownTime: number;
+  oldestAsOf: number | null;
+  latestFetchedAt: number | null;
+  sources: string[];
+}
+
+/** A fetched timestamp never stands in for a source observation timestamp. */
+export function summarizeFxRates(
+  currencies: readonly string[],
+  rates: ReadonlyMap<string, number>,
+  read: (currency: string) => QueryEntry<number> | null | undefined,
+  now = Date.now(),
+): FxRateStatus {
+  const status: FxRateStatus = { loading: 0, unavailable: 0, stale: 0, unknownTime: 0, oldestAsOf: null, latestFetchedAt: null, sources: [] };
+  const sources = new Set<string>();
+  for (const currency of new Set(currencies.map((value) => value.trim().toUpperCase()))) {
+    if (currency === "USD") continue;
+    const entry = read(currency);
+    if (entry?.phase === "loading" || entry?.phase === "refreshing") status.loading++;
+    const rate = rates.get(currency);
+    if (rate == null || !Number.isFinite(rate) || rate <= 0) { status.unavailable++; continue; }
+    // A legacy persisted numeric rate may be present without a dated query.
+    if (!entry || entry.asOf == null || !Number.isFinite(entry.asOf)) status.unknownTime++;
+    else status.oldestAsOf = Math.min(status.oldestAsOf ?? Infinity, entry.asOf);
+    if (entry?.error || (entry?.staleAt != null && entry.staleAt <= now)) status.stale++;
+    if (entry?.fetchedAt != null) status.latestFetchedAt = Math.max(status.latestFetchedAt ?? 0, entry.fetchedAt);
+    if (entry?.source && entry.source !== "static" && entry.source !== "identity") sources.add(entry.source);
+  }
+  status.sources = [...sources].sort();
+  return status;
+}
+
+export function fxStatusLabel(status: FxRateStatus): string {
+  const parts: string[] = [];
+  if (status.unavailable) parts.push(`${status.unavailable} unavailable`);
+  if (status.stale) parts.push(`${status.stale} stale`);
+  if (status.unknownTime) parts.push(`${status.unknownTime} rate ${status.unknownTime === 1 ? "time" : "times"} unknown`);
+  if (status.oldestAsOf != null) parts.push(`oldest rate ${new Date(status.oldestAsOf).toISOString().slice(0, 16).replace("T", " ")} UTC`);
+  return parts.join(" · ");
+}