gloomberb 0.18.2 → 0.18.4

package/src/time-series/bar-aggregation.ts

@@ -0,0 +1,243 @@
+import type { PricePoint } from "../types/financials";
+import { isAlwaysOpenExchange, isVenueTradingDay } from "../market-data/market/freshness";
+import { futuresSessionOpenMinute, latestSessionStart, listingTimeZone } from "../market-data/market/trading-sessions";
+import { isRoundTheClockCoin } from "../utils/crypto-pair";
+import { canonicalExchange } from "../utils/exchanges";
+import { futuresListingVenue } from "../utils/futures-generic";
+import { mergePriceHistoryIntegrity, pricePointIntegrity, type PriceHistoryIntegrity } from "../utils/price-history-integrity";
+import { getPricePointTimestamp } from "../utils/price-history";
+import { zonedDateTimeParts } from "../utils/zoned-date-time";
+import { isFiniteNumber } from "../utils/guards";
+import { chartBarSizeParts, chartBarSizeStepMs, type ChartBarSize } from "./resolution";
+import type { CustomChartResolution } from "./range";
+import type { ResolvedSeries } from "./types";
+
+const DAY_MS = 86_400_000;
+/** Sessions open at least 23 hours apart, so an open stays the latest one for this long after it. */
+const SESSION_REUSE_MS = 22 * 3_600_000;
+
+/** Which listing the source bars are of, which says when its sessions open and which days it trades. */
+export interface BarAggregationListing {
+  symbol?: string;
+  exchange?: string;
+  /** The bars include pre-market and after-hours trading: US sessions then start at 04:00 New York. */
+  extendedHours?: boolean;
+}
+
+/** A built bar. It carries the integrity of a source bar whose prices contradict each other, so the bar is left blank as that one is. */
+export type AggregatedPricePoint = PricePoint & { integrity?: PriceHistoryIntegrity };
+
+interface Bucket {
+  key: string;
+  time: number;
+  bars: PricePoint[];
+  gaps: PricePoint[];
+}
+
+/** A daily or longer bar's date: a label at UTC midnight names that date, others read in the venue's zone. */
+function barDate(time: number, timeZone: string): { year: number; month: number; day: number } {
+  if (time % DAY_MS === 0) {
+    const date = new Date(time);
+    return { year: date.getUTCFullYear(), month: date.getUTCMonth() + 1, day: date.getUTCDate() };
+  }
+  const { year, month, day } = zonedDateTimeParts(time, timeZone);
+  return { year, month, day };
+}
+
+/** The venue whose calendar a listing trades on: a future's exchange, else its own. */
+function calendarVenue(listing: BarAggregationListing): string {
+  return futuresListingVenue(listing.symbol ?? "", listing.exchange)?.venue ?? canonicalExchange(listing.exchange ?? "");
+}
+
+/** Counts the trading days of each year before each of its days, from 1 January. */
+function tradingDayCounter(listing: BarAggregationListing): (year: number, month: number, day: number) => number {
+  const everyDay = isRoundTheClockCoin(listing.symbol, listing.exchange) || isAlwaysOpenExchange(listing.exchange);
+  const venue = calendarVenue(listing);
+  const years = new Map<number, Int16Array>();
+  return (year, month, day) => {
+    let before = years.get(year);
+    if (!before) {
+      const start = Date.UTC(year, 0, 1);
+      const length = Math.round((Date.UTC(year + 1, 0, 1) - start) / DAY_MS);
+      before = new Int16Array(length + 1);
+      for (let index = 0; index < length; index += 1) {
+        const date = new Date(start + index * DAY_MS).toISOString().slice(0, 10);
+        before[index + 1] = before[index]! + (everyDay || isVenueTradingDay(venue, date) ? 1 : 0);
+      }
+      years.set(year, before);
+    }
+    return before[Math.round((Date.UTC(year, month - 1, day) - Date.UTC(year, 0, 1)) / DAY_MS)] ?? 0;
+  };
+}
+
+/** The first Monday of a year: its first full week starts there. */
+function firstMonday(year: number): number {
+  const start = Date.UTC(year, 0, 1);
+  return start + ((8 - new Date(start).getUTCDay()) % 7) * DAY_MS;
+}
+
+/** The period of `count` days, weeks or months a daily or longer bar falls in, counted from the start of its year. */
+function calendarBucketKey(
+  time: number,
+  unit: "d" | "wk" | "mo",
+  count: number,
+  timeZone: string,
+  tradingDaysBefore: ((year: number, month: number, day: number) => number) | null,
+): string {
+  const { year, month, day } = barDate(time, timeZone);
+  if (unit === "mo") return `${year}:${Math.floor((month - 1) / count)}`;
+  if (unit === "d") return `${year}:${Math.floor(tradingDaysBefore!(year, month, day) / count)}`;
+  // A week is named by its Monday; the days before a year's first full week end the previous year's last bar.
+  const date = Date.UTC(year, month - 1, day);
+  const monday = date - ((new Date(date).getUTCDay() + 6) % 7) * DAY_MS;
+  let weekYear = new Date(monday).getUTCFullYear();
+  if (monday < firstMonday(weekYear)) weekYear -= 1;
+  return `${weekYear}:${Math.floor((monday - firstMonday(weekYear)) / (7 * DAY_MS) / count)}`;
+}
+
+/** The shortest step between source bars, which says how long one of them is. */
+function sourceStepMs(times: readonly number[]): number {
+  let step = Number.POSITIVE_INFINITY;
+  for (let index = 1; index < times.length; index += 1) {
+    const gap = times[index]! - times[index - 1]!;
+    if (gap > 0 && gap < step) step = gap;
+  }
+  return Number.isFinite(step) ? Math.max(step, 60_000) : 60_000;
+}
+
+/**
+ * The bars of `size` built from shorter source bars, oldest first: the first
+ * open, the highest high, the lowest low, the last close and the summed volume
+ * of the source bars in each. Minute and hour bars start at the session's
+ * open and every `size` after it, so a 4h bar on a US stock runs 09:30 to
+ * 13:30 and the session's last one is shorter; a future's sessions open at its
+ * venue's published time (17:00 Chicago on CME Globex), and a market without
+ * known hours starts its days at midnight UTC. Day bars count the venue's
+ * trading days from 1 January (every day for a coin), week bars the weeks from
+ * the year's first Monday and month bars from January, starting again each
+ * year, so a bar never moves when older history loads. A period without source
+ * bars has no bar; one whose source bars are all reported gaps stays a gap.
+ * A size the bars are already in returns them as they are.
+ */
+export function aggregatePriceBars(
+  points: readonly PricePoint[],
+  size: ChartBarSize,
+  listing: BarAggregationListing = {},
+): AggregatedPricePoint[] {
+  const parts = chartBarSizeParts(size);
+  const sorted = points
+    .map((point) => ({ point, time: getPricePointTimestamp(point) }))
+    .filter((entry) => Number.isFinite(entry.time))
+    .sort((left, right) => left.time - right.time);
+  if (!parts || sorted.length === 0) return sorted.map((entry) => entry.point);
+  const intraday = parts.unit === "m" || parts.unit === "h";
+  const sizeMs = parts.count * (parts.unit === "h" ? 3_600_000 : 60_000);
+  const times = sorted.map((entry) => entry.time);
+  const step = intraday ? sourceStepMs(times) : 0;
+  if (intraday && step >= sizeMs) return sorted.map((entry) => entry.point);
+  const timeZone = listingTimeZone(listing.symbol, listing.exchange) ?? "UTC";
+  const tradingDaysBefore = parts.unit === "d" ? tradingDayCounter(listing) : null;
+
+  // The open of the session a bar trades in, looked up once per session: the
+  // latest open by the bar's last minute, so a bar that straddles an open
+  // (clock-aligned source bars) starts that session.
+  const lookupOpen = (time: number) => latestSessionStart(listing.symbol, listing.exchange, time, { extendedHours: listing.extendedHours === true });
+  const hasHours = intraday && lookupOpen(times.at(-1)! + step - 1) !== null;
+  let cachedOpen: number | null = null;
+  const sessionOpen = (time: number): number => {
+    if (!hasHours) return Math.floor(time / DAY_MS) * DAY_MS;
+    if (cachedOpen !== null && time >= cachedOpen && time + step - 1 < cachedOpen + SESSION_REUSE_MS) return cachedOpen;
+    cachedOpen = lookupOpen(time + step - 1) ?? Math.floor(time / DAY_MS) * DAY_MS;
+    return cachedOpen;
+  };
+
+  const buckets: Bucket[] = [];
+  let current: Bucket | undefined;
+  for (const { point, time } of sorted) {
+    let key: string;
+    let start = time;
+    if (intraday) {
+      const open = sessionOpen(time);
+      start = open + Math.max(0, Math.floor((time - open) / sizeMs)) * sizeMs;
+      key = String(start);
+    } else {
+      key = calendarBucketKey(time, parts.unit as "d" | "wk" | "mo", parts.count, timeZone, tradingDaysBefore);
+    }
+    if (!current || current.key !== key) {
+      current = { key, time: start, bars: [], gaps: [] };
+      buckets.push(current);
+    }
+    (isFiniteNumber(point.close) ? current.bars : current.gaps).push(point);
+  }
+  return buckets.map((bucket) => buildBar(bucket, intraday));
+}
+
+function buildBar(bucket: Bucket, intraday: boolean): AggregatedPricePoint {
+  const first = bucket.bars[0];
+  // Day and longer bars keep the first source bar's own label: sources date a session at midnight or at its open.
+  const date = new Date(intraday || !first ? bucket.time : getPricePointTimestamp(first));
+  if (!first) return { ...bucket.gaps[0]!, date };
+  const last = bucket.bars.at(-1)!;
+  let high = Number.NEGATIVE_INFINITY;
+  let low = Number.POSITIVE_INFINITY;
+  let volume: number | undefined;
+  let venueVolume: PricePoint["venueVolume"] | null | undefined;
+  let partial = false;
+  let filled = false;
+  const integrity: PriceHistoryIntegrity[] = [];
+  for (const bar of bucket.bars) {
+    const close = bar.close;
+    high = Math.max(high, isFiniteNumber(bar.high) ? bar.high : close);
+    low = Math.min(low, isFiniteNumber(bar.low) ? bar.low : close);
+    if (isFiniteNumber(bar.volume)) volume = (volume ?? 0) + bar.volume;
+    // One venue's trades add up only while every bar counts the same venue.
+    if (bar.venueVolume && venueVolume !== null) {
+      venueVolume = venueVolume === undefined || venueVolume.venue === bar.venueVolume.venue
+        ? { venue: bar.venueVolume.venue, volume: (venueVolume?.volume ?? 0) + bar.venueVolume.volume } : null;
+    }
+    partial ||= bar.partial === true;
+    filled ||= bar.filled === true;
+    const flagged = (bar as AggregatedPricePoint).integrity ?? pricePointIntegrity(bar);
+    if (flagged) integrity.push(flagged);
+  }
+  return {
+    date,
+    open: isFiniteNumber(first.open) ? first.open : first.close,
+    high,
+    low,
+    close: last.close,
+    ...(volume !== undefined ? { volume } : {}),
+    ...(volume === undefined && venueVolume ? { venueVolume } : {}),
+    ...(partial ? { partial: true } : {}),
+    ...(filled ? { filled: true } : {}),
+    ...(last.unsettled ? { unsettled: true } : {}),
+    ...(integrity.length ? { integrity: mergePriceHistoryIntegrity(...integrity) } : {}),
+  };
+}
+
+function greatestCommonDivisor(left: number, right: number): number {
+  return right === 0 ? left : greatestCommonDivisor(right, left % right);
+}
+
+/**
+ * When the sessions of the futures among `listings` open, in minutes after
+ * local midnight, which the source bars of a built bar size must divide
+ * (`chartBarSizeSource`); null when none of them is a future.
+ */
+export function futuresOpenMinuteOf(listings: Iterable<{ symbol: string; exchange?: string }>): number | null {
+  let shared: number | null = null;
+  for (const listing of listings) {
+    const minute = futuresSessionOpenMinute(listing.symbol, listing.exchange);
+    if (minute !== null) shared = shared === null ? minute : greatestCommonDivisor(shared, minute);
+  }
+  return shared;
+}
+
+/** A market series whose points were built in `size`: it says so, and its bars are that far apart. */
+export function withBuiltBarSize(series: ResolvedSeries, size: CustomChartResolution): ResolvedSeries {
+  return {
+    ...series,
+    barSize: size,
+    ...(series.timeBasis?.kind === "market" ? { timeBasis: { ...series.timeBasis, cadenceMs: chartBarSizeStepMs(size) } } : {}),
+  };
+}

