gloomberb 0.9.9 → 0.10.0

package/src/time-series/hooks.ts

@@ -0,0 +1,45 @@
+import { useMemo } from "react";
+import { apiClient } from "../api-client";
+import { loadCachedFredSeries } from "../data/fred-series";
+import { instrumentFromTicker } from "../market-data/request-types";
+import { useAssetData } from "../plugins/runtime";
+import { useAppSelector } from "../state/app/context";
+import type { FredSeriesRequest } from "../data/fred-series";
+import type { ChartSpec } from "./types";
+import {
+  useChartResolution,
+  type UseChartResolutionOptions,
+  type UseChartResolutionResult,
+} from "./use-chart-resolution";
+
+async function loadFred(request: FredSeriesRequest) {
+  return loadCachedFredSeries(
+    request,
+    () => apiClient.getCloudFredSeries(request.seriesId, {
+      startDate: request.startDate,
+      sortOrder: request.sortOrder,
+    }),
+  );
+}
+
+export function useResolvedChartSpec(
+  spec: ChartSpec,
+  options: UseChartResolutionOptions = {},
+): UseChartResolutionResult {
+  const dataProvider = useAssetData();
+  const tickers = useAppSelector((state) => state.tickers);
+  const hydratedSpec = useMemo<ChartSpec>(() => ({
+    ...spec,
+    series: spec.series.map((entry) => {
+      if (entry.source.kind !== "security" || entry.source.instrument.exchange) return entry;
+      const symbol = entry.source.instrument.symbol.trim().toUpperCase();
+      const ticker = tickers.get(symbol);
+      const instrument = instrumentFromTicker(ticker, symbol);
+      return instrument
+        ? { ...entry, source: { ...entry.source, instrument: { ...instrument, ...entry.source.instrument } } }
+        : entry;
+    }),
+  }), [spec, tickers]);
+  const sources = useMemo(() => ({ dataProvider, loadFredSeries: loadFred }), [dataProvider]);
+  return useChartResolution(hydratedSpec, sources, options);
+}

package/src/time-series/index.ts

@@ -0,0 +1,14 @@
+export * from "./alignment";
+export * from "./economic";
+export * from "./field-catalog";
+export * from "./fundamentals";
+export * from "./hooks";
+export * from "./live-quotes";
+export * from "./market";
+export * from "./reporting";
+export * from "./resolve";
+export * from "./spec";
+export * from "./studies";
+export * from "./transforms";
+export * from "./types";
+export * from "./use-chart-resolution";

package/src/time-series/live-quotes.test.ts

