gloomberb 0.19.2 → 0.19.3

package/src/time-series/official-close.ts

@@ -0,0 +1,159 @@
+import type { PricePoint, Quote } from "../types/financials";
+import { latestRegularSessionClose, regularSessionCloseOn, sessionCalendarTimeZone } from "../market-data/market/freshness";
+import { quoteTradingDay } from "../market-data/quotes/day-range";
+import { hasLikelyQuoteUnitMismatch } from "../utils/currency-units";
+import { canonicalExchange, isUsListingExchange } from "../utils/exchanges";
+import { zonedDateKey } from "../utils/zoned-date-time";
+
+/** What the footer of an intraday total says while a session has closed but its closing print is not in yet. */
+export const CLOSING_PRINT_PENDING_TEXT = "closing print not in yet";
+
+/** A close this far from the session's last trade is another listing's or another unit's, never its auction print. */
+const MAX_CLOSE_MOVE = 0.25;
+
+function barTime(point: Pick<PricePoint, "date">): number {
+  return new Date(point.date as Date | string | number).getTime();
+}
+
+const positive = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value) && value > 0;
+
+/** Whether `close` can be the close of a session whose last trade was `lastTrade`. */
+function nearLastTrade(close: number, lastTrade: number | null): boolean {
+  return lastTrade === null || !positive(lastTrade) || Math.abs(close / lastTrade - 1) <= MAX_CLOSE_MOVE;
+}
+
+/** The newest regular session that has closed, when the bars hold it, and its last trade there. */
+export interface ClosedSession {
+  /** The session's local date. */
+  date: string;
+  /** The close of its last regular bar: the last trade before the closing auction. */
+  lastTrade: number;
+}
+
+/** When each local date's session closed, read once per date. */
+function sessionCloses(venue: string | undefined) {
+  const closes = new Map<string, number | null>();
+  return (date: string) => {
+    if (!closes.has(date)) closes.set(date, regularSessionCloseOn(venue, date));
+    return closes.get(date)!;
+  };
+}
+
+/** Each closed session's last regular bar, by the session's local date (a later bar is after-hours). */
+function lastRegularBars(points: readonly PricePoint[], venue: string | undefined, now: number): Map<string, number> {
+  const zone = sessionCalendarTimeZone(venue);
+  const latest = latestRegularSessionClose(venue, now);
+  const last = new Map<string, number>();
+  if (!zone || !latest) return last;
+  const closeOn = sessionCloses(venue);
+  points.forEach((point, index) => {
+    const time = barTime(point);
+    if (!Number.isFinite(time)) return;
+    const date = zonedDateKey(time, zone);
+    if (date > latest.date) return;
+    const close = closeOn(date);
+    if (close === null || time >= close) return;
+    last.set(date, index);
+  });
+  return last;
+}
+
+/**
+ * The newest regular session that has closed by `now` (the venue's calendar),
+ * when the bars hold a regular bar of it: the session whose official close a
+ * quote is read for. Null while the venue trades past its last session's
+ * bars, for venues without sessions, and when the bars end earlier.
+ */
+export function newestClosedSession(points: readonly PricePoint[], options: { venue: string | undefined; now: number }): ClosedSession | null {
+  const latest = latestRegularSessionClose(options.venue, options.now);
+  if (!latest) return null;
+  const index = lastRegularBars(points, options.venue, options.now).get(latest.date);
+  return index === undefined ? null : { date: latest.date, lastTrade: points[index]!.close };
+}
+
+/** What the newest closed session's last bar ends on: a close, the note that its print is to come, or nothing to change. */
+export type NewestSessionClose = { close: number } | { pending: true } | null;
+
+/**
+ * The close the newest closed session ends on, for its last regular bar
+ * (`session`, from newestClosedSession). In order:
+ *
+ * 1. The quote's official close of that session (`regularClose`, dated by
+ *    `regularCloseSessionDate` or the quote's trading day).
+ * 2. Right after a US close (POST) without it, the note that the print is to
+ *    come: the quote's price then is the last trade before the auction.
+ * 3. Otherwise (the venue closed, the next pre-market, a listing that
+ *    publishes no closing print) the session's finished daily bar, then the
+ *    quote's own close: its price once closed, its previous close in the
+ *    next pre-market.
+ *
+ * Every figure from the quote must be the bars' listing (same venue, same
+ * currency where both are known), in the bars' units, and within 25% of the
+ * session's last trade; one that is not is not used. A quote of the session
+ * still trading, or none, leaves the daily bar's close or nothing.
+ */
+export function newestSessionClose(
+  quote: Quote | null | undefined,
+  session: ClosedSession & {
+    venue: string | undefined;
+    /** The listing's currency, where known. */
+    currency?: string | null;
+    /** The session's finished daily bar's close, where one was read. */
+    dailyClose?: number | null;
+  },
+): NewestSessionClose {
+  const daily = positive(session.dailyClose) && nearLastTrade(session.dailyClose, session.lastTrade) ? { close: session.dailyClose } : null;
+  if (!quote || quote.marketState === "REGULAR") return daily;
+  const quoteVenue = quote.listingExchangeName || quote.exchangeName;
+  if (quoteVenue && session.venue && canonicalExchange(quoteVenue) !== canonicalExchange(session.venue)) return daily;
+  if (session.currency && quote.currency && session.currency !== quote.currency) return daily;
+  const usable = (value: number | undefined): value is number => positive(value)
+    && !hasLikelyQuoteUnitMismatch({ currency: quote.currency, price: session.lastTrade }, { currency: quote.currency, price: value })
+    && nearLastTrade(value, session.lastTrade);
+  const official = positive(quote.regularClose) && (quote.regularCloseSessionDate ?? quoteTradingDay(quote)) === session.date
+    ? quote.regularClose : undefined;
+  if (official !== undefined) return usable(official) ? { close: official } : daily;
+  if (quote.marketState === "POST" && isUsListingExchange(canonicalExchange(session.venue))) return { pending: true };
+  if (daily) return daily;
+  if (quote.marketState === "PRE" || quote.marketState === "PREPRE") {
+    const previous = quote.previousClose;
+    return (!quote.previousCloseDate || quote.previousCloseDate === session.date) && usable(previous) ? { close: previous } : null;
+  }
+  return quoteTradingDay(quote) === session.date && usable(quote.price) ? { close: quote.price } : null;
+}
+
+/**
+ * Intraday bars of a listing that trades in sessions, each closed session's
+ * last regular bar closing on that session's official close (`closes`, by
+ * the venue's local date) instead of the last trade before the closing
+ * auction: an hourly 19:30 UTC bar of a thin ETF ends on a 19:38 trade at
+ * 12.31 while the 20:00 closing print is 12.19, which every total measured
+ * from the bars then misses. The bar's high and low widen to take the close.
+ * A close more than 25% off the bar's own is another unit's, and not taken.
+ *
+ * A session still trading, bars after its close (after-hours) and venues
+ * without sessions are left as served; the points array is the same one when
+ * nothing changed.
+ */
+export function withOfficialCloses(
+  points: PricePoint[],
+  closes: ReadonlyMap<string, number>,
+  options: { venue: string | undefined; now: number },
+): PricePoint[] {
+  if (points.length === 0 || closes.size === 0) return points;
+  let changed = false;
+  const next = points.slice();
+  for (const [date, index] of lastRegularBars(points, options.venue, options.now)) {
+    const close = closes.get(date);
+    const bar = next[index]!;
+    if (!positive(close) || bar.close === close || !nearLastTrade(close, bar.close)) continue;
+    next[index] = {
+      ...bar,
+      close,
+      ...(positive(bar.high) ? { high: Math.max(bar.high, close) } : {}),
+      ...(positive(bar.low) ? { low: Math.min(bar.low, close) } : {}),
+    };
+    changed = true;
+  }
+  return changed ? next : points;
+}

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

