gloomberb 0.13.3 → 0.14.0

package/src/time-series/valuation-denominator.test.ts

@@ -0,0 +1,240 @@
+import { expect, test } from "bun:test";
+import { createTestDataProvider } from "../test-support/data-provider";
+import { createDefaultConfig } from "../types/config";
+import type { FinancialStatement, TickerFinancials } from "../types/financials";
+import { loadChartPaneModel } from "../plugins/builtin/chart-composer/headless";
+import { deriveQuarterlyStatements, extractFundamentalSeries } from "./fundamentals";
+import type { ChartSpec, SecuritySeriesSource } from "./types";
+
+const source = (period: SecuritySeriesSource["period"] = "annual", metric = "trailingPE"): SecuritySeriesSource => ({
+  kind: "security", instrument: { symbol: "TEST", exchange: "NYSE" },
+  fieldId: `valuation.${metric}`, period, timestampMode: "available-at",
+});
+const fixture = (): TickerFinancials => ({
+  financialCurrency: "USD",
+  quote: { symbol: "TEST", currency: "USD", price: 60, lastUpdated: Date.parse("2026-09-11T20:00Z"), change: 0, changePercent: 0 },
+  annualStatements: [
+    { date: "2024-12-31", availableAt: "2025-03-01", currency: "USD", eps: 10 },
+    { date: "2025-12-31", availableAt: "2026-03-01", currency: "USD", eps: -2 },
+  ],
+  quarterlyStatements: [],
+  priceHistory: [
+    { date: new Date("2025-03-01"), close: 50 },
+    { date: new Date("2026-03-01"), close: 55 },
+  ],
+});
+
+test("Current valuation chooses the latest available statement before evaluating its denominator", () => {
+  for (const earnings of [-2, 0, undefined]) {
+    const data = fixture(); data.annualStatements[1]!.eps = earnings;
+    const original = JSON.stringify(data);
+    expect(extractFundamentalSeries(data, source()).map(({ value, periodLabel }) => [value, periodLabel]))
+      .toEqual([[5, "Year ended 2024-12-31"], [null, "Year ended 2025-12-31"]]);
+    expect(JSON.stringify(data)).toBe(original);
+  }
+  // An unpublished loss does not replace the earnings known at this quote time.
+  const future = fixture(); future.annualStatements[1]!.fieldAvailability = { eps: "2026-10-01" };
+  expect(extractFundamentalSeries(future, source()).find(point => point.periodLabel === "Current")?.value).toBe(6);
+  // A corrected positive latest observation resumes calculation on that period.
+  future.annualStatements[1] = { ...future.annualStatements[1]!, eps: 3, fieldAvailability: { eps: "2026-03-01" } };
+  expect(extractFundamentalSeries(future, source()).at(-1)?.value).toBe(20);
+});
+
+test("automatic valuation coverage does not substitute a profitable annual period for loss-making TTM inputs", () => {
+  const data = fixture();
+  data.annualStatements = [data.annualStatements[0]!];
+  data.quarterlyStatements = ["2025-06-30", "2025-09-30", "2025-12-31", "2026-03-31"]
+    .map((date) => ({ date, currency: "USD", eps: -1 }));
+  for (const period of ["auto", "ttm"] as const) {
+    expect(extractFundamentalSeries(data, source(period))).toEqual([]);
+  }
+  // Missing TTM earnings coverage can still use the independently requested
+  // automatic annual fallback; this is different from known unprofitable input.
+  data.quarterlyStatements = data.quarterlyStatements.map(({ eps, ...row }) => row);
+  expect(extractFundamentalSeries(data, source("auto")).at(-1)?.value).toBe(6);
+  expect(extractFundamentalSeries(data, source("ttm"))).toEqual([]);
+});
+
+test("finite reported EPS takes precedence over aggregate income and shares, including zero", () => {
+  for (const eps of [0, -0, -2, 2]) {
+    const data = fixture();
+    Object.assign(data.annualStatements[1]!, { eps, netIncome: 100, netIncomeCommonStockholders: eps * 10, dilutedShares: 10 });
+    const original = structuredClone(data);
+    const points = extractFundamentalSeries(data, source());
+    expect(points.map(({ value }) => value)).toEqual(eps > 0 ? [5, 27.5, 30] : [5, null]);
+    expect(data).toEqual(original);
+  }
+  // Only unavailable/nonfinite reported EPS keeps the existing derivation.
+  for (const eps of [undefined, NaN, Infinity]) {
+    const data = fixture();
+    Object.assign(data.annualStatements[1]!, { eps, netIncome: 100, dilutedShares: 10 });
+    expect(extractFundamentalSeries(data, source()).map(({ value }) => value)).toEqual([5, 5.5, 6]);
+  }
+});
+
+test("zero TTM reported EPS is coverage, not permission to use aggregate income or annual EPS", () => {
+  for (const earnings of [[0, 0, 0, 0], [1, -1, 2, -2]]) {
+    const data = fixture();
+    data.annualStatements = [data.annualStatements[0]!];
+    data.quarterlyStatements = ["2025-06-30", "2025-09-30", "2025-12-31", "2026-03-31"]
+      .map((date, index) => ({ date, currency: "USD", eps: earnings[index], netIncome: 25, dilutedShares: 10 }));
+    for (const period of ["auto", "ttm"] as const) {
+      expect(extractFundamentalSeries(data, source(period))).toEqual([]);
+    }
+    data.quarterlyStatements = data.quarterlyStatements.map(({ eps, ...row }) => row);
+    for (const period of ["auto", "ttm"] as const) {
+      expect(extractFundamentalSeries(data, source(period)).at(-1)?.value).toBe(6);
+    }
+  }
+});
+
+test("reported zero EPS uses its own availability; absent EPS uses income and shares availability", () => {
+  const data = fixture();
+  const latest = data.annualStatements[1]!;
+  Object.assign(latest, { eps: 0, netIncome: 200, dilutedShares: 10,
+    fieldAvailability: { eps: "2026-03-01", netIncome: "2026-10-01", dilutedShares: "2026-10-01" } });
+  // The known zero is effective even though alternative inputs are unpublished.
+  expect(extractFundamentalSeries(data, source()).map(({ value }) => value)).toEqual([5, null]);
+  latest.fieldAvailability = { eps: "2026-10-01", netIncome: "2026-03-01", dilutedShares: "2026-03-01" };
+  // Before reported EPS is available, the older published period remains current.
+  expect(extractFundamentalSeries(data, source()).map(({ value }) => value)).toEqual([5, 6, null]);
+  latest.eps = undefined;
+  expect(extractFundamentalSeries(data, source()).map(({ value }) => value)).toEqual([5, 2.75, 3]);
+  latest.fieldAvailability.dilutedShares = "2026-10-01";
+  expect(extractFundamentalSeries(data, source()).find(({ periodLabel }) => periodLabel === "Current")?.value).toBe(6);
+});
+
+test("missing EPS selects common income including zero and loss, without requiring aggregate income", () => {
+  for (const common of [60, 0, -20]) {
+    for (const netIncome of [100, undefined]) {
+      const data = fixture();
+      Object.assign(data.annualStatements[1]!, { eps: undefined, netIncome, netIncomeCommonStockholders: common, dilutedShares: 10, basicShares: 8 });
+      const original = structuredClone(data);
+      const points = extractFundamentalSeries(data, source());
+      expect(points.map(({ value }) => value)).toEqual(common > 0 ? [5, 55 / 6, 10] : [5, null]);
+      expect(points.every(({ provenance }) => provenance?.quality === "derived")).toBe(true);
+      expect(data).toEqual(original);
+    }
+  }
+  // Unusable common-income inputs do not manufacture a number or zero claim.
+  for (const common of [undefined, NaN, Infinity]) {
+    const data = fixture();
+    Object.assign(data.annualStatements[1]!, { eps: undefined, netIncome: 100, netIncomeCommonStockholders: common, dilutedShares: 10 });
+    expect(extractFundamentalSeries(data, source()).at(-1)?.value).toBe(6);
+  }
+});
+
+test("common-income fallback uses selected share and income availability, not aggregate publication time", () => {
+  const data = fixture();
+  const latest = data.annualStatements[1]!;
+  Object.assign(latest, { eps: undefined, netIncome: 100, netIncomeCommonStockholders: 60, dilutedShares: 10, basicShares: 8,
+    fieldAvailability: { netIncome: "2026-10-01", netIncomeCommonStockholders: "2026-03-01", dilutedShares: "2026-03-01", basicShares: "2026-03-01" } });
+  let points = extractFundamentalSeries(data, source());
+  expect(points.at(-1)?.value).toBe(10);
+  expect(points[1]?.availableAt?.toISOString()).toBe("2026-03-01T00:00:00.000Z");
+  latest.fieldAvailability!.netIncomeCommonStockholders = "2026-10-01";
+  expect(extractFundamentalSeries(data, source()).find(({ periodLabel }) => periodLabel === "Current")?.value).toBe(6);
+  latest.fieldAvailability!.netIncomeCommonStockholders = "2026-03-01";
+  latest.fieldAvailability!.dilutedShares = "2026-10-01";
+  expect(extractFundamentalSeries(data, source()).find(({ periodLabel }) => periodLabel === "Current")?.value).toBe(6);
+  for (const dilutedShares of [undefined, 0, -1, NaN, Infinity]) {
+    latest.dilutedShares = dilutedShares;
+    expect(extractFundamentalSeries(data, source()).at(-1)?.value).toBe(8);
+  }
+  latest.basicShares = undefined;
+  expect(extractFundamentalSeries(data, source()).map(({ value }) => value)).toEqual([5, null]);
+  latest.ordinarySharesNumber = 5;
+  latest.fieldAvailability!.ordinarySharesNumber = "2026-03-01";
+  expect(extractFundamentalSeries(data, source()).at(-1)?.value).toBe(5);
+  latest.ordinarySharesNumber = undefined;
+  latest.shareIssued = 4;
+  latest.fieldAvailability!.shareIssued = "2026-03-01";
+  expect(extractFundamentalSeries(data, source()).at(-1)?.value).toBe(4);
+  latest.dilutedShares = 10;
+  latest.fieldAvailability!.dilutedShares = "2026-03-01";
+  delete latest.fieldAvailability!.netIncomeCommonStockholders;
+  const undated = extractFundamentalSeries(data, source()).find(({ periodLabel }) => periodLabel === "Year ended 2025-12-31")!;
+  expect(undated.availableAt).toBeUndefined();
+  expect(undated.date.toISOString()).toBe("2025-12-31T00:00:00.000Z");
+});
+
+test("TTM keeps a complete common numerator and averaged shares; partial common coverage cannot become aggregate earnings", () => {
+  const data = fixture();
+  data.annualStatements = [data.annualStatements[0]!];
+  data.quarterlyStatements = ["2025-06-30", "2025-09-30", "2025-12-31", "2026-03-31"].map((date, index) => ({
+    date, currency: "USD", netIncome: 25, netIncomeCommonStockholders: [6, 12, 18, 24][index],
+    dilutedShares: [8, 10, 12, 10][index], basicShares: 5,
+    fieldAvailability: { netIncomeCommonStockholders: "2026-04-30", dilutedShares: "2026-05-01", netIncome: "2026-10-01" },
+  }));
+  for (const period of ["ttm", "auto"] as const) {
+    const points = extractFundamentalSeries(data, source(period));
+    expect(points.at(-1)?.value).toBe(10);
+    expect(points[0]?.availableAt?.toISOString()).toBe("2026-05-01T00:00:00.000Z");
+  }
+  data.quarterlyStatements[1]!.netIncomeCommonStockholders = undefined;
+  for (const period of ["ttm", "auto"] as const) expect(extractFundamentalSeries(data, source(period))).toEqual([]);
+  expect(extractFundamentalSeries(data, { ...source("ttm"), fieldId: "fundamental.netIncome" }).at(-1)?.value).toBe(100);
+  // Complete reported EPS overrides the fallback coverage guard, including zero.
+  for (const eps of [0, 0.5]) {
+    for (const quarter of data.quarterlyStatements) { quarter.eps = eps; quarter.fieldAvailability!.eps = "2026-04-30"; }
+    expect(extractFundamentalSeries(data, source("auto")).at(-1)?.value).toBe(eps === 0 ? undefined : 30);
+  }
+  for (const quarter of data.quarterlyStatements) {
+    delete quarter.eps; delete quarter.netIncomeCommonStockholders;
+    quarter.fieldAvailability!.netIncome = "2026-04-30";
+  }
+  expect(extractFundamentalSeries(data, source("auto")).at(-1)?.value).toBe(6);
+});
+
+test("reported Q4 common earnings use their own income and share dates while unresolved EPS blocks fallback", () => {
+  const annual: FinancialStatement = { date: "2025-12-31", currency: "USD", netIncome: 100, netIncomeCommonStockholders: 60, dilutedShares: 10,
+    fieldAvailability: { netIncome: "2026-03-01", netIncomeCommonStockholders: "2026-03-05", dilutedShares: "2026-03-06" } };
+  const quarters: FinancialStatement[] = ["2025-03-31", "2025-06-30", "2025-09-30"].map((date, index) => ({ date, currency: "USD", netIncome: 25,
+    netIncomeCommonStockholders: [10, 20, 15][index], dilutedShares: [8, 10, 12][index], availableAt: "2025-11-01" }));
+  // Common allocations and weighted-average shares both require quarter inputs.
+  quarters.push({ date: "2025-12-31", currency: "USD", netIncomeCommonStockholders: 15, dilutedShares: 10,
+    fieldAvailability: { netIncomeCommonStockholders: "2026-03-05", dilutedShares: "2026-03-06" } });
+  const q4 = deriveQuarterlyStatements(quarters, [annual]).at(-1)!;
+  expect(q4).toMatchObject({ netIncomeCommonStockholders: 15, dilutedShares: 10,
+    fieldAvailability: { netIncomeCommonStockholders: "2026-03-05", dilutedShares: "2026-03-06" } });
+  const data = { ...fixture(), annualStatements: [annual], quarterlyStatements: quarters };
+  const points = extractFundamentalSeries(data, source("ttm"));
+  expect(points.at(-1)?.value).toBe(10);
+  expect(points[0]?.availableAt?.toISOString()).toBe("2026-03-06T00:00:00.000Z");
+  annual.epsBasis = { status: "unresolved", source: "sec", originalValue: 6, basisDate: "2026-03-01", evidence: [] };
+  quarters[3]!.epsBasis = { ...annual.epsBasis, originalValue: 1.5 };
+  expect(extractFundamentalSeries(data, source("annual"))).toEqual([]);
+  expect(extractFundamentalSeries(data, source("ttm"))).toEqual([]);
+});
+
+test("other current monetary ratios cannot skip a latest zero denominator", () => {
+  const cases: Array<[string, Partial<FinancialStatement>, keyof FinancialStatement]> = [
+    ["priceSales", { totalRevenue: 100, dilutedShares: 10 }, "totalRevenue"],
+    ["evSales", { totalRevenue: 100, dilutedShares: 10, totalDebt: 20, cashAndCashEquivalents: 5 }, "totalRevenue"],
+    ["evEbitda", { ebitda: 100, dilutedShares: 10, totalDebt: 20, cashAndCashEquivalents: 5 }, "ebitda"],
+    ["priceFcf", { freeCashFlow: 100, dilutedShares: 10 }, "freeCashFlow"],
+  ];
+  for (const [metric, fields, denominator] of cases) {
+    const data = fixture();
+    data.annualStatements = data.annualStatements.map((row, index) => ({ ...row, ...fields, ...(index ? { [denominator]: 0 } : {}) }));
+    expect(extractFundamentalSeries(data, source("annual", metric)).some((point) => point.periodLabel === "Current")).toBe(false);
+    data.quarterlyStatements = ["2025-06-30", "2025-09-30", "2025-12-31", "2026-03-31"]
+      .map((date) => ({ date, currency: "USD", ...fields, [denominator]: 0 }));
+    expect(extractFundamentalSeries(data, source("auto", metric))).toEqual([]);
+  }
+});
+
+test("chart and headless export preserve historical P/E without a Current point sourced from older earnings", async () => {
+  const data = fixture();
+  const spec: ChartSpec = { version: 1, viewport: { range: "5Y", resolution: "1d" }, panels: [{ id: "main" }], studies: [],
+    series: [{ id: "pe", source: source(), style: "line", transform: "raw", axis: "left", panelId: "main", interpolation: "none" }] };
+  const context = { marketData: createTestDataProvider({ getTickerFinancials: async () => data,
+    getQuote: async () => data.quote!, getPriceHistoryForResolution: async () => data.priceHistory }),
+    apiClient: {} as any, config: createDefaultConfig("/tmp/valuation-denominator-test"), signal: new AbortController().signal };
+  const model = await loadChartPaneModel(spec, context);
+  expect(model.series[0]?.points.map((point) => point.value)).toEqual([5, null]);
+  expect(model.snapshot.financials[0]?.[1].annualStatements.at(-1)?.eps).toBe(-2);
+  data.annualStatements[1]!.eps = 3;
+  const recovered = await loadChartPaneModel(spec, context);
+  expect(recovered.series[0]?.points.at(-1)?.value).toBe(20);
+});