@@ -0,0 +1,219 @@
+import { describe, expect, test } from "bun:test";
+import { createTestDataProvider } from "../test-support/data-provider";
+import type { Quote } from "../types/financials";
+import { CHART_SPEC_VERSION, type ChartSeriesSpec, type ChartSpec } from "./types";
+import {
+  chartQuoteOverrideKeyForTarget,
+  getLiveChartQuoteTargets,
+  subscribeToLiveChartQuotes,
+} from "./live-quotes";
+
+function securitySeries(
+  id: string,
+  symbol: string,
+  fieldId: string,
+  visible = true,
+): ChartSeriesSpec {
+  return {
+    id,
+    source: { kind: "security", instrument: { symbol }, fieldId },
+    style: "line",
+    transform: "raw",
+    axis: "auto",
+    panelId: "main",
+    interpolation: "none",
+    visible,
+  };
+}
+
+function specWithSeries(series: ChartSeriesSpec[]): ChartSpec {
+  return {
+    version: CHART_SPEC_VERSION,
+    viewport: { range: "1Y", resolution: "1d" },
+    panels: [{ id: "main" }],
+    series,
+    studies: [],
+  };
+}
+
+function quote(symbol: string, price: number, lastUpdated: number): Quote {
+  return {
+    symbol,
+    price,
+    currency: "USD",
+    change: 0,
+    changePercent: 0,
+    lastUpdated,
+  };
+}
+
+async function waitFor(predicate: () => boolean): Promise<void> {
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    if (predicate()) return;
+    await new Promise((resolve) => setTimeout(resolve, 2));
+  }
+  throw new Error("Timed out waiting for live quote refresh.");
+}
+
+describe("live chart quotes", () => {
+  test("subscribes only to visible quote-sensitive instruments and deduplicates them", () => {
+    const spec = specWithSeries([
+      securitySeries("aapl-close", "AAPL", "market.close"),
+      securitySeries("aapl-volume", "AAPL", "market.volume"),
+      securitySeries("hidden", "MSFT", "market.close", false),
+      securitySeries("fundamental", "GOOG", "fundamental.totalRevenue"),
+      securitySeries("valuation", "TSLA", "pe"),
+      securitySeries("price-sales", "SHOP", "valuation.priceSales"),
+      securitySeries("forward-pe", "NVDA", "valuation.forwardPE"),
+      securitySeries("peg", "META", "valuation.pegRatio"),
+      {
+        id: "fred",
+        source: { kind: "economic", provider: "fred", seriesId: "CPIAUCSL" },
+        style: "line",
+        transform: "raw",
+        axis: "auto",
+        panelId: "main",
+        interpolation: "none",
+      },
+    ]);
+
+    expect(getLiveChartQuoteTargets(spec).map((target) => target.symbol)).toEqual(["AAPL", "TSLA", "SHOP"]);
+  });
+
+  test("subscribes to a hidden quote series when a visible study depends on it", () => {
+    const spec = specWithSeries([
+      securitySeries("hidden-price", "MSFT", "market.close", false),
+    ]);
+    spec.studies = [{
+      id: "sma",
+      kind: "sma",
+      inputSeriesIds: ["hidden-price"],
+      parameters: { period: 20 },
+      panelId: "main",
+      axis: "auto",
+    }];
+
+    expect(getLiveChartQuoteTargets(spec).map((target) => target.symbol)).toEqual(["MSFT"]);
+  });
+
+  test("coalesces bursts, serializes refreshes, and stops cleanly", async () => {
+    const spec = specWithSeries([securitySeries("price", "AAPL", "market.close")]);
+    let handler: Parameters<NonNullable<ReturnType<typeof createTestDataProvider>["subscribeQuotes"]>>[1]
+      | undefined;
+    let subscribedTarget: Parameters<NonNullable<ReturnType<typeof createTestDataProvider>["subscribeQuotes"]>>[0][number]
+      | undefined;
+    let unsubscribeCalls = 0;
+    const provider = createTestDataProvider({
+      subscribeQuotes: (targets, onQuote) => {
+        subscribedTarget = targets[0];
+        handler = onQuote;
+        return () => {
+          unsubscribeCalls += 1;
+        };
+      },
+    });
+    let releaseFirst!: () => void;
+    const firstRefresh = new Promise<void>((resolve) => {
+      releaseFirst = resolve;
+    });
+    const snapshots: Array<ReadonlyMap<string, Quote>> = [];
+    const dispose = subscribeToLiveChartQuotes({
+      spec,
+      dataProvider: provider,
+      refreshIntervalMs: 0,
+      onRefresh: async (overrides) => {
+        snapshots.push(overrides);
+        if (snapshots.length === 1) await firstRefresh;
+      },
+    });
+    const key = chartQuoteOverrideKeyForTarget(subscribedTarget!);
+
+    handler!(subscribedTarget!, quote("AAPL", 100, 100));
+    handler!(subscribedTarget!, quote("AAPL", 101, 101));
+    await waitFor(() => snapshots.length === 1);
+    expect(snapshots[0]?.get(key)?.price).toBe(101);
+
+    handler!(subscribedTarget!, quote("AAPL", 102, 102));
+    handler!(subscribedTarget!, quote("AAPL", 99, 99));
+    handler!(subscribedTarget!, quote("AAPL", 103, 103));
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    expect(snapshots).toHaveLength(1);
+
+    releaseFirst();
+    await waitFor(() => snapshots.length === 2);
+    expect(snapshots[1]?.get(key)?.price).toBe(103);
+
+    dispose();
+    dispose();
+    expect(unsubscribeCalls).toBe(1);
+    handler!(subscribedTarget!, quote("AAPL", 104, 104));
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    expect(snapshots).toHaveLength(2);
+  });
+
+  test("does not refresh resolved charts for receivedAt-only quote updates", async () => {
+    const spec = specWithSeries([securitySeries("price", "AAPL", "market.close")]);
+    let handler: Parameters<NonNullable<ReturnType<typeof createTestDataProvider>["subscribeQuotes"]>>[1]
+      | undefined;
+    let target: Parameters<NonNullable<ReturnType<typeof createTestDataProvider>["subscribeQuotes"]>>[0][number]
+      | undefined;
+    const provider = createTestDataProvider({
+      subscribeQuotes: (targets, onQuote) => {
+        target = targets[0];
+        handler = onQuote;
+        return () => {};
+      },
+    });
+    let refreshCalls = 0;
+    const dispose = subscribeToLiveChartQuotes({
+      spec,
+      dataProvider: provider,
+      refreshIntervalMs: 0,
+      onRefresh: () => {
+        refreshCalls += 1;
+      },
+    });
+
+    handler!(target!, { ...quote("AAPL", 100, 100), receivedAt: 100 });
+    await waitFor(() => refreshCalls === 1);
+    handler!(target!, { ...quote("AAPL", 100, 100), receivedAt: 101 });
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    expect(refreshCalls).toBe(1);
+
+    handler!(target!, { ...quote("AAPL", 101, 100), receivedAt: 102 });
+    await waitFor(() => refreshCalls === 2);
+    dispose();
+  });
+
+  test("continues after a synchronous background refresh failure", async () => {
+    const spec = specWithSeries([securitySeries("price", "AAPL", "market.close")]);
+    let handler: Parameters<NonNullable<ReturnType<typeof createTestDataProvider>["subscribeQuotes"]>>[1]
+      | undefined;
+    let target: Parameters<NonNullable<ReturnType<typeof createTestDataProvider>["subscribeQuotes"]>>[0][number]
+      | undefined;
+    const provider = createTestDataProvider({
+      subscribeQuotes: (targets, onQuote) => {
+        target = targets[0];
+        handler = onQuote;
+        return () => {};
+      },
+    });
+    let refreshCalls = 0;
+    const dispose = subscribeToLiveChartQuotes({
+      spec,
+      dataProvider: provider,
+      refreshIntervalMs: 0,
+      onRefresh: () => {
+        refreshCalls += 1;
+        if (refreshCalls === 1) throw new Error("temporary failure");
+      },
+    });
+
+    handler!(target!, quote("AAPL", 100, 100));
+    await waitFor(() => refreshCalls === 1);
+    handler!(target!, quote("AAPL", 101, 101));
+    await waitFor(() => refreshCalls === 2);
+
+    dispose();
+  });
+});