package/src/time-series/base-series.ts

@@ -0,0 +1,307 @@
+import { resolveAssetDisplayKind } from "../market-data/market/format";
+import { hasValidQuoteObservationTime } from "../market-data/quotes/freshness";
+import type { HistorySession } from "../types/price-history";
+import { appendLiveQuotePoint, hasUnknownBondHistoryBasis } from "./chart-data";
+import type { LiveBarAccumulator } from "./live-bars";
+import { CHART_RESOLUTION_STEP_MS, type ManualChartResolution } from "./resolution";
+import type { Quote, QuoteMetadata, TickerFinancials } from "../types/financials";
+import type { FredSeriesLoadResult } from "../sources/gloomberb-cloud/fred-series";
+import { extractFredSeries } from "./economic";
+import { getTimeSeriesField, isMarketFieldId } from "./field-catalog";
+import {
+  unreportedStatementPeriod,
+  valuationCurrencyWarning,
+  valuationPriceIssues,
+} from "./fundamentals";
+import { extractSecuritySeries } from "./market";
+import { activeStudyInputSeriesIds } from "./studies";
+import { reportingCurrencySeries } from "./reporting-currency";
+import { compareChartQuoteRecency } from "./live-quotes";
+import { marketSeriesFrequency } from "./market";
+import { canonicalExchange, resolveExchangeTimeZone } from "../utils/exchanges";
+import { futuresGenericCaption, futuresGenericListing, futuresListingPriceBasis } from "../utils/futures-generic";
+import { contractPriceUnit } from "./price-units";
+import { INDEX_POINTS_UNIT, isIndexLevel } from "../market-data/market/index-level";
+import { isOhlcSeriesStyle } from "./spec";
+import { SERIES_COLORS } from "../theme/series-colors";
+import type {
+  ChartSeriesSpec,
+  ChartSpec,
+  ResolvedSeries,
+} from "./types";
+import { instrumentLabel } from "./resolve-context";
+import { finiteDate } from "./chart-bounds";
+
+// A series that fails to load keeps its place with no observations. Dropping it
+// made a series the user had added disappear from the legend while it still sat
+// in the series editor, with nothing on screen to explain the difference.
+export function unloadableSeries(spec: ChartSeriesSpec, index: number, warning: string): ResolvedSeries {
+  const field = spec.source.kind === "security" ? getTimeSeriesField(spec.source.fieldId) : undefined;
+  const label = spec.source.kind === "security"
+    ? `${instrumentLabel(spec.source)} ${field?.seriesLabel ?? field?.shortLabel ?? spec.source.fieldId.split(".").at(-1) ?? "Series"}`
+    : spec.source.kind === "economic"
+      ? `FRED ${spec.source.seriesId}`
+      : spec.source.seriesId;
+  return {
+    id: spec.id,
+    label: spec.label?.trim() || label,
+    color: spec.color ?? SERIES_COLORS[index % SERIES_COLORS.length]!,
+    unit: field?.unit ?? "",
+    unitGroup: field?.unitGroup ?? "unknown",
+    nativeFrequency: field?.nativeFrequency ?? "daily",
+    dataShape: field?.dataShape ?? "scalar",
+    style: spec.style,
+    transform: spec.transform,
+    axis: spec.axis === "right" ? "right" : "left",
+    panelId: spec.panelId,
+    interpolation: spec.interpolation,
+    warning,
+    points: [],
+  };
+}
+
+export function emptyFinancials(priceHistory: TickerFinancials["priceHistory"] = []): TickerFinancials {
+  return { annualStatements: [], quarterlyStatements: [], priceHistory };
+}
+
+export function chartCalculationSeriesIds(spec: ChartSpec): Set<string> {
+  const ids = activeStudyInputSeriesIds(spec.studies);
+  spec.series.filter(entry => entry.visible !== false).forEach(entry => ids.add(entry.id));
+  // Hidden primary market data still owns the shared session anchor.
+  const primary = spec.series.find(entry => entry.source.kind === "security" && isMarketFieldId(entry.source.fieldId));
+  if (primary) ids.add(primary.id);
+  return ids;
+}
+
+export function latestQuote(snapshot: Quote | undefined, override: Quote | undefined): Quote | undefined {
+  if (!snapshot) return override;
+  if (!override) return snapshot;
+  return compareChartQuoteRecency(override, snapshot) >= 0 ? override : snapshot;
+}
+
+export function mergeHistory(
+  financials: TickerFinancials | null,
+  history: TickerFinancials["priceHistory"],
+  quoteOverride: Quote | undefined,
+  now: number,
+  liveBarResolution?: ManualChartResolution,
+  exchange?: string,
+  appendQuote = true,
+  assetCategory?: string,
+  live?: { bars: LiveBarAccumulator; since?: number; session?: HistorySession; extendedHours?: boolean },
+): TickerFinancials {
+  const base = financials ?? emptyFinancials();
+  const quote = latestQuote(base.quote, quoteOverride);
+  const unknownHistoryBasis = hasUnknownBondHistoryBasis(quote, assetCategory, base.quoteMetadata?.instrumentType);
+  if (!appendQuote || unknownHistoryBasis) return { ...base, quote, priceHistory: history };
+  // Market bars fold every observed quote into the forming bar; other series
+  // price their latest point from the current quote alone.
+  const priceHistory = live && liveBarResolution
+    ? live.bars.apply(history, quote, { now, resolution: liveBarResolution, exchange, liveSince: live.since, session: live.session,
+      extendedHours: live.extendedHours })
+    : appendLiveQuotePoint(history, quote, liveBarResolution
+      ? { now, mode: "ohlc", resolution: liveBarResolution, exchange }
+      : { now });
+  return { ...base, quote, priceHistory };
+}
+
+export function baseSecuritySeries(
+  spec: ChartSeriesSpec,
+  financials: TickerFinancials,
+  index: number,
+  marketResolution?: ManualChartResolution | null,
+  quoteMetadata: QuoteMetadata | null | undefined = financials.quoteMetadata,
+  /** What a futures contract's price counts ("USD / gallon"), from its terms. */
+  contractUnit?: string | null,
+): ResolvedSeries | null {
+  if (spec.source.kind !== "security") return null;
+  const field = getTimeSeriesField(spec.source.fieldId);
+  if (!field) return null;
+  const points = extractSecuritySeries(financials, spec.source);
+  const unreportedPeriod = points.length === 0 ? unreportedStatementPeriod(financials, spec.source) : null;
+  const symbol = instrumentLabel(spec.source);
+  const statementCurrency = field.id.startsWith("fundamental.") && field.unit.startsWith("currency")
+    ? reportingCurrencySeries(points, financials.financialCurrency) : null;
+  // A broker contract names its currency even before (or without) a quote.
+  const currency = statementCurrency ? statementCurrency.currency : financials.quote?.currency || quoteMetadata?.currency || spec.source.instrument.instrument?.currency;
+  const assetKind = resolveAssetDisplayKind({ assetCategory: financials.quote?.instrumentType || quoteMetadata?.instrumentType });
+  const unknownBondBasis = hasUnknownBondHistoryBasis(financials.quote,
+    spec.source.instrument.instrument?.secType, quoteMetadata?.instrumentType);
+  const volumeUnit = unknownBondBasis ? undefined : assetKind === "equity" ? "shares" as const : assetKind === "contract" ? "contracts" as const : undefined;
+  // A price quote establishes its currency, but only instrument metadata can
+  // establish a per-share or per-crypto-unit basis. This does not establish the
+  // provider's volume denomination or a derivative's contract multiplier.
+  const unitTemplate = field.unitGroup === "price" && isMarketFieldId(field.id)
+    ? unknownBondBasis ? "unknown" : `currency${assetKind === "equity" ? "/share" : assetKind === "crypto" ? "/unit" : ""}`
+    : field.unit;
+  const generic = field.unitGroup === "price"
+    ? futuresGenericListing(spec.source.instrument.symbol, spec.source.instrument.exchange) : null;
+  // A generic future on an index, VIX or Treasuries reads in points or 32nds, and an index
+  // future's continuous symbol or contract in points, not dollars, as its quote does.
+  const genericBasis = field.unitGroup === "price" && isMarketFieldId(field.id)
+    ? futuresListingPriceBasis(spec.source.instrument.symbol, spec.source.instrument.exchange) : null;
+  // An index's level is points too, never the currency its members trade in.
+  const indexLevel = field.unitGroup === "price" && isMarketFieldId(field.id)
+    && isIndexLevel(financials.quote?.instrumentType || quoteMetadata?.instrumentType);
+  const genericUnit = genericBasis === "points" || indexLevel ? INDEX_POINTS_UNIT : genericBasis === "thirty-seconds" ? "32nds" : null;
+  // A future's price in a currency counts what its contract terms say: heating
+  // oil is USD / gallon and crude USD / barrel, which a bare USD does not tell apart.
+  const statedUnit = !genericUnit && unitTemplate === "currency" ? contractPriceUnit(contractUnit, currency) : null;
+  const unit = field.id === "market.volume" ? volumeUnit ?? ""
+    : statedUnit ?? genericUnit ?? (unitTemplate.startsWith("currency") && currency ? unitTemplate.replace("currency", currency) : unitTemplate);
+  const currencyUnitGroup = genericUnit ? `${field.unitGroup}:${genericUnit}`
+    : unknownBondBasis && field.unitGroup === "price" ? "price:unknown"
+    : field.unit.startsWith("currency") && currency
+    ? `${field.unitGroup}:${currency}`
+    : field.unitGroup;
+  const marketExchange = spec.source.instrument.exchange
+    || financials.quote?.listingExchangeName
+    || financials.quote?.exchangeName;
+  const marketField = isMarketFieldId(spec.source.fieldId);
+  // A routing code such as a broker's SMART names no venue. The quote's
+  // listing then supplies the session clock, so closed hours stay off the axis.
+  const sessionExchange = [marketExchange, financials.quote?.listingExchangeName, quoteMetadata?.listingExchangeName, financials.quote?.exchangeName]
+    .find((value) => resolveExchangeTimeZone(value));
+  // A dollar listing saved with IBKR's SMART route and no other venue trades on
+  // the US session, and so does a dollar option, which names no venue at all.
+  const dollars = !currency || currency === "USD";
+  const usOption = dollars && (spec.source.instrument.instrument?.secType?.toUpperCase() === "OPT"
+    || /^OPTION$/i.test(financials.quote?.instrumentType ?? quoteMetadata?.instrumentType ?? ""));
+  const routedUsListing = !sessionExchange && ((canonicalExchange(marketExchange) === "SMART" && dollars) || usOption);
+  const marketTimeZone = marketField
+    && canonicalExchange(marketExchange) !== "CCC"
+    ? resolveExchangeTimeZone(sessionExchange) ?? (routedUsListing ? "America/New_York" : null)
+    : null;
+  // A route has no hours of its own: its sessions, which the day view and
+  // VWAP follow, are the venue's, and NYSE's for an unnamed dollar listing.
+  const listingExchange = canonicalExchange(marketExchange) === "SMART" || usOption
+    ? canonicalExchange(sessionExchange) || (routedUsListing ? "NYSE" : marketExchange)
+    : marketExchange;
+  const latestChangePercent = marketField && field.unit.startsWith("currency")
+    && !unknownBondBasis
+    && financials.quote && hasValidQuoteObservationTime(financials.quote)
+    ? financials.quote.changePercent
+    : undefined;
+  const priceIssues = valuationPriceIssues(financials, spec.source);
+  // A source with closes only, such as a generic future, has flat bars (open,
+  // high and low filled from the close): nothing to draw as candles.
+  const closesOnly = marketField && points.length > 1
+    && points.every((point) => [point.open, point.high, point.low].every((value) => value == null || value === point.close));
+  return {
+    id: spec.id,
+    label: spec.label?.trim() || (generic ? futuresGenericCaption(generic) : `${symbol} ${field.seriesLabel ?? field.shortLabel}`),
+    color: spec.color ?? SERIES_COLORS[index % SERIES_COLORS.length]!,
+    unit,
+    unitGroup: currencyUnitGroup,
+    ...(statedUnit ? { statedUnit } : {}),
+    priceAssetCategory: marketField && field.unitGroup === "price" && !unknownBondBasis
+      ? financials.quote?.instrumentType || quoteMetadata?.instrumentType : undefined,
+    volumeUnit,
+    ...(priceIssues.length ? { valuationPriceIssues: priceIssues } : {}),
+    warning: field.id === "market.volume" && !volumeUnit && points.length > 0
+      ? "Volume unit unknown." : statementCurrency?.warning ?? valuationCurrencyWarning(financials, spec.source),
+    nativeFrequency: marketField ? marketSeriesFrequency(spec.source, marketResolution)
+      : spec.source.period && spec.source.period !== "auto" ? spec.source.period : field.nativeFrequency,
+    ...(unreportedPeriod ? { unreportedPeriod } : {}),
+    ...(marketField ? { historyResolution: marketResolution } : {}),
+    timestampMode: spec.source.timestampMode,
+    dataShape: field.dataShape,
+    style: closesOnly && isOhlcSeriesStyle(spec.style ?? field.defaultStyle) ? "line" : spec.style,
+    transform: spec.transform,
+    axis: spec.axis === "right" ? "right" : "left",
+    panelId: spec.panelId,
+    interpolation: spec.interpolation,
+    observationKind: marketField ? "market" : undefined,
+    ...(marketField ? { listing: { symbol: spec.source.instrument.symbol, exchange: listingExchange ?? "" } } : {}),
+    timeBasis: marketTimeZone
+      ? {
+          kind: "market",
+          timeZone: marketTimeZone,
+          exchange: canonicalExchange(sessionExchange) || undefined,
+          cadenceMs: marketResolution
+            ? CHART_RESOLUTION_STEP_MS[marketResolution]
+            : undefined,
+        }
+      : undefined,
+    latestChangePercent: typeof latestChangePercent === "number" && Number.isFinite(latestChangePercent)
+      ? latestChangePercent
+      : undefined,
+    points,
+  };
+}
+
+const FRED_CATALOG_UNITS: Readonly<Record<string, string>> = {
+  "percent": "%",
+  "millions of u.s. dollars": "million USD",
+  "millions of dollars": "million USD",
+  "billions of dollars": "billion USD",
+  "billions of u.s. dollars": "billion USD",
+  "billions of us dollars": "billion USD",
+  "dollars per barrel": "USD/barrel",
+  "thousands of persons": "thousand people",
+};
+
+function fredCatalogUnit(units: string): string {
+  return FRED_CATALOG_UNITS[units.toLowerCase()] ?? units;
+}
+
+export function baseEconomicSeries(
+  spec: ChartSeriesSpec,
+  loaded: FredSeriesLoadResult,
+  index: number,
+): ResolvedSeries | null {
+  if (spec.source.kind !== "economic") return null;
+  const { data } = loaded;
+  const units = data.info?.units?.trim() || "value";
+  const catalogUnit = fredCatalogUnit(units);
+  // "Percent Change from Year Ago" and "Percent per Annum" are percent too.
+  const isPercent = units.toLowerCase().includes("percent");
+  return {
+    id: spec.id,
+    label: spec.label?.trim() || data.info?.title?.trim() || spec.source.seriesId,
+    color: spec.color ?? SERIES_COLORS[index % SERIES_COLORS.length]!,
+    unit: isPercent ? "%" : catalogUnit,
+    unitGroup: isPercent ? "percent" : `economic:${catalogUnit.toLowerCase()}`,
+    nativeFrequency: "auto",
+    timestampMode: "period-end",
+    dataShape: "scalar",
+    style: spec.style,
+    transform: spec.transform,
+    axis: spec.axis === "right" ? "right" : "left",
+    panelId: spec.panelId,
+    interpolation: spec.interpolation,
+    points: extractFredSeries(data.observations, { providerId: "fred", timestampMode: "period-end" }),
+    warning: "FRED vintage dates are unavailable; observations use period dates.",
+  };
+}
+
+export function baseCapabilitySeries(
+  spec: ChartSeriesSpec,
+  loaded: ResolvedSeries,
+  index: number,
+): ResolvedSeries {
+  const points = loaded.points.flatMap((point) => {
+    const date = finiteDate(point.date as unknown as string | Date | undefined);
+    const observedAt = finiteDate(point.observedAt as unknown as string | Date | undefined) ?? date;
+    const availableAt = finiteDate(point.availableAt as unknown as string | Date | undefined) ?? undefined;
+    return date && observedAt ? [{ ...point, date, observedAt, ...(availableAt ? { availableAt } : {}) }] : [];
+  });
+  return {
+    ...loaded,
+    id: spec.id,
+    label: spec.label?.trim() || loaded.label || (spec.source.kind === "capability" ? spec.source.seriesId : spec.id),
+    color: spec.color ?? loaded.color ?? SERIES_COLORS[index % SERIES_COLORS.length]!,
+    style: spec.style,
+    transform: spec.transform,
+    axis: spec.axis === "right" ? "right" : spec.axis === "left" ? "left" : loaded.axis,
+    panelId: spec.panelId,
+    interpolation: spec.interpolation,
+    observationKind: loaded.observationKind ?? "dataset",
+    points,
+  };
+}
+
+export function staleFredWarning(loaded: FredSeriesLoadResult): string | null {
+  if (!loaded.stale) return null;
+  return `FRED refresh failed${loaded.refreshError ? ` (${loaded.refreshError})` : ""}; showing cached data fetched ${new Date(loaded.fetchedAt).toISOString().slice(0, 10)}.`;
+}