@@ -1,9 +1,10 @@
 import { scalarPointValue } from "./alignment";
 import { getTimeSeriesField } from "./field-catalog";
 import type { ChartSpec, ResolvedSeries, TimeSeriesPoint } from "./types";
-import { chartBarSizeSource, type ManualChartResolution } from "./resolution";
+import { CHART_RESOLUTION_STEP_MS, chartBarSizeSource, getChartResolutionLabel, isIntradayResolution, type ManualChartResolution } from "./resolution";
 import type { TimeRange } from "./range";
 import { zonedDateTimeParts } from "../utils/zoned-date-time";
+import { priceComparisonCloseTimes } from "./coin-session-close";
 import { barLastSession } from "../market-data/market/bar-period";
 import {
   barCloseDay, isIntradayDailyBar, isReturnPeriod, LATEST_INTRADAY_TEXT, periodBaseDay, periodBaseIndex, periodDayText,
@@ -52,6 +53,10 @@ export interface PriceComparisonOptions {
    */
   preset?: TimeRange | null;
   now?: number;
+  /** Coin legs whose daily closes were taken at the session venue's close (coinLegsAtSessionClose). */
+  atSessionClose?: ReadonlySet<string>;
+  /** Of those, the legs whose newest day ends at a session close that has passed: not a price still moving. */
+  closedEnds?: ReadonlySet<string>;
 }
 
 export function observationDate(time: number, series: Pick<ResolvedSeries, "timeBasis">): string {
@@ -156,6 +161,28 @@ export function totalReturnLevelsNotice(spec: ChartSpec, series: readonly Resolv
     priceOnly.length ? ` Price only for ${priceOnly.join(", ")}: distribution history unavailable.` : ""}`;
 }
 
+/**
+ * The bar size intraday legs are matched in: the chart's, or when it has none
+ * the coarsest the legs were served in. Null when neither is intraday.
+ */
+function intradayBucketMs(resolution: ManualChartResolution | "auto", series: ReadonlyArray<ResolvedSeries | undefined>): number | null {
+  const sizes = [resolution, ...series.map((entry) => entry?.historyResolution)]
+    .filter((size): size is ManualChartResolution => !!size && size !== "auto" && size in CHART_RESOLUTION_STEP_MS && isIntradayResolution(size as ManualChartResolution));
+  if (resolution !== "auto" && sizes[0] === resolution) return CHART_RESOLUTION_STEP_MS[resolution];
+  return sizes.length ? Math.max(...sizes.map((size) => CHART_RESOLUTION_STEP_MS[size])) : null;
+}
+
+/** `1H` for an hour's bucket, as the chart names its bar size. */
+function barLabel(bucketMs: number): string {
+  const size = (Object.keys(CHART_RESOLUTION_STEP_MS) as ManualChartResolution[]).find((key) => CHART_RESOLUTION_STEP_MS[key] === bucketMs);
+  return size ? getChartResolutionLabel(size) : `${Math.round(bucketMs / 60_000)}m`;
+}
+
+/** `IBIT and BTC-USD`, `A, B and C`. */
+function listLabels(labels: readonly string[]): string {
+  return labels.length <= 1 ? labels.join("") : `${labels.slice(0, -1).join(", ")} and ${labels.at(-1)}`;
+}
+
 interface ComparedLeg {
   id: string;
   label: string;
@@ -203,6 +230,9 @@ export function resolvePriceComparison(
   const dropped: NonNullable<PriceComparison["dropped"]> = [];
   const reported = new Set<string>();
   const legs: ComparedLeg[] = [];
+  // Intraday bars compare by the bar of the chart's size they open in: a fund's 13:30 bar and a coin's 13:00 bar are
+  // one hourly bar, so the fund's last bar of the day (19:30, closing at 20:00) meets the coin's bar closing then.
+  const bucketMs = calendarBars ? null : intradayBucketMs(resolution, seriesIds.map((id) => byId.get(id)!));
   for (const id of seriesIds) {
     const entry = byId.get(id)!;
     const inWindow = priceObservationWindowFilter(entry, bounds, resolution, dateWindow);
@@ -211,7 +241,7 @@ export function resolvePriceComparison(
     for (const point of entry.points) {
       const time = point.date.getTime();
       if (!Number.isFinite(time) || scalarPointValue(point) === null) continue;
-      const key = calendarBars ? observationDate(time, entry) : String(time);
+      const key = calendarBars ? observationDate(time, entry) : String(bucketMs ? Math.floor(time / bucketMs) * bucketMs : time);
       points.set(key, point);
       if (inWindow(time)) window.add(key);
     }
@@ -237,7 +267,16 @@ export function resolvePriceComparison(
     return legs.length ? keys(legs[0]!).filter((key) => sets.every((set) => set.has(key))) : [];
   };
   const sharedWindow = shared((leg) => leg.window);
-  const sharedStart = sharedWindow.find((key) => legs.every((leg) => nonzero(leg, key)));
+  // Authored dates (`--from 2026-10-19`) measure from the close before the first date, as RETURN does: the last
+  // date the legs share before it. Weekly and monthly bars keep the bar the window starts in.
+  const authoredFrom = !preset && dateWindow && /^\d{4}-\d{2}-\d{2}$/.test(dateWindow.start) && (resolution === "1d" || !calendarBars)
+    ? dateWindow.start : null;
+  const firstInWindow = authoredFrom ? legs.map((leg) => leg.window[0]!).sort(order)[0] : undefined;
+  const authoredBase = authoredFrom && firstInWindow !== undefined
+    ? shared((leg) => leg.keys).filter((key) => (calendarBars ? key < authoredFrom : order(key, firstInWindow) < 0)
+      && legs.every((leg) => nonzero(leg, key))).at(-1)
+    : undefined;
+  const sharedStart = authoredBase ?? sharedWindow.find((key) => legs.every((leg) => nonzero(leg, key)));
   // The period is measured back from the chart's newest observation, by its session day.
   const anchor = period && legs.length
     ? legs.map((leg) => calendarBars ? sessionDay(leg.window.at(-1)!) : dayOf(leg, leg.window.at(-1)!)).sort().at(-1)!
@@ -274,7 +313,14 @@ export function resolvePriceComparison(
   const droppedText = dropped.length
     ? ` Left out: ${dropped.map((entry) => reported.has(entry.seriesId) ? entry.label : `${entry.label} (${entry.reason})`).join("; ")}.`
     : "";
-  if (!compared.length) return { seriesIds, start: null, end: null, notice: unavailable, ...(dropped.length ? { dropped } : {}) };
+  if (!compared.length) {
+    // Intraday legs that never trade in the same bar: said, with the bar size that compares them.
+    const apart = !calendarBars && legs.length >= 2 && sharedWindow.length === 0 && legs.every((leg) => leg.window.length >= 2);
+    const notice = apart
+      ? `${basis} Comparison unavailable: ${listLabels(legs.map((leg) => leg.label))} share no ${bucketMs ? `${barLabel(bucketMs)} ` : ""}bar times in this range; daily bars (1D) compare them.`
+      : unavailable;
+    return { seriesIds, start: null, end: null, notice, ...(dropped.length ? { dropped } : {}) };
+  }
   const sourceBounds = Object.fromEntries(compared.map(({ leg, start, end }) => [leg.id, {
     start: leg.points.get(start)!.date.getTime(),
     end: leg.points.get(end)!.date.getTime(),
@@ -284,7 +330,7 @@ export function resolvePriceComparison(
     const endDay = calendarBars ? sessionDay(end) : dayOf(leg, end);
     // A daily bar of the session still trading, or a week or month running through it.
     return [leg.id, { baseDay: calendarBars ? sessionDay(start) : dayOf(leg, start), endDay,
-      intraday: calendarBars && isIntradayDailyBar(endDay, legVenue(leg.entry), now) }];
+      intraday: calendarBars && !options.closedEnds?.has(leg.id) && isIntradayDailyBar(endDay, legVenue(leg.entry), now) }];
   }));
   const span = calendarBars
     ? (() => {
@@ -292,7 +338,10 @@ export function resolvePriceComparison(
       const to = legsText(compared.map(({ leg }) => ({ label: leg.label, text: legDays[leg.id]!.intraday
         ? `${periodDayText(legDays[leg.id]!.endDay, currentYear)}, ${LATEST_INTRADAY_TEXT}`
         : `${periodDayText(legDays[leg.id]!.endDay, currentYear)} close` })));
-      return `From ${from} to ${to}; market session times may differ.`;
+      // A coin beside a listing that closes each day says when it is measured: at that close, or at 00:00 UTC.
+      const timing = priceComparisonCloseTimes({ legs: legDays }, compared.map(({ leg }) => leg.entry),
+        new Map(compared.map(({ leg }) => [leg.id, leg.label])), options.atSessionClose);
+      return `From ${from} to ${to}; ${timing ?? "market session times may differ"}.`;
     })()
     : baseDay && sharedBase !== undefined
       ? `From ${periodDayText(legDays[compared[0]!.leg.id]!.baseDay, currentYear)} close to ${displayDate(Math.max(...Object.values(sourceBounds).map((range) => range.end)))}.`

package/src/time-series/resolve.ts

@@ -43,7 +43,7 @@ import { FORWARD_PE_BASIS_NOTICE, REALIZED_NTM_PE_BASIS_NOTICE } from "./forward
 import { valuationPriceWarning } from "./valuation-price";
 import { VALUATION_CURRENCY_WARNING_PREFIX } from "./valuation-currency";
 import { chartPriceHistoryIntegrityNotices } from "./market";
-import { maxStudyWarmupPoints, resolveStudies } from "./studies";
+import { maxStudyWarmupPoints, resolveStudies } from "./studies/resolve";
 import { clipSeriesToWindow } from "./alignment";
 import { totalReturnSeries } from "./total-return";
 import {
@@ -55,6 +55,7 @@ import {
   totalReturnLevelsNotice,
 } from "./price-comparison";
 import { chartQuoteOverrideKeyForSource } from "./live-quotes";
+import { coinLegsAtSessionClose } from "./coin-session-close";
 import { chartSeriesSourceKey } from "../capabilities/chart-series";
 import { rememberSeedListingFacts } from "./parsed-history-cache";
 import {
@@ -1057,8 +1058,16 @@ async function resolveChartSpecPass(
   const commonCadence = servedCadences.size === 1 ? [...servedCadences][0] : undefined;
   const resolution = commonCadence ?? undefined;
   const comparisonResolution = resolution ?? "auto";
-  const priceComparison = resolvePriceComparison(spec, rawSeries, bounds, comparisonResolution, requestBounds ? null : spec.viewport.dateWindow,
-    { preset: hasExplicitWindow ? null : spec.viewport.range, now: referenceNow.getTime() + Math.max(0, Date.now() - resolutionStartedAt) });
+  const comparisonOptions = { preset: hasExplicitWindow ? null : spec.viewport.range, now: referenceNow.getTime() + Math.max(0, Date.now() - resolutionStartedAt) };
+  let priceComparison = resolvePriceComparison(spec, rawSeries, bounds, comparisonResolution, requestBounds ? null : spec.viewport.dateWindow, comparisonOptions);
+  // A coin compared in daily closes with a listing that closes each day is measured at that close when its hourly bars reach.
+  const timed = sources.dataProvider && comparisonResolution === "1d"
+    ? await coinLegsAtSessionClose(priceComparison, rawSeries, sources.dataProvider, comparisonOptions.now) : null;
+  if (timed?.timing.atSessionClose.size) {
+    rawSeries.splice(0, rawSeries.length, ...timed.series);
+    priceComparison = resolvePriceComparison(spec, rawSeries, bounds, comparisonResolution, requestBounds ? null : spec.viewport.dateWindow,
+      { ...comparisonOptions, atSessionClose: timed.timing.atSessionClose, closedEnds: timed.timing.closedEnds });
+  }
   const displayBounds = comparisonDisplayBounds(bounds, priceComparison);
   const comparisonBounds = priceComparison && priceComparison.start !== null
     ? priceComparison : bounds;

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

@@ -2,7 +2,7 @@ import { limitSeriesObservations } from "./financial-period-coverage";
 import type { ManualChartResolution } from "./resolution";
 import { getTimeSeriesField } from "./field-catalog";
 import { collectPriceHistoryIntegrity } from "./market";
-import { activeStudyInputSeriesIds } from "./studies";
+import { activeStudyInputSeriesIds } from "./studies/resolve";
 import { applyResolvedSeriesTransform } from "./transforms";
 import { clipSeriesToWindow } from "./alignment";
 import type { StudyAnchor } from "./leverage";

package/src/time-series/studies/formula.ts

@@ -0,0 +1,205 @@
+import { alignTimeSeries } from "../alignment";
+import type { ChartStudySpec, ResolvedSeries, TimeSeriesPoint } from "../types";
+import { isFiniteNumber } from "../../utils/guards";
+import { GALLONS_PER_BARREL, isBarrelsPerTonne, perBarrelUnit, perTonneUnit } from "../price-units";
+import { derivedPoint, outputSeries } from "./shared";
+import {
+  combinedUnit,
+  derivedValueDecimals,
+  fxConversionIssue,
+  isPriceGroup,
+  knownUnitSignature,
+  legName,
+  unitMismatchMessage,
+  type SeriesUnit,
+} from "./units";
+
+interface FormulaLeg {
+  /** The input's place in the study's inputs. */
+  index: number;
+  /** Its multiplier, its sign included. */
+  weight: number;
+  /** The multiplier carries the 42 gallons that make a per-gallon price per barrel. */
+  perBarrel: boolean;
+  /** The barrels in a tonne the multiplier carries (7.45 for gasoil), making a per-barrel price per tonne. */
+  perTonne: number | null;
+}
+
+export interface FormulaTerms {
+  /** The inputs the formula adds up. */
+  legs: FormulaLeg[];
+  /** The inputs the whole sum is multiplied (1) or divided (-1) by: `/EURUSD=X`. */
+  factors: Array<{ index: number; power: 1 | -1 }>;
+  divisor: number;
+}
+
+/**
+ * A formula study's terms: `weight1`, `perBarrel1`, `perTonne1` ... per
+ * input it adds up, `power1` ... (1 or -1) per input it multiplies or divides
+ * the sum by, and an optional `divisor`. A saved or hand-edited spec can carry
+ * a multiplier or divisor no formula was written with (a value that is not a
+ * number is dropped when the spec loads, so it arrives missing); that is an
+ * error, not a silent 1.
+ */
+export function formulaTerms(spec: ChartStudySpec, inputs: readonly ResolvedSeries[]): FormulaTerms | { error: string } {
+  const legs: FormulaLeg[] = [];
+  const factors: FormulaTerms["factors"] = [];
+  for (const [index, input] of inputs.entries()) {
+    const power = spec.parameters[`power${index + 1}`];
+    if (power !== undefined) {
+      if (power !== 1 && power !== -1) return { error: `The formula neither multiplies nor divides by ${legName(input)}; write the formula again.` };
+      factors.push({ index, power });
+      continue;
+    }
+    const weight = spec.parameters[`weight${index + 1}`];
+    if (!isFiniteNumber(weight)) return { error: `The multiplier of ${legName(input)} is missing or not a number; write the formula again.` };
+    if (weight === 0) return { error: `${legName(input)} has a multiplier of 0, which removes it; leave it out of the formula instead.` };
+    const perTonne = spec.parameters[`perTonne${index + 1}`];
+    legs.push({
+      index,
+      weight,
+      perBarrel: spec.parameters[`perBarrel${index + 1}`] === 1,
+      perTonne: isFiniteNumber(perTonne) && isBarrelsPerTonne(perTonne) ? perTonne : null,
+    });
+  }
+  if (legs.length === 0) return { error: "The formula has no series to add up, only series it divides by; write the formula again." };
+  const divisor = spec.parameters.divisor ?? 1;
+  if (!isFiniteNumber(divisor)) return { error: "The formula's divisor is not a number; write the formula again." };
+  if (divisor === 0) return { error: "A formula cannot be divided by 0." };
+  return { legs, factors, divisor };
+}
+
+/**
+ * A leg's unit once its multiplier is applied: 42 gallons of a per-gallon
+ * price are a barrel's worth, and 7.45 barrels of gasoil a tonne's.
+ */
+function formulaLegUnit(leg: FormulaLeg, input: ResolvedSeries): string {
+  const unit = leg.perBarrel ? perBarrelUnit(input.unit) : input.unit;
+  return leg.perTonne ? perTonneUnit(unit) : unit;
+}
+
+/** Why a formula's legs cannot be summed, or null when every leg counts the same known unit. */
+function formulaUnitMismatch(terms: FormulaTerms, inputs: readonly ResolvedSeries[]): string | null {
+  if (terms.legs.length < 2) return null;
+  const legs = terms.legs.map((leg) => ({ series: inputs[leg.index]!, unit: formulaLegUnit(leg, inputs[leg.index]!) }));
+  const signatures = legs.map(({ series, unit }) => knownUnitSignature({ unit, unitGroup: series.unitGroup }));
+  const other = signatures.findIndex((signature, index) => index > 0 && (signature === null || signature !== signatures[0]));
+  if (signatures[0] !== null && other < 0) return null;
+  return unitMismatchMessage("formula", legs[0]!, legs[Math.max(1, other)]!);
+}
+
+function formatFormulaNumber(value: number): string {
+  return String(Number(value.toPrecision(10)));
+}
+
+/**
+ * A formula as the legend names it, from the terms it was written with:
+ * `42×HO=F - CL=F`, `(2×42×RB=F + 42×HO=F - 3×CL=F)/3`, `(42×HO=F - BZ=F)/EURUSD=X`.
+ */
+function formulaLabel(inputs: readonly ResolvedSeries[], terms: FormulaTerms): string {
+  const sum = terms.legs.map((leg, position) => {
+    const magnitude = Math.abs(leg.weight);
+    // The conversions it carries are named as written: 7.45×42×HO=F.
+    const conversions = [...(leg.perTonne ? [leg.perTonne] : []), ...(leg.perBarrel ? [GALLONS_PER_BARREL] : [])];
+    const count = conversions.reduce((rest, factor) => rest / factor, magnitude);
+    const factors = [...(Math.abs(count - 1) < 1e-9 ? [] : [formatFormulaNumber(count)]), ...conversions.map(String)];
+    const term = [...factors, legName(inputs[leg.index]!)].join("×");
+    if (position === 0) return leg.weight < 0 ? `-${term}` : term;
+    return `${leg.weight < 0 ? "-" : "+"} ${term}`;
+  }).join(" ");
+  if (terms.divisor === 1 && terms.factors.length === 0) return sum;
+  return [
+    `(${sum})`,
+    ...(terms.divisor === 1 ? [] : [`/${formatFormulaNumber(terms.divisor)}`]),
+    ...terms.factors.map(({ index, power }) => `${power < 0 ? "/" : "×"}${legName(inputs[index]!)}`),
+  ].join("");
+}
+
+/** Every input's value on each date they share, each carried forward to the others' dates. */
+function alignedSamples(inputs: readonly ResolvedSeries[]): Array<{ point: TimeSeriesPoint; values: number[] }> {
+  return alignTimeSeries(inputs, { mode: "intersection", carryForward: true }).flatMap((row) => {
+    const aligned = inputs.map((input) => row.values[input.id]);
+    if (aligned.some((entry) => !isFiniteNumber(entry?.value))) return [];
+    const availability = Math.max(...aligned.map((entry) => entry!.point.availableAt?.getTime() ?? entry!.point.date.getTime()));
+    return [{
+      values: aligned.map((entry) => entry!.value as number),
+      point: {
+        date: new Date(row.date),
+        observedAt: new Date(row.date),
+        availableAt: Number.isFinite(availability) ? new Date(availability) : undefined,
+        value: null,
+        provenance: { quality: "derived" as const },
+      },
+    }];
+  });
+}
+
+/**
+ * A weighted sum of the legs over a divisor, in the unit the legs share once
+ * converted, then times or over the series it is scaled by, in the unit
+ * that arithmetic leaves: a crack in USD / barrel over EURUSD=X is EUR / barrel.
+ */
+/**
+ * A formula's unit: its legs' once converted, then times or over each series
+ * it is scaled by. Legs that count different units, or an FX rate the wrong
+ * way up, are an error that says why: a crack over USDJPY=X is no price, and
+ * times it JPY / barrel.
+ */
+export function formulaUnit(terms: FormulaTerms, inputs: readonly ResolvedSeries[]): SeriesUnit | { error: string } {
+  const mismatch = formulaUnitMismatch(terms, inputs);
+  if (mismatch) return { error: mismatch };
+  const first = inputs[terms.legs[0]!.index]!;
+  let unit: SeriesUnit = { unit: formulaLegUnit(terms.legs[0]!, first), unitGroup: first.unitGroup };
+  for (const factor of terms.factors) {
+    const series = inputs[factor.index]!;
+    const next = combinedUnit(unit, series, factor.power);
+    const issue = fxConversionIssue(unit, series, factor.power, next);
+    if (issue) return { error: issue };
+    unit = next;
+  }
+  return unit;
+}
+
+export function resolveFormula(
+  spec: ChartStudySpec,
+  inputs: readonly ResolvedSeries[],
+  terms: FormulaTerms,
+  unit: SeriesUnit,
+  color: string,
+): ResolvedSeries[] {
+  const first = inputs[terms.legs[0]!.index]!;
+  // Rounded off the float's last digits: 42 × 4.6233 - 96.12 is 98.0586, not 98.05860000000001.
+  const points = alignedSamples(inputs).map(({ point, values }) => {
+    let value: number | null = terms.legs.reduce((sum, leg) => sum + values[leg.index]! * leg.weight, 0) / terms.divisor;
+    for (const factor of terms.factors) {
+      const scale = values[factor.index]!;
+      value = value === null || (factor.power < 0 && scale === 0) ? null : factor.power < 0 ? value / scale : value * scale;
+    }
+    return derivedPoint({ point, value: 0 }, value === null ? null : Number(value.toPrecision(12)));
+  });
+  const frequencies = new Set(inputs.map((input) => input.nativeFrequency));
+  const resolutions = new Set(inputs.map((input) => input.historyResolution));
+  const scaled = terms.factors.length > 0;
+  // A price per quantity reads with its unit beside it, as a future's does.
+  const statedUnit = scaled
+    ? isPriceGroup(unit.unitGroup) && unit.unit.includes("/") ? unit.unit : null
+    : inputs.some((input) => input.statedUnit) ? unit.unit : null;
+  const valueDecimals = !scaled || isPriceGroup(unit.unitGroup) ? derivedValueDecimals(inputs, points) : undefined;
+  return [outputSeries(spec, first, {
+    label: formulaLabel(inputs, terms),
+    points,
+    color,
+    unit: unit.unit,
+    unitGroup: unit.unitGroup,
+    statedUnit,
+    // A weighted sum is no traded price: its decimals are its legs', not a contract's tick.
+    priceAssetCategory: null,
+    ...(valueDecimals !== undefined ? { valueDecimals } : {}),
+    // As the pair formulas: as-of levels, constant until an input changes.
+    style: "step",
+    interpolation: "step-after",
+    axis: "left",
+    nativeFrequency: frequencies.size === 1 ? first.nativeFrequency : "auto",
+    historyResolution: resolutions.size === 1 ? first.historyResolution : null,
+  })];
+}