package/src/time-series/live-quotes.ts

@@ -0,0 +1,203 @@
+import { canonicalTimeSeriesFieldId, isMarketFieldId } from "./field-catalog";
+import type { DataProvider, QuoteSubscriptionTarget } from "../types/data-provider";
+import type { Quote } from "../types/financials";
+import type { BrokerContractRef } from "../types/instrument";
+import type { ChartSeriesSpec, ChartSpec, SecuritySeriesSource } from "./types";
+import { activeStudyInputSeriesIds } from "./studies";
+import { valuationSeriesUsesLiveQuote } from "./fundamentals";
+
+export const LIVE_CHART_REFRESH_INTERVAL_MS = 1_000;
+
+function normalized(value: string | undefined): string {
+  return value?.trim().toUpperCase() ?? "";
+}
+
+function quoteIdentityKey(identity: {
+  symbol: string;
+  exchange?: string;
+  brokerId?: string;
+  brokerInstanceId?: string;
+  instrument?: BrokerContractRef | null;
+}): string {
+  const contractKey = identity.instrument?.conId
+    ?? identity.instrument?.localSymbol
+    ?? identity.instrument?.symbol
+    ?? "";
+  return [
+    normalized(identity.symbol),
+    normalized(identity.exchange),
+    identity.brokerId ?? "",
+    identity.brokerInstanceId ?? "",
+    contractKey,
+  ].join("|");
+}
+
+export function chartQuoteOverrideKeyForSource(source: SecuritySeriesSource): string {
+  return quoteIdentityKey({
+    symbol: source.instrument.symbol,
+    exchange: source.instrument.exchange,
+    brokerId: source.instrument.brokerId,
+    brokerInstanceId: source.instrument.brokerInstanceId,
+    instrument: source.instrument.instrument,
+  });
+}
+
+export function chartQuoteOverrideKeyForTarget(target: QuoteSubscriptionTarget): string {
+  return quoteIdentityKey({
+    symbol: target.symbol,
+    exchange: target.exchange,
+    brokerId: target.context?.brokerId,
+    brokerInstanceId: target.context?.brokerInstanceId,
+    instrument: target.context?.instrument,
+  });
+}
+
+function supportsLiveQuote(
+  series: ChartSeriesSpec,
+  activeStudyInputs: ReadonlySet<string>,
+): series is ChartSeriesSpec & {
+  source: SecuritySeriesSource;
+} {
+  if ((series.visible === false && !activeStudyInputs.has(series.id)) || series.source.kind !== "security") {
+    return false;
+  }
+  const fieldId = canonicalTimeSeriesFieldId(series.source.fieldId);
+  return isMarketFieldId(fieldId) || valuationSeriesUsesLiveQuote(fieldId);
+}
+
+/** Displayed or study-required quote-sensitive instruments, deduplicated by routing identity. */
+export function getLiveChartQuoteTargets(spec: ChartSpec): QuoteSubscriptionTarget[] {
+  const targets = new Map<string, QuoteSubscriptionTarget>();
+  const activeStudyInputs = activeStudyInputSeriesIds(spec.studies);
+  for (const series of spec.series) {
+    if (!supportsLiveQuote(series, activeStudyInputs)) continue;
+    const target: QuoteSubscriptionTarget = {
+      symbol: series.source.instrument.symbol,
+      exchange: series.source.instrument.exchange,
+      context: {
+        brokerId: series.source.instrument.brokerId,
+        brokerInstanceId: series.source.instrument.brokerInstanceId,
+        instrument: series.source.instrument.instrument ?? null,
+      },
+      surface: "detail",
+      visible: true,
+      weight: 1,
+    };
+    targets.set(chartQuoteOverrideKeyForTarget(target), target);
+  }
+  return [...targets.values()];
+}
+
+export function liveChartQuoteTargetSignature(spec: ChartSpec): string {
+  return getLiveChartQuoteTargets(spec)
+    .map(chartQuoteOverrideKeyForTarget)
+    .sort()
+    .join("\n");
+}
+
+function isNewerQuote(next: Quote, current: Quote | undefined): boolean {
+  if (!current) return true;
+  if (next.lastUpdated !== current.lastUpdated) return next.lastUpdated > current.lastUpdated;
+  return (next.receivedAt ?? 0) > (current.receivedAt ?? 0);
+}
+
+function hasResolutionRelevantChange(next: Quote, current: Quote | undefined): boolean {
+  if (!current) return true;
+  return next.lastUpdated !== current.lastUpdated
+    || next.price !== current.price
+    || next.currency !== current.currency
+    || next.providerId !== current.providerId
+    || next.marketState !== current.marketState
+    || next.preMarketPrice !== current.preMarketPrice
+    || next.postMarketPrice !== current.postMarketPrice
+    || next.exchangeName !== current.exchangeName
+    || next.listingExchangeName !== current.listingExchangeName;
+}
+
+export interface LiveChartQuoteSubscriptionOptions {
+  spec: ChartSpec;
+  dataProvider: DataProvider | null;
+  onRefresh: (quoteOverrides: ReadonlyMap<string, Quote>) => Promise<void> | void;
+  refreshIntervalMs?: number;
+}
+
+/**
+ * Coalesces streaming quote bursts and serializes engine refreshes. A slow
+ * refresh can have at most one follow-up queued, using the latest quote per
+ * instrument, so streaming never fans out into overlapping history requests.
+ */
+export function subscribeToLiveChartQuotes({
+  spec,
+  dataProvider,
+  onRefresh,
+  refreshIntervalMs = LIVE_CHART_REFRESH_INTERVAL_MS,
+}: LiveChartQuoteSubscriptionOptions): () => void {
+  const targets = getLiveChartQuoteTargets(spec);
+  if (!dataProvider?.subscribeQuotes || targets.length === 0) return () => {};
+
+  const subscribedKeys = new Set(targets.map(chartQuoteOverrideKeyForTarget));
+  const quoteOverrides = new Map<string, Quote>();
+  const interval = Math.max(0, refreshIntervalMs);
+  let disposed = false;
+  let pending = false;
+  let inFlight = false;
+  let lastStartedAt = Number.NEGATIVE_INFINITY;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+
+  const schedule = () => {
+    if (disposed || inFlight || timer !== null || !pending) return;
+    const delay = Math.max(0, interval - (Date.now() - lastStartedAt));
+    timer = setTimeout(() => {
+      timer = null;
+      if (disposed || inFlight || !pending) return;
+      pending = false;
+      inFlight = true;
+      lastStartedAt = Date.now();
+      const snapshot = new Map(quoteOverrides);
+      Promise.resolve()
+        .then(() => onRefresh(snapshot))
+        .catch(() => {
+          // A background refresh failure must not stop the live subscription.
+        })
+        .finally(() => {
+          inFlight = false;
+          if (pending) schedule();
+        });
+    }, delay);
+  };
+
+  let unsubscribe: () => void;
+  try {
+    unsubscribe = dataProvider.subscribeQuotes(targets, (target, quote) => {
+      if (disposed) return;
+      const key = chartQuoteOverrideKeyForTarget(target);
+      const previous = quoteOverrides.get(key);
+      if (!subscribedKeys.has(key) || !isNewerQuote(quote, previous)) return;
+      quoteOverrides.set(key, quote);
+      // receivedAt-only updates keep freshness metadata current without
+      // rebuilding unchanged series, studies, and chart bitmaps.
+      if (!hasResolutionRelevantChange(quote, previous)) return;
+      pending = true;
+      schedule();
+    });
+  } catch {
+    disposed = true;
+    pending = false;
+    if (timer !== null) clearTimeout(timer);
+    timer = null;
+    return () => {};
+  }
+
+  return () => {
+    if (disposed) return;
+    disposed = true;
+    pending = false;
+    if (timer !== null) clearTimeout(timer);
+    timer = null;
+    try {
+      unsubscribe();
+    } catch {
+      // Cleanup remains idempotent even if a provider has already torn down.
+    }
+  };
+}