package/src/time-series/valuation-live-status.test.ts

@@ -0,0 +1,63 @@
+import { expect, test } from "bun:test";
+import { createTestDataProvider } from "../test-support/data-provider";
+import { resolveChartSpecData } from "./resolve";
+import { subscribeToLiveChartQuotes } from "./live-quotes";
+import type { Quote, TickerFinancials } from "../types/financials";
+import { CHART_SPEC_VERSION, type ChartSpec } from "./types";
+
+// Synthetic boundary inputs. This exercises actual subscription + resolver,
+// not a claim of a newly fetched provider quote or native render execution.
+for (const receivedAt of [undefined, 42]) {
+  test(`equal source-time stale changes flow through actual resolver with receipt ${receivedAt}`, async () => {
+    const quote: Quote = { symbol: "TEST", currency: "USD", price: 60, change: 0, changePercent: 0,
+      lastUpdated: Date.parse("2026-09-11T20:00:00Z"), stale: false,
+      ...(receivedAt === undefined ? {} : { receivedAt }) };
+    const financials: TickerFinancials = { financialCurrency: "USD", quote,
+      annualStatements: [{ date: "2025-12-31", availableAt: "2026-09-10T14:00:00Z", currency: "USD", eps: 10 }],
+      quarterlyStatements: [], priceHistory: [{ date: new Date("2026-09-10T13:30:00Z"), close: 55 }] };
+    const spec: ChartSpec = { version: CHART_SPEC_VERSION, viewport: { range: "5Y", resolution: "1d" },
+      panels: [{ id: "main" }], studies: [], series: [{ id: "pe", source: { kind: "security", instrument: { symbol: "TEST", exchange: "NYSE" },
+        fieldId: "valuation.trailingPE", period: "annual", timestampMode: "available-at" },
+        style: "line", transform: "raw", axis: "left", panelId: "main", interpolation: "none" }] };
+    let emit!: Parameters<NonNullable<ReturnType<typeof createTestDataProvider>["subscribeQuotes"]>>[1];
+    let target!: Parameters<NonNullable<ReturnType<typeof createTestDataProvider>["subscribeQuotes"]>>[0][number];
+    const provider = createTestDataProvider({ getTickerFinancials: async () => financials,
+      getQuote: async () => financials.quote!, getPriceHistoryForResolution: async () => financials.priceHistory,
+      subscribeQuotes: (targets, listener) => { target = targets[0]!; emit = listener; return () => {}; } });
+    const results: Awaited<ReturnType<typeof resolveChartSpecData>>[] = [];
+    const stop = subscribeToLiveChartQuotes({ spec, dataProvider: provider, refreshIntervalMs: 0,
+      onRefresh: async (quoteOverrides) => { results.push(await resolveChartSpecData(spec, { dataProvider: provider,
+        now: new Date("2026-09-12T00:00:00Z"), quoteOverrides })); } });
+    async function send(next: Quote, refreshes?: number) {
+      emit(target, next);
+      if (refreshes === undefined) { await Bun.sleep(10); return; }
+      for (let attempt = 0; attempt < 100 && results.length < refreshes; attempt++) await Bun.sleep(2);
+    }
+    try {
+      await send({ ...quote }, 1);
+      expect(results).toHaveLength(1);
+      expect(results.at(-1)?.series[0]?.points.map(point => point.value)).toEqual([5.5, 6]);
+      await send({ ...quote, stale: true }, 2);
+      expect(results).toHaveLength(2);
+      expect(results.at(-1)?.series[0]?.points.map(point => point.value)).toEqual([5.5]);
+      expect(results.at(-1)?.warnings.some(warning => warning.includes("source quote is stale"))).toBe(true);
+      await send({ ...quote, stale: false }, 3);
+      expect(results).toHaveLength(3);
+      expect(results.at(-1)?.series[0]?.points.map(point => point.value)).toEqual([5.5, 6]);
+      expect(results.at(-1)?.warnings.some(warning => warning.includes("source quote is stale"))).toBe(false);
+      // An older source observation must remain rejected even with a newer receipt.
+      await send({ ...quote, lastUpdated: quote.lastUpdated - 60_000, stale: true, receivedAt: 500 });
+      expect(results).toHaveLength(3);
+      // Exact duplicate and receipt-only heartbeat must not rebuild the chart.
+      await send({ ...quote });
+      await send({ ...quote, receivedAt: 1000 });
+      expect(results).toHaveLength(3);
+      // After advancing the receipt, delayed older-receipt status is also rejected.
+      await send({ ...quote, stale: true, receivedAt: 999 });
+      expect(results).toHaveLength(3);
+      await send({ ...quote, stale: true, receivedAt: 1000 }, 4);
+      expect(results).toHaveLength(4);
+      expect(results.at(-1)?.series[0]?.points.map(point => point.value)).toEqual([5.5]);
+    } finally { stop(); }
+  });
+}

