gloomberb 0.13.3 → 0.14.1

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

@@ -0,0 +1,133 @@
+import { scalarPointValue } from "./alignment";
+import { getTimeSeriesField } from "./field-catalog";
+import type { ChartSpec, ResolvedSeries, TimeSeriesPoint } from "./types";
+import type { ManualChartResolution } from "./resolution";
+import { zonedDateTimeParts } from "../utils/zoned-date-time";
+
+export const PRICE_COMPARISON_BASIS = "Price returns in each listing's currency; cash distributions and FX conversion excluded.";
+
+export interface PriceComparison {
+  seriesIds: string[];
+  /** Display envelope; each leg retains its exact source endpoints below. */
+  start: number | null;
+  end: number | null;
+  notice: string;
+  alignment?: "session-date" | "timestamp";
+  sourceBounds?: Record<string, { start: number; end: number }>;
+}
+
+function observationDate(time: number, series: ResolvedSeries): string {
+  const date = new Date(time);
+  // Date-only provider bars are represented as UTC midnight throughout the app.
+  // Timestamped bars use the exchange's local calendar; crypto uses UTC.
+  if (time % 86_400_000 === 0 || !series.timeBasis) return date.toISOString().slice(0, 10);
+  const { year, month, day } = zonedDateTimeParts(time, series.timeBasis.timeZone);
+  return `${year}-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
+}
+
+/** Date-only research windows select local sessions; runtime timestamps remain exact. */
+export function priceObservationWindowFilter(
+  series: ResolvedSeries,
+  bounds: { start: number | null; end: number | null },
+  resolution: ManualChartResolution | "auto",
+  dateWindow: ChartSpec["viewport"]["dateWindow"] | null,
+): (time: number) => boolean {
+  const calendarBars = resolution === "1d" || resolution === "1wk" || resolution === "1mo";
+  const calendarWindow = calendarBars && dateWindow
+    && /^\d{4}-\d{2}-\d{2}$/.test(dateWindow.start)
+    && /^\d{4}-\d{2}-\d{2}$/.test(dateWindow.end) ? dateWindow : null;
+  return (time) => {
+    if (!Number.isFinite(time)) return false;
+    const key = calendarWindow ? observationDate(time, series) : null;
+    return key !== null
+      ? key >= calendarWindow!.start && key <= calendarWindow!.end
+      : (bounds.start === null || time >= bounds.start) && (bounds.end === null || time <= bounds.end);
+  };
+}
+
+export function priceComparisonBoundsForSeries(series: ResolvedSeries, comparison: PriceComparison | null) {
+  return comparison?.sourceBounds?.[series.id] ?? comparison;
+}
+
+function displayDate(time: number): string {
+  const iso = new Date(time).toISOString();
+  return iso.endsWith("T00:00:00.000Z") ? iso.slice(0, 10) : iso.replace("T", " ").replace(".000Z", " UTC");
+}
+
+/** Comparable normalized closing-price legs share observed endpoints. Other chart meanings are unchanged. */
+export function priceComparisonSeriesIds(spec: ChartSpec): string[] | null {
+  if (spec.viewport.maxPoints !== undefined) return null;
+  const visible = spec.series.filter((entry) => entry.visible !== false);
+  if (visible.length < 2 || !visible.every((entry) => {
+    const field = entry.source.kind === "security" ? getTimeSeriesField(entry.source.fieldId)?.id : null;
+    return (field === "market.close" || field === "market.ohlcv")
+      && (entry.transform === "percent" || entry.transform === "index100")
+      && entry.transform === visible[0]!.transform
+      && entry.panelId === visible[0]!.panelId
+      && entry.source.kind === "security" && visible[0]!.source.kind === "security"
+      && (entry.source.period ?? "auto") === (visible[0]!.source.period ?? "auto");
+  })) return null;
+  return visible.map((entry) => entry.id);
+}
+
+export function resolvePriceComparison(
+  spec: ChartSpec,
+  series: readonly ResolvedSeries[],
+  bounds: { start: number | null; end: number | null },
+  resolution: ManualChartResolution | "auto" = spec.viewport.resolution,
+  dateWindow: ChartSpec["viewport"]["dateWindow"] | null = spec.viewport.dateWindow,
+): PriceComparison | null {
+  const seriesIds = priceComparisonSeriesIds(spec);
+  if (!seriesIds) return null;
+  const byId = new Map(series.map((entry) => [entry.id, entry]));
+  const calendarBars = resolution === "1d" || resolution === "1wk" || resolution === "1mo";
+  const observations = seriesIds.map((id) => {
+    const entry = byId.get(id);
+    if (!entry) return new Map<string, TimeSeriesPoint>();
+    const inWindow = priceObservationWindowFilter(entry, bounds, resolution, dateWindow);
+    return new Map(entry.points.flatMap((point) => {
+      const time = point.date.getTime();
+      if (!inWindow(time) || scalarPointValue(point) === null) return [];
+      return [[calendarBars ? observationDate(time, entry) : String(time), point] as const];
+    }));
+  });
+  const shared = [...observations[0]!.keys()].filter((key) => observations.every((points) => points.has(key)))
+    .sort((a, b) => calendarBars ? a.localeCompare(b) : Number(a) - Number(b));
+  const start = shared.find((key) => observations.every((points) => {
+    const point = points.get(key);
+    return point && scalarPointValue(point) !== 0;
+  }));
+  const end = shared.at(-1);
+  if (start === undefined || end === undefined || start === end) return {
+    seriesIds, start: null, end: null,
+    notice: `${PRICE_COMPARISON_BASIS} Comparison unavailable: need two shared dates and a nonzero baseline.`,
+  };
+  const sourceBounds = Object.fromEntries(seriesIds.map((id, index) => [id, {
+    start: observations[index]!.get(start)!.date.getTime(),
+    end: observations[index]!.get(end)!.date.getTime(),
+  }]));
+  return {
+    seriesIds,
+    start: Math.min(...Object.values(sourceBounds).map((range) => range.start)),
+    end: Math.max(...Object.values(sourceBounds).map((range) => range.end)),
+    alignment: calendarBars ? "session-date" : "timestamp",
+    sourceBounds,
+    notice: calendarBars
+      ? `${PRICE_COMPARISON_BASIS} Shared calendar dates: ${start} to ${end}; market session times may differ.`
+      : `${PRICE_COMPARISON_BASIS} Shared observations: ${displayDate(Number(start))} to ${displayDate(Number(end))}.`,
+  };
+}
+
+/** Clip only compared legs; raw observations and study inputs stay available in the source cache. */
+export function clipPriceComparison(series: ResolvedSeries, comparison: PriceComparison | null): ResolvedSeries {
+  if (!comparison?.seriesIds.includes(series.id)) return series;
+  const { start, end } = priceComparisonBoundsForSeries(series, comparison)!;
+  return {
+    ...series,
+    // The legend must describe the compared endpoint, not a newer one-leg quote.
+    latestChangePercent: undefined,
+    points: start === null || end === null ? [] : series.points.filter((point) => (
+      point.date.getTime() >= start && point.date.getTime() <= end
+    )),
+  };
+}

package/src/time-series/price-history-integrity-window.test.ts

@@ -0,0 +1,137 @@
+import { expect, test } from "bun:test";
+import type { PricePoint } from "../types/financials";
+import type { HeadlessPaneContext } from "../types/headless";
+import { createTestDataProvider } from "../test-support/data-provider";
+import { loadChartPaneModel } from "../plugins/builtin/chart-composer/headless";
+import { CHART_SPEC_VERSION, type ChartSpec } from "./types";
+import { chartQuoteOverrideKeyForSource } from "./live-quotes";
+import { ChartResolveCache, resolveChartSpecData, seedChartResolutionResult } from "./resolve";
+
+const row = (date: string, close = 10, bad = false): PricePoint => ({
+  date: new Date(date), close, ...(bad ? { open: 30, high: 20, low: 5 } : {}),
+});
+function chart(start = "2026-09-08", end = "2026-09-10"): ChartSpec {
+  return {
+    version: CHART_SPEC_VERSION,
+    viewport: { range: "1M", resolution: "1d", dateWindow: { start, end } },
+    panels: [{ id: "main" }], studies: [],
+    series: ["A", "B"].map((symbol) => ({
+      id: symbol, source: { kind: "security", instrument: { symbol, exchange: "NASDAQ" }, fieldId: "market.close" },
+      style: "line", transform: "percent", axis: "left", panelId: "main", interpolation: "none",
+    })),
+  };
+}
+function provider(histories: Record<string, PricePoint[]>) {
+  const getHistory = async (symbol: string) => histories[symbol] ?? [];
+  return createTestDataProvider({
+    getQuote: async (symbol) => ({ symbol, currency: "USD", instrumentType: "ETF", price: 12, change: 0, changePercent: 0, lastUpdated: 0 }),
+    getPriceHistory: getHistory, getPriceHistoryForResolution: getHistory, getDetailedPriceHistory: getHistory,
+  });
+}
+
+test("rejected requested comparison endpoints remain exported and incomplete while valid shared returns survive", async () => {
+  for (const edge of [0, 2]) {
+    const spec = chart();
+    const histories = {
+      A: [8, 9, 10].map((day, index) => row(`2026-09-${String(day).padStart(2, "0")}`, 10 + index, index === edge)),
+      B: [8, 9, 10].map((day, index) => row(`2026-09-${String(day).padStart(2, "0")}`, 10 + index)),
+    };
+    const model = await loadChartPaneModel(spec, { marketData: provider(histories) } as HeadlessPaneContext);
+    const seed = seedChartResolutionResult(spec, new Map(spec.series.map((entry) => [chartQuoteOverrideKeyForSource(entry.source), histories[entry.id as "A" | "B"]])))!;
+    expect(model.complete).toBe(false);
+    expect(model.chart.priceHistoryIntegrity).toEqual(seed.priceHistoryIntegrity);
+    expect(model.metadata!.priceHistoryIntegrity).toEqual(model.chart.priceHistoryIntegrity);
+    for (const result of [model.chart, seed]) {
+      expect(result.priceHistoryIntegrity).toHaveLength(1);
+      expect(result.priceHistoryIntegrity![0]).toMatchObject({ seriesId: "A", scope: "requested-observation" });
+      expect(result.priceHistoryIntegrity![0]!.integrity.sourcePoints).toEqual([{ ...histories.A[edge], date: histories.A[edge]!.date.toISOString() }]);
+      expect(result.series.every((entry) => entry.points.length === 2 && entry.points.every((point) => !point.provenance?.priceHistoryIntegrity))).toBe(true);
+      expect(result.series.every((entry) => entry.points[0]!.value === 0)).toBe(true);
+      expect(result.priceComparison?.start).toBe(Date.parse(edge === 0 ? "2026-09-09" : "2026-09-08"));
+      expect(result.priceComparison?.end).toBe(Date.parse(edge === 0 ? "2026-09-10" : "2026-09-09"));
+      expect(result.warnings.some((warning) => warning.includes("inconsistent OHLC"))).toBe(true);
+    }
+    expect((model.metadata!.summaries as Array<{ return: number | null }>).every((summary) => summary.return !== null)).toBe(true);
+    expect((model.metadata!.notices as string[]).some((notice) => notice.includes("inconsistent OHLC"))).toBe(true);
+  }
+});
+
+test("integrity metadata excludes unrelated corruption in the loaded navigation buffer", async () => {
+  const spec = chart();
+  const histories = {
+    A: [row("2026-09-07", 10, true), row("2026-09-08", 10), row("2026-09-09", 11), row("2026-09-10", 12), row("2026-09-11", 12, true)],
+    B: [row("2026-09-08", 10), row("2026-09-09", 11), row("2026-09-10", 12)],
+  };
+  const model = await loadChartPaneModel(spec, { marketData: provider(histories) } as HeadlessPaneContext);
+  expect(model.complete).not.toBe(false);
+  expect(model.chart.priceHistoryIntegrity).toBeUndefined();
+  expect(model.metadata!.priceHistoryIntegrity).toBeUndefined();
+  expect(model.chart.warnings.some((warning) => warning.includes("inconsistent OHLC"))).toBe(false);
+});
+
+test("date-only integrity selection uses local market sessions while explicit and panned timestamps stay exact", async () => {
+  const spec = chart("2026-01-08", "2026-01-10");
+  spec.series[0]!.source = { kind: "security", instrument: { symbol: "A", exchange: "ASX" }, fieldId: "market.close" };
+  const histories = {
+    A: [row("2026-01-06T23:00:00Z", 10, true), row("2026-01-07T23:00:00Z", 10, true), row("2026-01-08T23:00:00Z", 11), row("2026-01-09T23:00:00Z", 12), row("2026-01-11T23:00:00Z", 12, true)],
+    B: [row("2026-01-08T14:30:00Z", 10), row("2026-01-09T14:30:00Z", 11), row("2026-01-10T14:30:00Z", 12)],
+  };
+  const sources = { dataProvider: provider(histories) };
+  const selected = await resolveChartSpecData(spec, sources);
+  const seed = seedChartResolutionResult(spec, new Map(spec.series.map((entry) => [chartQuoteOverrideKeyForSource(entry.source), histories[entry.id as "A" | "B"]])))!;
+  for (const result of [selected, seed]) {
+    expect(result.priceHistoryIntegrity?.flatMap((entry) => entry.integrity.sourcePoints.map((point) => point.date))).toEqual(["2026-01-07T23:00:00.000Z"]);
+    expect(result.priceComparison?.sourceBounds?.A.start).toBe(Date.parse("2026-01-08T23:00:00Z"));
+  }
+  const exact = { start: new Date("2026-01-08T00:00:00Z"), end: new Date("2026-01-10T23:59:59.999Z") };
+  const panned = await resolveChartSpecData(spec, sources, new ChartResolveCache(), { requestViewport: exact });
+  expect(panned.priceHistoryIntegrity).toBeUndefined();
+  expect(panned.warnings.some((warning) => warning.includes("inconsistent OHLC"))).toBe(false);
+  spec.viewport.dateWindow = { start: exact.start.toISOString(), end: exact.end.toISOString() };
+  expect((await resolveChartSpecData(spec, sources)).priceHistoryIntegrity).toBeUndefined();
+});
+
+test("a comparison with no usable overlap still preserves rejected selected rows", async () => {
+  const spec = chart();
+  const histories = { A: [row("2026-09-08", 10, true), row("2026-09-09", 11)], B: [row("2026-09-08", 10), row("2026-09-09", 11)] };
+  const model = await loadChartPaneModel(spec, { marketData: provider(histories) } as HeadlessPaneContext);
+  expect(model.chart.priceComparison?.start).toBeNull();
+  expect(model.series.every((entry) => entry.points.length === 0)).toBe(true);
+  expect(model.chart.priceHistoryIntegrity![0]!.integrity.sourcePoints[0]!.open).toBe(30);
+  expect(model.complete).toBe(false);
+});
+
+test("observation-count windows exclude older corrupt rows while retaining a rejected selected row", async () => {
+  const spec = chart();
+  spec.viewport = { range: "ALL", resolution: "1d", maxPoints: 2 };
+  const histories = {
+    A: [row("2026-09-07", 10, true), row("2026-09-08", 10), row("2026-09-09", 11), row("2026-09-10", 12)],
+    B: [row("2026-09-08", 10), row("2026-09-09", 11), row("2026-09-10", 12)],
+  };
+  const model = await loadChartPaneModel(spec, { marketData: provider(histories) } as HeadlessPaneContext);
+  const seeded = seedChartResolutionResult(spec, new Map(spec.series.map((entry) => [chartQuoteOverrideKeyForSource(entry.source), histories[entry.id as "A" | "B"]])))!;
+  expect(model.complete).not.toBe(false);
+  for (const result of [model.chart, seeded]) {
+    expect(result.series.every((entry) => entry.points.length === 2)).toBe(true);
+    expect(result.priceHistoryIntegrity).toBeUndefined();
+    expect(result.warnings.some((warning) => warning.includes("inconsistent OHLC"))).toBe(false);
+  }
+  histories.A[3] = row("2026-09-10", 12, true);
+  const rejected = await loadChartPaneModel(spec, { marketData: provider(histories) } as HeadlessPaneContext);
+  expect(rejected.complete).toBe(false);
+  expect(rejected.chart.priceHistoryIntegrity?.every((entry) => entry.integrity.sourcePoints.every((point) => point.date === "2026-09-10T00:00:00.000Z"))).toBe(true);
+});
+
+test("a hidden source used only to retain the chart timeline does not report unrelated integrity warnings", async () => {
+  const spec = chart();
+  spec.series[0]!.visible = false;
+  const histories = {
+    A: [row("2026-09-08", 10, true), row("2026-09-09", 11), row("2026-09-10", 12)],
+    B: [row("2026-09-08", 10), row("2026-09-09", 11), row("2026-09-10", 12)],
+  };
+  const model = await loadChartPaneModel(spec, { marketData: provider(histories) } as HeadlessPaneContext);
+  expect(model.chart.timelineSeries?.[0]?.points.some((point) => point.provenance?.priceHistoryIntegrity)).toBe(true);
+  expect(model.chart.priceHistoryIntegrity).toBeUndefined();
+  expect(model.complete).not.toBe(false);
+  expect(model.chart.warnings.some((warning) => warning.includes("inconsistent OHLC"))).toBe(false);
+});

package/src/time-series/price-history-integrity.test.ts

@@ -0,0 +1,195 @@
+import { expect, test } from "bun:test";
+import type { PricePoint } from "../types/financials";
+import type { HeadlessPaneContext } from "../types/headless";
+import { createTestDataProvider } from "../test-support/data-provider";
+import { pricePointIntegrity, pricePointValues } from "../utils/price-history-integrity";
+import { historicalPricesHeadless } from "../plugins/builtin/ticker-detail/headless";
+import { loadChartPaneModel } from "../plugins/builtin/chart-composer/headless";
+import { extractPriceSeries } from "./market";
+import { appendLiveQuotePoint } from "./chart-data";
+import { seedChartResolutionResult } from "./resolve";
+import { chartQuoteOverrideKeyForSource } from "./live-quotes";
+import { resolveStudies } from "./studies";
+import { buildPriceReturnFields } from "../market-data/performance";
+import { pricePointsToResolvedSeries } from "../components/chart/composite/price-series";
+import { applyCompositeChartCursor, buildCompositeChartScene } from "../components/chart/composite/scene";
+import { CHART_SPEC_VERSION, type ChartSpec, type ResolvedSeries, type SeriesPeriod, type SeriesTransform } from "./types";
+
+// Actual SPY row retained from the September 10 Yahoo history cache. The open
+// exceeds the reported high; a later close does not tell us which field is wrong.
+const reported: PricePoint = {
+  date: new Date("2026-09-10T13:30:00.000Z"),
+  open: 764.0800170898438, high: 758.5549926757812, low: 757.5700073242188,
+  close: 758.1500244140625, volume: 3461376,
+};
+const history: PricePoint[] = [
+  { date: new Date("2026-09-09T13:30:00Z"), close: 757 }, reported,
+  { date: new Date("2026-09-11T13:30:00Z"), close: 760 },
+  { date: new Date("2026-09-14T13:30:00Z"), close: 761 },
+];
+const source = { kind: "security" as const, instrument: { symbol: "SPY", exchange: "ARCX" }, fieldId: "market.ohlcv" };
+function spec(transform: SeriesTransform = "raw"): ChartSpec {
+  return {
+    version: CHART_SPEC_VERSION,
+    viewport: { range: "1M", resolution: "1d", dateWindow: { start: "2026-09-08", end: "2026-09-15" } },
+    panels: [{ id: "main" }], studies: [],
+    series: [{ id: "price", source, style: "candles", transform, axis: "left", panelId: "main", interpolation: "none" }],
+  };
+}
+function resolved(points: PricePoint[] = history): ResolvedSeries {
+  return {
+    ...spec().series[0]!, id: "price", label: "SPY", color: "#ffffff", unit: "USD/share", unitGroup: "price:USD",
+    nativeFrequency: "daily", dataShape: "ohlcv", axis: "left", timeBasis: { kind: "market", timeZone: "America/New_York" }, points: extractPriceSeries(points, source),
+  };
+}
+
+test("the invariant detects contradictions without inventing missing OHLC or losing tiny and negative valid prices", () => {
+  for (const point of [reported, { ...reported, open: undefined, high: 1, low: 2 }, { ...reported, open: undefined, high: 800, low: 759 }]) {
+    const checked = pricePointValues(point);
+    expect(checked).toMatchObject({ open: null, high: null, low: null, close: null, volume: null });
+    expect(checked.integrity?.reason).toBe("inconsistent-ohlc");
+    expect(checked.integrity?.sourcePoints[0]).toEqual({ ...point, date: point.date.toISOString() });
+    expect(Object.isFrozen(checked.integrity?.sourcePoints[0])).toBe(true);
+  }
+  for (const point of [
+    { date: reported.date, close: 758 },
+    { date: reported.date, open: -2, high: 0, low: -3, close: -1 },
+    { date: reported.date, open: 0.00000002, high: 0.00000003, low: 0.00000001, close: 0.000000025 },
+    { date: reported.date, high: 0.3, close: 0.1 + 0.2 },
+  ]) expect(pricePointIntegrity(point)).toBeUndefined();
+  expect(pricePointIntegrity({ date: reported.date, high: 0.00000001, close: 0.00000002 })).toBeDefined();
+  const copy = { ...reported };
+  const diagnostic = pricePointIntegrity(copy)!;
+  copy.open = 1;
+  expect(diagnostic.sourcePoints[0]!.open).toBe(reported.open);
+  const withSource: PricePoint = { ...reported, historySource: { provider: "yahoo", symbol: "SHEL", exchange: "LSE", currency: "GBP" } };
+  const sourceDiagnostic = pricePointIntegrity(withSource)!;
+  withSource.historySource!.provider = "twelvedata";
+  expect(sourceDiagnostic.sourcePoints[0]!.historySource?.provider).toBe("yahoo");
+  expect(Object.isFrozen(sourceDiagnostic.sourcePoints[0]!.historySource)).toBe(true);
+});
+
+test("every price field and aggregated window retain an explicit gap and original source diagnostics", () => {
+  for (const period of ["auto", "daily", "weekly", "monthly", "quarterly", "annual"] as SeriesPeriod[]) {
+    for (const field of ["ohlcv", "open", "high", "low", "close", "volume"]) {
+      const points = extractPriceSeries(history, { ...source, fieldId: `market.${field}`, period });
+      const gap = points.find((point) => point.provenance?.priceHistoryIntegrity)!;
+      expect(gap).toMatchObject({ value: null, open: null, high: null, low: null, close: null, volume: null });
+      expect(gap.provenance!.priceHistoryIntegrity!.sourcePoints).toEqual([{ ...reported, date: reported.date.toISOString() }]);
+      expect(points.every((point) => point.value !== reported.close)).toBe(true);
+    }
+  }
+  const nonFiniteClose = extractPriceSeries([{ ...reported, close: NaN }], source);
+  expect(nonFiniteClose).toHaveLength(1);
+  expect(nonFiniteClose[0]!.value).toBeNull();
+  const merged = extractPriceSeries([reported, { ...reported, date: new Date("2026-09-11") }], { ...source, period: "weekly" })[0]!.provenance!.priceHistoryIntegrity!;
+  expect(merged.sourcePoints).toHaveLength(2);
+  expect(Object.isFrozen(merged)).toBe(true);
+  expect(Object.isFrozen(merged.sourcePoints)).toBe(true);
+});
+
+test("seed, resolved chart transforms and HP exports agree on quarantined values and visible notices", async () => {
+  const context = {
+    marketData: createTestDataProvider({ getPriceHistory: async () => history, getPriceHistoryForResolution: async () => history }),
+  } as HeadlessPaneContext;
+  const hp = await historicalPricesHeadless.load({ symbols: ["SPY:ARCX"], options: { range: "ALL" }, argument: ["SPY:ARCX"], rawArgument: "SPY:ARCX" }, context);
+  expect(hp.rows[1]).toMatchObject({ date: reported.date.toISOString(), close: null, open: null, integrity: pricePointIntegrity(reported) });
+  expect(hp.metadata!.notices).toHaveLength(1);
+  expect(hp.complete).toBe(false);
+  const seeded = seedChartResolutionResult(spec(), new Map([[chartQuoteOverrideKeyForSource(source), history]]))!;
+  expect(seeded.warnings.join(" ")).toContain("inconsistent OHLC");
+  for (const transform of ["raw", "percent", "index100", "log", "yoy", "qoq"] as SeriesTransform[]) {
+    const model = await loadChartPaneModel(spec(transform), context);
+    expect(model.chart.errors).toEqual([]);
+    expect(model.complete).toBe(false);
+    const json = JSON.parse(JSON.stringify(model));
+    const gap = json.series[0].points.find((point: { provenance?: { priceHistoryIntegrity?: unknown } }) => point.provenance?.priceHistoryIntegrity);
+    expect(gap).toMatchObject({ value: null, open: null, high: null, low: null, close: null });
+    expect(gap.provenance.priceHistoryIntegrity.sourcePoints[0].open).toBe(reported.open);
+    expect(json.metadata.notices.join(" ")).toContain("inconsistent OHLC");
+    expect(json.metadata.summaries[0]).toMatchObject({ return: null, startValue: null, endValue: null });
+  }
+});
+
+test("a fresh quote cannot silently repair an inconsistent reported bar", () => {
+  const now = Date.parse("2026-09-10T15:00:00Z");
+  const result = appendLiveQuotePoint([reported], {
+    symbol: "SPY", currency: "USD", price: 766, change: 8, changePercent: 1, lastUpdated: now, marketState: "REGULAR",
+  }, { now, mode: "ohlc", resolution: "1d", exchange: "ARCX" });
+  expect(result[0]).toEqual(reported);
+  expect(extractPriceSeries(result, source)[0]!.value).toBeNull();
+});
+
+test("overview chart and return windows preserve the integrity boundary without suppressing unaffected horizons", () => {
+  const chart = pricePointsToResolvedSeries(history, { id: "overview", label: "SPY", color: "#fff", unit: "USD" });
+  expect(chart.points[1]).toMatchObject({ value: null, open: null, close: null });
+  expect(chart.warning).toContain("inconsistent OHLC");
+  const fields = buildPriceReturnFields([
+    { date: new Date("2025-10-09"), close: 700 }, reported,
+    { date: new Date("2026-09-11"), close: 760 }, { date: new Date("2026-10-11"), close: 770 },
+  ]);
+  expect(fields.find((field) => field.id === "1M")!.value).toBeCloseTo(10 / 760);
+  expect(fields.find((field) => field.id === "1Y")).toMatchObject({ value: null, unavailableReason: "inconsistent-ohlc" });
+  expect(buildPriceReturnFields([reported]).every((field) => field.unavailableReason === "inconsistent-ohlc")).toBe(true);
+});
+
+test("chart cursor and latest-price marker cannot carry a prior close across a rejected bar", () => {
+  const latestBad = resolved(history.slice(0, 2));
+  const options = { width: 100, height: 20 };
+  const scene = buildCompositeChartScene([latestBad], [{ id: "main" }], options)!;
+  expect(scene.endTime).toBe(reported.date.getTime());
+  expect(scene.panels[0]!.lastPrice).toBeUndefined();
+  expect(scene.cursorValues[0]!.value).toBeNull();
+  const hovered = applyCompositeChartCursor(scene, reported.date);
+  expect(hovered.cursorValues[0]!.point?.provenance?.priceHistoryIntegrity).toBeDefined();
+  expect(hovered.cursorValues[0]!.value).toBeNull();
+  expect(applyCompositeChartCursor(scene, history[0]!.date).cursorValues[0]!.value).toBe(757);
+  const recovered = buildCompositeChartScene([resolved()], [{ id: "main" }], options)!;
+  expect(recovered.cursorValues[0]!.value).toBe(761);
+  expect(recovered.panels[0]!.lastPrice?.value).toBe(761);
+  expect(applyCompositeChartCursor(recovered, reported.date).cursorValues[0]!.value).toBeNull();
+});
+
+test("rolling and recursive studies restart after a corrupt row instead of calculating around it", () => {
+  const input = resolved();
+  for (const kind of ["sma", "ema", "bollinger", "rsi", "macd"] as const) {
+    const result = resolveStudies([input], [{ id: kind, kind, inputSeriesIds: [input.id], parameters: { period: 2, fast: 1, slow: 2, signal: 1 }, panelId: "main", axis: "left" }]);
+    for (const output of result.series) {
+      expect(output.points.find((point) => point.date.getTime() === reported.date.getTime())?.value).toBeNull();
+      expect(output.points.some((point) => point.date.getTime() === history[2]!.date.getTime() && point.value !== null)).toBe(false);
+      const warmup = output.points.find((point) => point.date.getTime() === history[2]!.date.getTime());
+      expect(warmup?.provenance?.priceHistoryIntegrity?.sourcePoints[0]?.date).toBe(reported.date.toISOString());
+    }
+    if (kind === "sma" || kind === "ema") expect(result.series[0]!.points.at(-1)?.value).toBe(760.5);
+  }
+});
+
+test("a study retains integrity attribution while warming up after a gap outside the visible window", async () => {
+  const chart = spec();
+  chart.viewport.dateWindow = { start: "2026-09-11", end: "2026-09-15" };
+  chart.studies = [{ id: "sma", kind: "sma", inputSeriesIds: ["price"], parameters: { period: 2 }, panelId: "main", axis: "left" }];
+  const model = await loadChartPaneModel(chart, {
+    marketData: createTestDataProvider({ getPriceHistory: async () => history, getPriceHistoryForResolution: async () => history }),
+  } as HeadlessPaneContext);
+  const study = model.series.find((entry) => entry.id === "sma")!;
+  expect(study.points[0]).toMatchObject({ date: history[2]!.date, value: null });
+  expect(study.points[0]!.provenance?.priceHistoryIntegrity?.sourcePoints[0]?.date).toBe(reported.date.toISOString());
+  expect(study.points[1]).toMatchObject({ value: 760.5 });
+  expect(study.points[1]!.provenance?.priceHistoryIntegrity).toBeUndefined();
+  expect(model.complete).toBe(false);
+  expect(model.chart.warnings.some((warning) => warning.startsWith("SMA") && warning.includes("inconsistent OHLC"))).toBe(true);
+  expect(model.chart.priceHistoryIntegrity?.map((entry) => [entry.seriesId, entry.scope])).toEqual([["sma", "visible-calculation"]]);
+});
+
+test("pair studies keep the corrupt observation as a gap and retain valid peer levels on recovery", () => {
+  const input = resolved();
+  const peer = { ...resolved([{ date: history[0]!.date, close: 10 }]), id: "peer", label: "Peer" };
+  for (const kind of ["ratio", "spread"] as const) {
+    const output = resolveStudies([input, peer], [{ id: kind, kind, inputSeriesIds: [input.id, peer.id], parameters: {}, panelId: "main", axis: "left" }]).series[0]!;
+    expect(output.points.map((point) => point.value)).toEqual(kind === "ratio" ? [75.7, null, 76, 76.1] : [747, null, 750, 751]);
+  }
+  const constantPeer = { ...peer, points: resolved(history.map((point) => ({ date: point.date, close: 10 }))).points };
+  const correlation = resolveStudies([input, constantPeer], [{ id: "corr", kind: "correlation", inputSeriesIds: [input.id, peer.id], parameters: { period: 2, returns: 0 }, panelId: "main", axis: "left" }]).series[0]!;
+  expect(correlation.points.at(-1)?.value).toBeNull(); // Zero variance after enough valid observations.
+  expect(correlation.points.at(-1)?.provenance?.priceHistoryIntegrity).toBeUndefined();
+});

package/src/time-series/q4-common-income.test.ts

@@ -0,0 +1,63 @@
+import { expect, test } from "bun:test";
+import type { FinancialStatement, TickerFinancials } from "../types/financials";
+import { parseCompanyFactsFinancialStatements } from "../sources/sec-edgar";
+import { computeTTM } from "../plugins/builtin/ticker-detail/financials/aggregation";
+import { deriveQuarterlyStatements, extractFundamentalSeries } from "./fundamentals";
+import type { SecuritySeriesSource } from "./types";
+import fixture from "./fixtures/q4-reported-common-income.json";
+
+const q4 = (rows: FinancialStatement[]) => rows.find(row => row.date === "2025-12-31")!;
+const source = (period: SecuritySeriesSource["period"]): SecuritySeriesSource => ({ kind: "security",
+  instrument: { symbol: "JPM", exchange: "NYSE" }, fieldId: "valuation.trailingPE", period, timestampMode: "period-end" });
+function snapshot(quarterlyStatements: FinancialStatement[]): TickerFinancials {
+  return { quarterlyStatements, annualStatements: [fixture.annual], financialCurrency: "USD",
+    priceHistory: [{ date: new Date("2025-12-31"), close: 100 }],
+    quote: { symbol: "JPM", currency: "USD", price: 100, change: 0, changePercent: 0, lastUpdated: Date.parse("2026-03-10T12:00:00Z") },
+  };
+}
+
+test("captured JPM SEC history cannot infer a Q4 common allocation from independent annual and quarterly amounts", () => {
+  // Same issuer supplement: FY common 55,681m minus Q1–Q3 gives 12,691m,
+  // but reported Q4 is 12,689m. The SEC Q4 balance-only row has no explicit
+  // common-income coverage gap, so an unavailableFields guard is insufficient.
+  const parsed = parseCompanyFactsFinancialStatements(fixture.companyfacts);
+  expect(q4(parsed.quarterlyStatements).unavailableFields).toBeUndefined();
+  const original = structuredClone(parsed);
+  const derived = q4(deriveQuarterlyStatements(parsed.quarterlyStatements, parsed.annualStatements));
+  expect(derived.netIncomeCommonStockholders).toBeUndefined();
+  expect(derived.fieldAvailability?.netIncomeCommonStockholders).toBeUndefined();
+  expect(derived.fieldSources?.netIncomeCommonStockholders).toBeUndefined();
+  expect(derived.netIncome).toBe(fixture.quarterly[3]!.netIncome);
+  expect(parsed).toEqual(original);
+});
+
+test("missing common allocations do not suppress additive parent income or revenue completion", () => {
+  const derived = q4(deriveQuarterlyStatements(fixture.quarterly.slice(0, 3), [fixture.annual]));
+  expect(derived.netIncomeCommonStockholders).toBeUndefined();
+  expect(derived.netIncome).toBe(13_025_000_000);
+  expect(derived.totalRevenue).toBe(45_798_000_000);
+});
+
+test("direct common allocations retain their reported TTM sum and income-per-share denominator", () => {
+  const quarters = fixture.quarterly.map(({ eps: _eps, ...row }) => row);
+  const derived = deriveQuarterlyStatements(quarters, [fixture.annual]);
+  expect(q4(derived).netIncomeCommonStockholders).toBe(12_689_000_000);
+  expect(computeTTM(derived)?.netIncomeCommonStockholders).toBe(55_679_000_000);
+  const shares = quarters.reduce((sum, row) => sum + row.dilutedShares, 0) / 4;
+  expect(extractFundamentalSeries(snapshot(quarters), source("ttm")).at(-1)?.value).toBeCloseTo(100 * shares / 55_679_000_000, 10);
+  for (const common of [0, -1_000_000]) {
+    const direct = quarters.map(row => row.date === fixture.annual.date ? { ...row, netIncomeCommonStockholders: common } : row);
+    expect(q4(deriveQuarterlyStatements(direct, [fixture.annual])).netIncomeCommonStockholders).toBe(common);
+  }
+});
+
+test("missing Q4 common income leaves the TTM earnings fallback unavailable until reported data arrives", () => {
+  const quarters = fixture.quarterly.map(({ eps: _eps, ...row }, index) => ({ ...row,
+    ...(index === 3 ? { netIncomeCommonStockholders: undefined } : {}),
+  }));
+  const data = snapshot(quarters);
+  for (const period of ["ttm", "auto"] as const) expect(extractFundamentalSeries(data, source(period))).toEqual([]);
+  // Complete reported EPS retains precedence despite an incomplete allocation.
+  data.quarterlyStatements = quarters.map((row, index) => ({ ...row, eps: fixture.quarterly[index]!.eps }));
+  expect(extractFundamentalSeries(data, source("ttm")).at(-1)?.value).toBeCloseTo(100 / 20.01, 10);
+});