package/src/time-series/market-resolution.ts

@@ -0,0 +1,53 @@
+import {
+  CHART_RESOLUTION_STEP_MS,
+  type ManualChartResolution,
+} from "../components/chart/core/resolution";
+import { isMarketFieldId } from "./field-catalog";
+import type { ChartSeriesSpec, SeriesPeriod } from "./types";
+
+const MARKET_PERIOD_MAX_RESOLUTION: Partial<Record<SeriesPeriod, ManualChartResolution>> = {
+  daily: "1d",
+  weekly: "1wk",
+  monthly: "1mo",
+};
+
+export function maximumResolutionForMarketPeriod(
+  period: SeriesPeriod | undefined,
+): ManualChartResolution | null {
+  return period ? MARKET_PERIOD_MAX_RESOLUTION[period] ?? null : null;
+}
+
+export function isResolutionFineEnoughForMarketPeriod(
+  resolution: ManualChartResolution,
+  period: SeriesPeriod | undefined,
+): boolean {
+  const maximum = maximumResolutionForMarketPeriod(period);
+  return maximum === null
+    || CHART_RESOLUTION_STEP_MS[resolution] <= CHART_RESOLUTION_STEP_MS[maximum];
+}
+
+/** Returns the finest fetch cadence required by explicit market periods. */
+export function finestExplicitMarketPeriodResolution(
+  series: readonly ChartSeriesSpec[],
+): ManualChartResolution | null {
+  let finest: ManualChartResolution | null = null;
+  for (const entry of series) {
+    if (entry.source.kind !== "security" || !isMarketFieldId(entry.source.fieldId)) continue;
+    const required = maximumResolutionForMarketPeriod(entry.source.period);
+    if (!required) continue;
+    if (!finest || CHART_RESOLUTION_STEP_MS[required] < CHART_RESOLUTION_STEP_MS[finest]) {
+      finest = required;
+    }
+  }
+  return finest;
+}
+
+export function resolutionForExplicitMarketPeriods(
+  preferred: ManualChartResolution,
+  series: readonly ChartSeriesSpec[],
+): ManualChartResolution {
+  const required = finestExplicitMarketPeriodResolution(series);
+  return required && CHART_RESOLUTION_STEP_MS[preferred] > CHART_RESOLUTION_STEP_MS[required]
+    ? required
+    : preferred;
+}