package/src/time-series/valuation-price.test.ts

@@ -0,0 +1,264 @@
+import { expect, spyOn, test } from "bun:test";
+import type { TickerFinancials } from "../types/financials";
+import { createTestDataProvider } from "../test-support/data-provider";
+import { createDefaultConfig } from "../types/config";
+import { loadChartPaneModel } from "../plugins/builtin/chart-composer/headless";
+import { extractFundamentalSeries, valuationPriceIssues } from "./fundamentals";
+import { resolveStudies } from "./studies";
+import { resolveChartSpecData } from "./resolve";
+import { chartQuoteOverrideKeyForSource, subscribeToLiveChartQuotes } from "./live-quotes";
+import { CHART_SPEC_VERSION, type ChartSpec, type SecuritySeriesSource } from "./types";
+
+const source = (metric = "trailingPE"): SecuritySeriesSource => ({ kind: "security",
+  instrument: { symbol: "TEST", exchange: "NYSE" }, fieldId: `valuation.${metric}`,
+  period: "annual", timestampMode: "available-at" });
+const fixture = (): TickerFinancials => ({ financialCurrency: "USD",
+  quote: { symbol: "TEST", currency: "USD", price: 60, change: 0, changePercent: 0,
+    lastUpdated: Date.parse("2026-09-11T20:00:00Z") },
+  annualStatements: [{ date: "2025-12-31", availableAt: "2026-09-10T14:00:00Z", currency: "USD",
+    eps: 10, totalRevenue: 100, dilutedShares: 10, totalDebt: 20, cashAndCashEquivalents: 5,
+    ebitda: 30, freeCashFlow: 20 }], quarterlyStatements: [],
+  priceHistory: [{ date: new Date("2026-09-09"), close: 50 },
+    { date: new Date("2026-09-10T13:30:00Z"), open: 54, high: 56, low: 53, close: 55 }],
+});
+const fields = ["trailingPE", "priceSales", "evSales", "evEbitda", "priceFcf"];
+
+test("stale quote-derived Current multiples are withheld while historical ratios and input evidence survive", () => {
+  const data = fixture();
+  const history = fields.map((field) => extractFundamentalSeries(data, source(field))[0]);
+  data.quote!.stale = true;
+  const original = JSON.stringify(data);
+  fields.forEach((field, index) => {
+    expect(extractFundamentalSeries(data, source(field))).toEqual([history[index]!]);
+    expect(valuationPriceIssues(data, source(field))).toEqual([expect.objectContaining({ kind: "quote", reason: "stale",
+      quote: expect.objectContaining({ price: 60, lastUpdated: data.quote!.lastUpdated, stale: true }) })]);
+  });
+  expect(JSON.stringify(data)).toBe(original);
+  data.quote!.stale = false;
+  for (const field of fields) expect(extractFundamentalSeries(data, source(field)).at(-1)?.periodLabel).toBe("Current");
+});
+
+test("invalid current quote price or timestamp never borrows the historical close", () => {
+  for (const patch of [{ price: NaN }, { price: Infinity }, { price: 0 }, { price: -1 },
+    { lastUpdated: NaN }, { lastUpdated: 0 }, { lastUpdated: -1 }, { lastUpdated: 9e20 }]) {
+    const data = fixture(); Object.assign(data.quote!, patch);
+    const points = extractFundamentalSeries(data, source());
+    expect(points.map((point) => point.value)).toEqual([5.5]);
+    expect(points.some((point) => point.periodLabel === "Current")).toBe(false);
+    expect(valuationPriceIssues(data, source())[0]?.kind).toBe("quote");
+  }
+  const afterHours = fixture(); Object.assign(afterHours.quote!, { high: 58, low: 53, price: 60 });
+  expect(extractFundamentalSeries(afterHours, source()).at(-1)?.value).toBe(6);
+  expect(valuationPriceIssues(afterHours, source())).toEqual([]);
+});
+
+test("a latest contradictory historical bar leaves a diagnostic gap instead of using its close or an older bar", () => {
+  const data = fixture(); data.quote!.stale = true;
+  data.priceHistory[1]!.open = 70;
+  const original = JSON.stringify(data.priceHistory);
+  for (const field of fields) {
+    const points = extractFundamentalSeries(data, source(field));
+    expect(points).toHaveLength(1);
+    expect(points[0]?.value).toBeNull();
+    expect(points[0]?.observedAt.toISOString()).toBe("2025-12-31T00:00:00.000Z");
+    expect(points[0]?.provenance?.priceHistoryIntegrity?.sourcePoints[0]).toMatchObject({ open: 70, high: 56, close: 55 });
+  }
+  expect(JSON.stringify(data.priceHistory)).toBe(original);
+  // A valid close-only row at the same time cannot erase contradictory evidence.
+  data.priceHistory.push({ date: data.priceHistory[1]!.date, close: 55 });
+  expect(extractFundamentalSeries(data, source())[0]?.value).toBeNull();
+  data.priceHistory.reverse();
+  expect(extractFundamentalSeries(data, source())[0]?.value).toBeNull();
+  // A genuinely newer valid observation before availability restores the ratio.
+  data.priceHistory.push({ date: new Date("2026-09-10T13:45:00Z"), close: 57 });
+  expect(extractFundamentalSeries(data, source())[0]?.value).toBe(5.7);
+  // Removing the corrupt source through a corrected input also restores it.
+  data.priceHistory = [{ date: new Date("2026-09-10T13:30:00Z"), close: 55 }];
+  expect(extractFundamentalSeries(data, source())[0]?.value).toBe(5.5);
+});
+
+test("later corruption and invalid dates cannot change an earlier valuation; serialized history remains supported", () => {
+  const data = fixture(); data.quote!.stale = true;
+  data.priceHistory.push({ date: new Date("2026-09-11"), open: 100, high: 56, low: 50, close: 55 });
+  data.priceHistory.push({ date: null as unknown as Date, close: 99 });
+  data.priceHistory = JSON.parse(JSON.stringify(data.priceHistory));
+  expect(extractFundamentalSeries(data, source())[0]?.value).toBe(5.5);
+  expect(extractFundamentalSeries(data, source())[0]?.provenance?.priceHistoryIntegrity).toBeUndefined();
+});
+
+test("an unusable latest historical close does not silently fall back to an older quote", () => {
+  for (const close of [0, -5, NaN, Infinity]) {
+    const data = fixture(); data.quote = undefined;
+    // Keep declared price units through a metadata-only quote.
+    data.quote = { ...fixture().quote!, lastUpdated: 0 };
+    data.priceHistory = [{ date: new Date("2026-09-09"), close: 50 },
+      { date: new Date("2026-09-10"), close }];
+    expect(extractFundamentalSeries(data, source())[0]?.value).toBeNull();
+    expect(valuationPriceIssues(data, source())).toEqual(expect.arrayContaining([
+      expect.objectContaining({ kind: "history", reason: "invalid-price" }),
+    ]));
+  }
+});
+
+async function load(data: TickerFinancials, viewport: Partial<ChartSpec["viewport"]> = {}, studies: ChartSpec["studies"] = []) {
+  const spec: ChartSpec = { version: CHART_SPEC_VERSION, viewport: { range: "5Y", resolution: "1d", ...viewport },
+    panels: [{ id: "main" }], studies, series: [{ id: "pe", source: source(), style: "line",
+      transform: "raw", axis: "left", panelId: "main", interpolation: "none" }] };
+  return loadChartPaneModel(spec, { marketData: createTestDataProvider({ getTickerFinancials: async () => data,
+    getPriceHistoryForResolution: async () => data.priceHistory, getQuote: async () => data.quote! }),
+    config: createDefaultConfig("/tmp/valuation-price-test"), apiClient: {} as any, signal: new AbortController().signal });
+}
+
+test("actual resolver/export retain stale-source diagnostics and historical values, then recover on a fresh quote", async () => {
+  const data = fixture(); data.quote!.stale = true;
+  const model = await load(data);
+  expect(model.series[0]?.points.map((point) => point.value)).toEqual([5.5]);
+  expect(model.complete).toBe(false);
+  expect(model.metadata?.warnings).toEqual(expect.arrayContaining([expect.stringContaining("source quote is stale")]));
+  expect(model.metadata?.valuationPriceIssues).toEqual([expect.objectContaining({ seriesId: "pe", issues: [
+    expect.objectContaining({ reason: "stale", quote: expect.objectContaining({ price: 60, lastUpdated: data.quote!.lastUpdated, stale: true }) }),
+  ] })]);
+  expect(model.snapshot.financials[0]?.[1].quote?.stale).toBe(true);
+  data.quote!.stale = false;
+  const recovered = await load(data);
+  expect(recovered.series[0]?.points.at(-1)?.value).toBe(6);
+  expect(recovered.metadata?.valuationPriceIssues).toBeUndefined();
+  expect(recovered.complete).not.toBe(false);
+});
+
+test("future Current quote times retain invalid-time provenance without changing historical multiples", async () => {
+  const now = Date.parse("2026-09-12T04:00:00Z");
+  const clock = spyOn(Date, "now").mockReturnValue(now);
+  const data = fixture();
+  const future = now + 86_400_000;
+  data.quote!.lastUpdated = future;
+  const original = JSON.stringify(data);
+  try {
+    for (const field of fields) {
+      expect(extractFundamentalSeries(data, source(field)).some(point => point.periodLabel === "Current")).toBe(false);
+      expect(valuationPriceIssues(data, source(field))).toEqual([expect.objectContaining({ reason: "invalid-timestamp", quote: expect.objectContaining({ lastUpdated: future, price: 60 }) })]);
+    }
+    const model = await load(data);
+    expect(model.series[0]?.points.map(point => point.value)).toEqual([5.5]);
+    expect(model.complete).toBe(false);
+    expect(model.metadata?.warnings).toEqual(expect.arrayContaining([expect.stringContaining("source quote timestamp is unavailable")]));
+    expect(model.metadata?.valuationPriceIssues).toEqual([expect.objectContaining({ issues: [expect.objectContaining({ reason: "invalid-timestamp", quote: expect.objectContaining({ lastUpdated: future }) })] })]);
+    expect(JSON.stringify(data)).toBe(original);
+    for (const viewport of [{ dateWindow: { start: "2026-09-10T13:00:00Z", end: "2026-09-10T20:00:00Z" } }, { maxPoints: 1 }]) {
+      const historical = await load(data, viewport);
+      expect(historical.complete).not.toBe(false);
+      expect(historical.metadata?.valuationPriceIssues).toBeUndefined();
+    }
+    data.quote!.lastUpdated = now - 60_000;
+    const recovered = await load(data);
+    expect(recovered.series[0]?.points.at(-1)).toMatchObject({ periodLabel: "Current", value: 6 });
+    expect(recovered.metadata?.valuationPriceIssues).toBeUndefined();
+    expect(recovered.complete).not.toBe(false);
+  } finally { clock.mockRestore(); }
+});
+
+test("actual resolver/export count a null corrupt valuation as unavailable and retain the original candle", async () => {
+  const data = fixture(); data.quote!.stale = true; data.priceHistory[1]!.open = 70;
+  const model = await load(data);
+  expect(model.complete).toBe(false);
+  expect(model.unavailableSymbols).toEqual(["TEST:XNYS"]);
+  expect(model.metadata?.priceHistoryIntegrity).toEqual(expect.arrayContaining([
+    expect.objectContaining({ seriesId: "pe", integrity: expect.objectContaining({ sourcePoints: [expect.objectContaining({ open: 70, high: 56 })] }) }),
+  ]));
+  expect(model.metadata?.summaries).toEqual(expect.arrayContaining([expect.objectContaining({ endValue: null })]));
+  expect(model.metadata?.warnings).toEqual(expect.arrayContaining([expect.stringContaining("inconsistent OHLC")]));
+});
+
+test("historical date windows and period limits do not inherit excluded current or older price failures", async () => {
+  const data = fixture(); data.quote!.stale = true;
+  for (const viewport of [{ dateWindow: { start: "2026-09-10T13:00:00Z", end: "2026-09-10T20:00:00Z" } }, { maxPoints: 1 }]) {
+    const model = await load(data, viewport);
+    expect(model.series[0]?.points.map((point) => point.value)).toEqual([5.5]);
+    expect(model.complete).not.toBe(false);
+    expect(model.metadata?.valuationPriceIssues).toBeUndefined();
+    expect(model.chart.warnings.some((warning) => warning.includes("source quote"))).toBe(false);
+  }
+  data.annualStatements.unshift({ ...data.annualStatements[0]!, date: "2024-12-31", availableAt: "2025-03-01" });
+  data.priceHistory.unshift({ date: new Date("2025-02-28"), close: 0 });
+  const limited = await load(data, { maxPoints: 1 });
+  expect(limited.series[0]?.points.map((point) => point.value)).toEqual([5.5]);
+  expect(limited.complete).toBe(true);
+  expect(limited.metadata?.valuationPriceIssues).toBeUndefined();
+  data.quote!.lastUpdated = NaN;
+  expect((await load(data, { dateWindow: { start: "2026-09-10T13:00:00Z", end: "2026-09-10T20:00:00Z" } })).complete).not.toBe(false);
+});
+
+test("all-missing requested periods retain their price evidence and remain unavailable", async () => {
+  const data = fixture(); data.quote!.stale = true; data.priceHistory[1]!.open = 70;
+  const model = await load(data, { maxPoints: 1 });
+  expect(model.series[0]?.points.map((point) => point.value)).toEqual([null]);
+  expect(model.complete).toBe(false);
+  expect(model.unavailableSymbols).toEqual(["TEST:XNYS"]);
+  expect(model.metadata?.priceHistoryIntegrity).toEqual(expect.arrayContaining([
+    expect.objectContaining({ integrity: expect.objectContaining({ sourcePoints: [expect.objectContaining({ open: 70 })] }) }),
+  ]));
+  expect(model.metadata?.valuationPriceIssues).toBeUndefined(); // Current was not requested.
+});
+
+test("invalid non-OHLC prices interrupt studies and retain the reason during later warmup", async () => {
+  const data = fixture(); data.quote!.stale = true;
+  data.annualStatements = [2023, 2024, 2025, 2026].map((year) => ({ date: `${year}-12-31`, availableAt: `${year + 1}-03-01`, currency: "USD", eps: 10 }));
+  data.priceHistory = [50, 0, 70, 80].map((close, index) => ({ date: new Date(`${2024 + index}-03-01`), close }));
+  const points = extractFundamentalSeries(data, source());
+  expect(points.map((point) => point.value)).toEqual([5, null, 7, 8]);
+  const study: ChartSpec["studies"][number] = { id: "sma", kind: "sma", inputSeriesIds: ["pe"], parameters: { period: 2 }, panelId: "main", axis: "left" };
+  const outputs = resolveStudies([{ id: "pe", label: "P/E", color: "#fff", unit: "x", unitGroup: "ratio", nativeFrequency: "annual",
+    dataShape: "scalar", style: "line", transform: "raw", axis: "left", panelId: "main", interpolation: "none", points }], [study]);
+  expect(outputs.series[0]?.points.map((point) => point.value)).toEqual([null, null, 7.5]);
+  const warmup = await load(data, { dateWindow: { start: "2026-03-01", end: "2026-03-02" } }, [study]);
+  expect(warmup.series.find((entry) => entry.id === "sma")?.points[0]?.value).toBeNull();
+  expect(warmup.complete).toBe(false);
+  expect(warmup.metadata?.valuationPriceIssues).toEqual(expect.arrayContaining([
+    expect.objectContaining({ seriesId: "sma", issues: [expect.objectContaining({ kind: "history", reason: "invalid-price", point: expect.objectContaining({ close: 0 }) })] }),
+  ]));
+  expect(warmup.chart.warnings.some((warning) => warning.includes("Historical valuation unavailable"))).toBe(true);
+  expect(warmup.chart.warnings.some((warning) => warning.includes("inconsistent OHLC"))).toBe(false);
+});
+
+test.each(["NaN", "future"] as const)("actual live quote status and %s timestamp recovery recompute Current valuations", async invalidKind => {
+  const data = fixture();
+  const spec: ChartSpec = { version: CHART_SPEC_VERSION, viewport: { range: "5Y", resolution: "1d" }, panels: [{ id: "main" }],
+    studies: [], series: [{ id: "pe", source: source(), style: "line", transform: "raw", axis: "left", panelId: "main", interpolation: "none" }] };
+  let emit!: Parameters<NonNullable<ReturnType<typeof createTestDataProvider>["subscribeQuotes"]>>[1];
+  let target!: Parameters<NonNullable<ReturnType<typeof createTestDataProvider>["subscribeQuotes"]>>[0][number];
+  const provider = createTestDataProvider({ getTickerFinancials: async () => data, getQuote: async () => data.quote!,
+    getPriceHistoryForResolution: async () => data.priceHistory,
+    subscribeQuotes: (targets, listener) => { target = targets[0]!; emit = listener; return () => {}; } });
+  const results: Awaited<ReturnType<typeof resolveChartSpecData>>[] = [];
+  const stop = subscribeToLiveChartQuotes({ spec, dataProvider: provider, refreshIntervalMs: 0,
+    onRefresh: async (quoteOverrides) => { results.push(await resolveChartSpecData(spec, { dataProvider: provider,
+      now: new Date("2026-09-12"), quoteOverrides })); } });
+  async function waitForCount(count: number) {
+    for (let tries = 0; tries < 100 && results.length < count; tries++) await Bun.sleep(2);
+    expect(results).toHaveLength(count);
+  }
+  const valid = { ...data.quote!, stale: false };
+  try {
+    emit(target, { ...valid, lastUpdated: invalidKind === "NaN" ? NaN : Date.now() + 86_400_000, receivedAt: 1 });
+    await waitForCount(1);
+    // A valid timestamp must dislodge the malformed prior stream observation.
+    emit(target, { ...valid, receivedAt: 2 });
+    await waitForCount(2);
+    expect(results.at(-1)?.series[0]?.points.at(-1)?.value).toBe(6);
+    emit(target, { ...valid, stale: true, receivedAt: 3 });
+    await waitForCount(3);
+    expect(results.at(-1)?.series[0]?.points.map((point) => point.value)).toEqual([5.5]);
+    expect(results.at(-1)?.warnings.some((warning) => warning.includes("source quote is stale"))).toBe(true);
+    emit(target, { ...valid, stale: false, receivedAt: 4 });
+    await waitForCount(4);
+    expect(results.at(-1)?.series[0]?.points.at(-1)?.value).toBe(6);
+    expect(results.at(-1)?.warnings.some((warning) => warning.includes("source quote is stale"))).toBe(false);
+  } finally { stop(); }
+  for (const invalid of [NaN, Infinity, 0, -1, 9e20, Date.now() + 86_400_000]) {
+    data.quote!.lastUpdated = invalid;
+    const recovered = await resolveChartSpecData(spec, { dataProvider: provider, now: new Date("2026-09-12"),
+      quoteOverrides: new Map([[chartQuoteOverrideKeyForSource(source()), valid]]) });
+    expect(recovered.series[0]?.points.at(-1)?.value).toBe(6);
+    expect(recovered.series[0]?.valuationPriceIssues).toBeUndefined();
+  }
+});