package/src/time-series/market.ts

@@ -0,0 +1,125 @@
+import type { PricePoint, TickerFinancials } from "../types/financials";
+import { canonicalTimeSeriesFieldId, isFundamentalFieldId, isMarketFieldId } from "./field-catalog";
+import { extractFundamentalSeries } from "./fundamentals";
+import type { SecuritySeriesSource, SeriesPeriod, TimeSeriesPoint } from "./types";
+
+function finiteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+function pricePointDate(value: unknown): Date | null {
+  const date = value instanceof Date ? new Date(value) : new Date(value as string | number);
+  return Number.isFinite(date.getTime()) ? date : null;
+}
+
+function utcDay(date: Date): string {
+  return date.toISOString().slice(0, 10);
+}
+
+function periodKey(date: Date, period: SeriesPeriod): string {
+  const year = date.getUTCFullYear();
+  const month = date.getUTCMonth();
+  if (period === "annual") return String(year);
+  if (period === "quarterly") return `${year}-Q${Math.floor(month / 3) + 1}`;
+  if (period === "monthly") return `${year}-${String(month + 1).padStart(2, "0")}`;
+  if (period === "weekly") {
+    const monday = new Date(Date.UTC(year, month, date.getUTCDate()));
+    const weekday = monday.getUTCDay();
+    monday.setUTCDate(monday.getUTCDate() - (weekday === 0 ? 6 : weekday - 1));
+    return utcDay(monday);
+  }
+  return utcDay(date);
+}
+
+interface AggregatedPricePoint {
+  date: Date;
+  open: number;
+  high: number;
+  low: number;
+  close: number;
+  volume?: number;
+}
+
+/** Aggregates OHLCV correctly: first open, max high, min low, last close, summed volume. */
+export function aggregatePriceHistory(
+  points: readonly PricePoint[],
+  period: SeriesPeriod,
+): PricePoint[] {
+  const sorted = points
+    .flatMap((point) => {
+      const date = pricePointDate(point.date);
+      return date && finiteNumber(point.close) ? [{ ...point, date }] : [];
+    })
+    .sort((left, right) => left.date.getTime() - right.date.getTime());
+  if (period === "auto") return sorted.map((point) => ({ ...point, date: new Date(point.date) }));
+  if (period === "ttm") return [];
+
+  const buckets = new Map<string, AggregatedPricePoint>();
+  for (const point of sorted) {
+    const key = periodKey(point.date, period);
+    const open = finiteNumber(point.open) ? point.open : point.close;
+    const high = finiteNumber(point.high) ? point.high : point.close;
+    const low = finiteNumber(point.low) ? point.low : point.close;
+    const current = buckets.get(key);
+    if (!current) {
+      buckets.set(key, {
+        date: new Date(point.date),
+        open,
+        high,
+        low,
+        close: point.close,
+        volume: finiteNumber(point.volume) ? point.volume : undefined,
+      });
+      continue;
+    }
+    current.date = new Date(point.date);
+    current.high = Math.max(current.high, high);
+    current.low = Math.min(current.low, low);
+    current.close = point.close;
+    if (finiteNumber(point.volume)) current.volume = (current.volume ?? 0) + point.volume;
+  }
+  return [...buckets.values()];
+}
+
+export function extractPriceSeries(
+  priceHistory: readonly PricePoint[],
+  source: SecuritySeriesSource,
+): TimeSeriesPoint[] {
+  const fieldId = canonicalTimeSeriesFieldId(source.fieldId);
+  if (!isMarketFieldId(fieldId)) return [];
+  const aggregated = aggregatePriceHistory(priceHistory, source.period ?? "auto");
+  return aggregated.map((point) => {
+    const value = fieldId === "market.open"
+      ? point.open
+      : fieldId === "market.high"
+        ? point.high
+        : fieldId === "market.low"
+          ? point.low
+          : fieldId === "market.volume"
+            ? point.volume
+            : point.close;
+    return {
+      date: new Date(point.date),
+      observedAt: new Date(point.date),
+      availableAt: new Date(point.date),
+      value: finiteNumber(value) ? value : null,
+      open: finiteNumber(point.open) ? point.open : null,
+      high: finiteNumber(point.high) ? point.high : null,
+      low: finiteNumber(point.low) ? point.low : null,
+      close: finiteNumber(point.close) ? point.close : null,
+      volume: finiteNumber(point.volume) ? point.volume : null,
+      provenance: { quality: "reported" as const },
+    };
+  });
+}
+
+/** Pure security-source coordinator used by runtime hooks after data loading. */
+export function extractSecuritySeries(
+  financials: TickerFinancials | null,
+  source: SecuritySeriesSource,
+): TimeSeriesPoint[] {
+  if (!financials) return [];
+  if (isMarketFieldId(source.fieldId)) return extractPriceSeries(financials.priceHistory, source);
+  if (isFundamentalFieldId(source.fieldId)) return extractFundamentalSeries(financials, source);
+  return [];
+}