package/src/time-series/valuation-price.ts

@@ -0,0 +1,68 @@
+import type { PricePoint, Quote } from "../types/financials";
+import { hasValidQuoteObservationTime } from "../market-data/quotes/freshness";
+import { mergePriceHistoryIntegrity, pricePointIntegrity } from "../utils/price-history-integrity";
+
+export type ValuationPriceIssue = ({
+  kind: "quote";
+  reason: "stale" | "invalid-price" | "invalid-timestamp";
+  quote: Pick<Quote, "symbol" | "currency" | "price" | "lastUpdated" | "stale" | "providerId">;
+} | {
+  kind: "history";
+  reason: "invalid-price";
+  point: Omit<PricePoint, "date"> & { date: string };
+}) & { affectedAt?: string };
+
+export function valuationQuoteIssue(quote: Quote | undefined): ValuationPriceIssue | undefined {
+  if (!quote) return undefined;
+  const validObservationTime = hasValidQuoteObservationTime(quote);
+  const reason = quote.stale === true ? "stale"
+    : !Number.isFinite(quote.price) || quote.price <= 0 ? "invalid-price"
+      : !validObservationTime ? "invalid-timestamp" : null;
+  if (!reason) return undefined;
+  const { symbol, currency, price, lastUpdated, stale, providerId } = quote;
+  return { kind: "quote", reason, quote: { symbol, currency, price, lastUpdated, stale, providerId },
+    ...(validObservationTime
+      ? { affectedAt: new Date(lastUpdated).toISOString() } : {}) };
+}
+
+/** Select the source observation before validating it; a rejected latest row
+ * cannot silently borrow an older price. Conflicting rows at that same time
+ * retain any reported OHLC contradiction until the source replaces them. */
+export function valuationPriceAtOrBefore(history: readonly PricePoint[], date: string) {
+  const target = Date.parse(date);
+  if (!Number.isFinite(target)) return null;
+  let latest = -Infinity;
+  let points: PricePoint[] = [];
+  for (const point of history) {
+    // Persisted Date values arrive as strings. Missing dates must not become epoch zero.
+    const time = point.date instanceof Date ? point.date.getTime()
+      : typeof point.date === "string" ? Date.parse(point.date) : NaN;
+    if (!Number.isFinite(time) || time > target || time < latest) continue;
+    if (time > latest) { latest = time; points = []; }
+    points.push(point);
+  }
+  if (!points.length) return null;
+  const issues = points.flatMap((point) => {
+    const integrity = pricePointIntegrity(point);
+    return integrity ? [integrity] : [];
+  });
+  if (issues.length) return { price: null, integrity: mergePriceHistoryIntegrity(...issues) };
+  const invalid = points.find((point) => !Number.isFinite(point.close) || point.close <= 0);
+  if (invalid) return {
+    price: null,
+    issue: { kind: "history", reason: "invalid-price", point: Object.freeze({ ...invalid,
+      date: new Date(invalid.date).toISOString(),
+      ...(invalid.historySource ? { historySource: Object.freeze({ ...invalid.historySource }) } : {}),
+    }) } satisfies ValuationPriceIssue,
+  };
+  return { price: points[0]!.close };
+}
+
+export function valuationPriceWarning(issues: readonly ValuationPriceIssue[]): string | undefined {
+  const messages = issues.map((issue) => issue.kind === "history"
+    ? "Historical valuation unavailable: source price is invalid."
+    : issue.reason === "stale" ? "Current valuation unavailable: source quote is stale."
+      : issue.reason === "invalid-price" ? "Current valuation unavailable: source quote price is invalid."
+        : "Current valuation unavailable: source quote timestamp is unavailable.");
+  return messages.length ? [...new Set(messages)].join(" ") : undefined;
+}