gloomberb 0.18.3 → 0.18.4

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

@@ -0,0 +1,38 @@
+import { publicTickerKey } from "../utils/exchanges";
+import type { ChartSeriesSpec, ChartStudySpec } from "./types";
+
+/**
+ * What a series' errors are prefixed with: its label, else what was asked for
+ * (`VIX`, `FRED GDP`), never the internal id a preset gave it (`vix-market-close-3`).
+ */
+export function seriesMessageName(spec: Pick<ChartSeriesSpec, "label" | "source">): string {
+  const label = spec.label?.trim();
+  if (label) return label;
+  switch (spec.source.kind) {
+    case "security": return publicTickerKey(spec.source.instrument.symbol, spec.source.instrument.exchange);
+    case "economic": return `FRED ${spec.source.seriesId}`;
+    case "capability": return spec.source.seriesId;
+  }
+}
+
+const STUDY_MESSAGE_NAMES: Partial<Record<ChartStudySpec["kind"], string>> = {
+  "realized-vol": "Realized volatility",
+  "volume-profile": "Volume profile",
+  "anchored-vwap": "Anchored VWAP",
+  "leverage-decay": "Leverage decay",
+  atr: "ATR",
+  sma: "SMA",
+  ema: "EMA",
+  rsi: "RSI",
+  macd: "MACD",
+  vwap: "VWAP",
+};
+
+/**
+ * What a study's errors and warnings are prefixed with: what it is
+ * (`Ratio`, `Realized volatility`), never the id the chart gave it
+ * (`pair:ratio`, `builtin:realized-vol:price`).
+ */
+export function studyMessageName(spec: Pick<ChartStudySpec, "kind">): string {
+  return STUDY_MESSAGE_NAMES[spec.kind] ?? `${spec.kind[0]!.toUpperCase()}${spec.kind.slice(1)}`;
+}

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

@@ -0,0 +1,208 @@
+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 { applyResolvedSeriesTransform } from "./transforms";
+import { clipSeriesToWindow } from "./alignment";
+import type { StudyAnchor } from "./leverage";
+import {
+  comparedBufferPoints,
+  priceComparisonBoundsForSeries,
+  priceObservationWindowFilter,
+  type PriceComparison,
+} from "./price-comparison";
+import { parsePublicTickerKey, publicTickerKey } from "../utils/exchanges";
+import type {
+  ChartSeriesSpec,
+  ChartSpec,
+  ResolvedSeries,
+} from "./types";
+import { type DateBounds, filterPoints } from "./chart-bounds";
+
+export function resolvePriceHistoryIntegrity(
+  spec: ChartSpec,
+  requestedSeries: readonly ResolvedSeries[],
+  visibleSeries: readonly ResolvedSeries[],
+  bounds: DateBounds,
+  resolution: ManualChartResolution | "auto",
+  dateWindow: ChartSpec["viewport"]["dateWindow"] | null,
+) {
+  const filters = new Map(requestedSeries.map((entry) => [entry.id, priceObservationWindowFilter(entry, bounds, resolution, dateWindow)]));
+  const requestedIds = activeStudyInputSeriesIds(spec.studies);
+  spec.series.filter((entry) => entry.visible !== false).forEach((entry) => requestedIds.add(entry.id));
+  const selected = requestedSeries.filter((entry) => requestedIds.has(entry.id)).map((entry) => limitSeriesObservations(spec, {
+    ...entry, points: entry.points.filter((point) => filters.get(entry.id)!(point.date.getTime())),
+  }));
+  return [
+    ...collectPriceHistoryIntegrity(selected, "requested-observation", (id, time) => filters.get(id)!(time)),
+    ...collectPriceHistoryIntegrity(visibleSeries, "visible-calculation"),
+  ];
+}
+
+export function assignAxes(
+  series: ResolvedSeries[],
+  specs: readonly { id: string; axis: ChartSeriesSpec["axis"] }[],
+  warnings: string[],
+): ResolvedSeries[] {
+  const requested = new Map(specs.map((spec) => [spec.id, spec.axis] as const));
+  const groupsByPanel = new Map<string, Partial<Record<"left" | "right", string>>>();
+  return series.map((entry) => {
+    const groups = groupsByPanel.get(entry.panelId) ?? {};
+    groupsByPanel.set(entry.panelId, groups);
+    const preferred = requested.get(entry.id);
+    let axis: "left" | "right";
+    if (preferred === "left" || preferred === "right") {
+      axis = preferred;
+    } else if (groups.left === entry.unitGroup) {
+      axis = "left";
+    } else if (groups.right === entry.unitGroup) {
+      axis = "right";
+    } else if (!groups.left) {
+      axis = "left";
+    } else {
+      axis = "right";
+    }
+    if (groups[axis] && groups[axis] !== entry.unitGroup) {
+      warnings.push(`${entry.label} shares the ${axis} axis with a different unit; choose an explicit panel for independent scaling.`);
+    }
+    groups[axis] ??= entry.unitGroup;
+    return { ...entry, axis };
+  });
+}
+
+/**
+ * A series drawn in a ticker's price (a moving average of it, a band around
+ * it) takes the units of that ticker's price series when the chart has it, so
+ * the two share an axis and the line sits on the price instead of on a scale
+ * of its own.
+ */
+export function adoptPriceUnits(series: ResolvedSeries[], specs: readonly ChartSeriesSpec[]): ResolvedSeries[] {
+  if (!series.some((entry) => entry.priceOf)) return series;
+  const specsById = new Map(specs.map((spec) => [spec.id, spec]));
+  const prices = series.filter((entry) => {
+    const source = specsById.get(entry.id)?.source;
+    return source?.kind === "security" && getTimeSeriesField(source.fieldId)?.unitGroup === "price"
+      && entry.transform === "raw";
+  });
+  if (prices.length === 0) return series;
+  return series.map((entry) => {
+    if (!entry.priceOf) return entry;
+    const wanted = parsePublicTickerKey(entry.priceOf.toUpperCase());
+    const key = publicTickerKey(wanted.symbol, wanted.exchange);
+    const named = (price: ResolvedSeries) => {
+      const source = specsById.get(price.id)?.source;
+      if (source?.kind !== "security") return false;
+      return publicTickerKey(source.instrument.symbol, source.instrument.exchange) === key
+        || (!wanted.exchange && source.instrument.symbol.toUpperCase() === wanted.symbol);
+    };
+    const price = prices.find((candidate) => named(candidate) && candidate.panelId === entry.panelId)
+      ?? prices.find(named);
+    return price && entry.transform === "raw"
+      ? { ...entry, unit: price.unit, unitGroup: price.unitGroup }
+      : entry;
+  });
+}
+
+/**
+ * Where studies that read returns over the chart's period measure each series
+ * from and to: a compared leg's shared first and last session, else the
+ * window in view.
+ */
+export function studyAnchors(
+  series: readonly ResolvedSeries[],
+  comparison: PriceComparison | null,
+  bounds: DateBounds,
+): Map<string, StudyAnchor> {
+  return new Map(series.map((entry) => [entry.id, priceComparisonBoundsForSeries(entry, comparison) ?? bounds]));
+}
+
+export function prepareBaseSeriesForStudies(
+  series: ResolvedSeries,
+  bounds: DateBounds,
+  clipToBounds = false,
+  fallbackBaselineBounds?: DateBounds,
+): ResolvedSeries {
+  const baselineTransform = series.transform === "percent" || series.transform === "index100";
+  let source = series;
+  if (clipToBounds && bounds.start !== null && bounds.end !== null) {
+    source = clipSeriesToWindow(series, new Date(bounds.start), new Date(bounds.end));
+  } else if (clipToBounds) {
+    source = { ...series, points: filterPoints(series.points, bounds) };
+  }
+  const baseline = baselineTransform
+    ? scalarBaseline(series, bounds)
+      ?? (fallbackBaselineBounds ? scalarBaseline(series, fallbackBaselineBounds) : null)
+    : null;
+  return applyResolvedSeriesTransform(
+    source,
+    source.transform,
+    baselineTransform ? { baseline } : undefined,
+  );
+}
+
+function scalarBaseline(series: ResolvedSeries, bounds: DateBounds): number | null {
+  const points = filterPoints(series.points, bounds);
+  for (const point of points) {
+    const value = typeof point.value === "number" && Number.isFinite(point.value)
+      ? point.value
+      : typeof point.close === "number" && Number.isFinite(point.close)
+        ? point.close
+        : null;
+    if (value !== null && value !== 0) return value;
+  }
+  return null;
+}
+
+function studyForOutput(
+  outputId: string,
+  studies: readonly ChartSpec["studies"][number][],
+): ChartSpec["studies"][number] | undefined {
+  return studies
+    .filter((study) => outputId === study.id || outputId.startsWith(`${study.id}:`))
+    .sort((left, right) => right.id.length - left.id.length)[0];
+}
+
+/** Price overlays read in the price's own terms, so they take its transform. */
+function followsInputTransform(kind: ChartSpec["studies"][number]["kind"]): boolean {
+  return kind === "sma" || kind === "ema" || kind === "bollinger" || kind === "vwap" || kind === "anchored-vwap";
+}
+
+export function presentationBounds(
+  series: ResolvedSeries,
+  studies: readonly ChartSpec["studies"][number][],
+  comparison: PriceComparison | null,
+  fallback: DateBounds,
+): DateBounds {
+  const study = studyForOutput(series.id, studies);
+  const sourceId = study && followsInputTransform(study.kind)
+    ? study.inputSeriesIds[0] : series.id;
+  return (sourceId && comparison?.sourceBounds?.[sourceId]) || fallback;
+}
+
+export function applyStudyPresentationTransforms(
+  outputs: ResolvedSeries[],
+  studies: readonly ChartSpec["studies"][number][],
+  rawSeries: readonly ResolvedSeries[],
+  visibleBounds: DateBounds,
+  fallbackBaselineBounds?: DateBounds,
+  priceComparison?: PriceComparison | null,
+  view: DateBounds = visibleBounds,
+): ResolvedSeries[] {
+  const rawById = new Map(rawSeries.map((series) => [series.id, series] as const));
+  return outputs.map((output) => {
+    const study = studyForOutput(output.id, studies);
+    if (!study || !followsInputTransform(study.kind)) {
+      return output;
+    }
+    const input = rawById.get(study.inputSeriesIds[0] ?? "");
+    if (!input || input.transform === "raw") return output;
+    const baseline = input.transform === "percent" || input.transform === "index100"
+      ? scalarBaseline(input, priceComparisonBoundsForSeries(input, priceComparison ?? null) ?? visibleBounds)
+        ?? (fallbackBaselineBounds ? scalarBaseline(input, fallbackBaselineBounds) : null)
+      : undefined;
+    const transformed = applyResolvedSeriesTransform(output, input.transform, { baseline });
+    const inputBounds = priceComparison?.sourceBounds?.[input.id];
+    return inputBounds ? { ...transformed, points: comparedBufferPoints(transformed.points, inputBounds, view) } : transformed;
+  });
+}

package/src/time-series/spec.ts

@@ -1,6 +1,6 @@
-import { CHART_RESOLUTIONS, TIME_RANGES, type ChartResolution, type TimeRange } from "./range";
+import { TIME_RANGES, type ChartResolution, type TimeRange } from "./range";
 import { isRealizedVolatilityEstimator } from "../market-data/realized-volatility";
-import { getChartResolutionLabel } from "./resolution";
+import { getChartResolutionLabel, isChartResolution } from "./resolution";
 import {
   canonicalTimeSeriesFieldId,
   getTimeSeriesField,
@@ -32,9 +32,9 @@ import {
   isValidChartSeriesId,
 } from "../capabilities/chart-series";
 import { recordOrNull } from "../utils/guards";
+import { isLeverageFactor } from "./leverage";
 
 const RANGE_SET = new Set<TimeRange>(TIME_RANGES);
-const RESOLUTIONS = new Set<ChartResolution>(CHART_RESOLUTIONS);
 const PERIODS = new Set<SeriesPeriod>(["auto", "daily", "weekly", "monthly", "quarterly", "annual", "ttm"]);
 // `band` only stays on a capability series: a field's styles and an economic series' leave it out.
 const STYLES = new Set<SeriesStyle>(["line", "area", "step", "columns", "points", "candles", "ohlc", "hlc", "band"]);
@@ -58,6 +58,8 @@ const STUDIES = new Set<ChartStudyKind>([
   "spread",
   "correlation",
   "formula",
+  "leverage",
+  "leverage-decay",
 ]);
 
 /**
@@ -321,7 +323,7 @@ export function normalizeChartSpec(value: unknown, fallback: ChartSpec = DEFAULT
       range: RANGE_SET.has(viewport?.range as TimeRange)
         ? viewport!.range as TimeRange
         : fallbackCopy.viewport.range,
-      resolution: RESOLUTIONS.has(viewport?.resolution as ChartResolution)
+      resolution: isChartResolution(viewport?.resolution)
         ? viewport!.resolution as ChartResolution
         : fallbackCopy.viewport.resolution,
       dateWindow: normalizedDateWindow(viewport?.dateWindow),
@@ -343,7 +345,7 @@ function issue(path: string, code: string, message: string): ChartSpecIssue {
 }
 
 function requiredInputCount(kind: ChartStudyKind): number {
-  return kind === "ratio" || kind === "spread" || kind === "correlation" ? 2 : 1;
+  return kind === "ratio" || kind === "spread" || kind === "correlation" || kind === "leverage-decay" ? 2 : 1;
 }
 
 /** Whether a study has the inputs its kind takes: two for a pair, one or more for a formula, one for the rest. */
@@ -361,7 +363,7 @@ export function validateChartSpec(spec: ChartSpec): ChartSpecValidationResult {
     errors.push(issue("version", "unsupported-version", `Unsupported chart spec version ${String(spec.version)}.`));
   }
   if (!RANGE_SET.has(spec.viewport.range)) errors.push(issue("viewport.range", "invalid-range", "Invalid date range."));
-  if (!RESOLUTIONS.has(spec.viewport.resolution)) {
+  if (!isChartResolution(spec.viewport.resolution)) {
     errors.push(issue("viewport.resolution", "invalid-resolution", "Invalid chart resolution."));
   }
   if (spec.viewport.dateWindow) {
@@ -544,6 +546,9 @@ export function validateChartSpec(spec: ChartSpec): ChartSpecValidationResult {
       const slow = study.parameters.slow ?? 26;
       if (typeof fast === "number" && typeof slow === "number" && fast >= slow) errors.push(issue(`${path}.parameters`, "invalid-macd-periods", "MACD fast period must be shorter than slow period."));
     }
+    if ((study.kind === "leverage" || study.kind === "leverage-decay") && !isLeverageFactor(study.parameters.factor)) {
+      errors.push(issue(`${path}.parameters.factor`, "invalid-factor", "A leverage factor is a nonzero multiple of at most 5, such as 3 or -3."));
+    }
   });
 
   if (spec.series.length === 0) warnings.push(issue("series", "empty-chart", "Chart has no data series."));

package/src/time-series/studies.ts

@@ -17,6 +17,8 @@ import type {
   TimeSeriesPoint,
 } from "./types";
 import { isFiniteNumber } from "../utils/guards";
+import { studyMessageName } from "./series-name";
+import { dailyLeverageGrowth, isLeverageFactor, leverageDecayPoints, leverageFactorLabel, leverageSymbol, sessionCloses, type StudyAnchor } from "./leverage";
 import { GALLONS_PER_BARREL, isPerBarrelUnit, isPerGallonUnit, perBarrelUnit, quantityIdentity, unitCurrencyToken } from "./price-units";
 
 export interface StudyResolutionResult {
@@ -45,7 +47,10 @@ const KIND_COLORS: Partial<Record<ChartStudyKind, string>> = {
   "anchored-vwap": "#b197fc",
   "volume-profile": "#adb5bd",
   atr: "#63e6be",
+  leverage: "#e599f7",
 };
+/** The decay study's two lines: the fund against the daily line, the daily line against the period multiple. */
+const DECAY_COLORS = ["#ffa94d", "#66d9e8"] as const;
 /**
  * One per anchor, so eight lines never repeat a colour. None is red or pink
  * (falling candles take the theme's negative), orange (VWAP), yellow (the
@@ -117,6 +122,7 @@ function outputSeries(
     nativeFrequency: options.nativeFrequency ?? input.nativeFrequency,
     ...(historyResolution !== undefined ? { historyResolution } : {}),
     ...(input.historyStart && historyResolution === input.historyResolution ? { historyStart: input.historyStart } : {}),
+    ...(input.barSize && historyResolution === input.historyResolution ? { barSize: input.barSize } : {}),
     dataShape: "scalar",
     style: options.style ?? "line",
     transform: "raw",
@@ -1084,7 +1090,70 @@ function resolveFormula(
 }
 
 function requiredInputs(kind: ChartStudyKind): number {
-  return kind === "ratio" || kind === "spread" || kind === "correlation" ? 2 : 1;
+  return kind === "ratio" || kind === "spread" || kind === "correlation" || kind === "leverage-decay" ? 2 : 1;
+}
+
+/** The objective's line and its decay compound session returns: they need daily bars, whatever the chart's range. */
+function dailyBarsIssue(spec: ChartStudySpec, input: ResolvedSeries, marketResolution: ManualChartResolution | undefined): string | null {
+  const resolution = input.historyResolution === undefined ? marketResolution : input.historyResolution;
+  if (input.nativeFrequency === "daily" && (resolution === undefined || resolution === "1d")) return null;
+  return `${studyMessageName(spec)}: ${leverageFactorLabel(Number(spec.parameters.factor))} daily needs daily bars. Choose D bars.`;
+}
+
+/**
+ * The line a leveraged or inverse fund's daily objective draws from its index
+ * fund, in percent from where the chart compares (3× daily QQQ beside TQQQ),
+ * on the percent axis the compared legs share.
+ */
+function resolveLeverageLine(spec: ChartStudySpec, index: ResolvedSeries, color: string, anchor: StudyAnchor | undefined): ResolvedSeries[] {
+  const factor = spec.parameters.factor as number;
+  const closes = sessionCloses(index, anchor);
+  const growth = dailyLeverageGrowth(closes.map((entry) => entry.close), factor);
+  return [outputSeries(spec, index, {
+    label: `${leverageFactorLabel(factor)} daily ${leverageSymbol(index)}`,
+    points: closes.map((entry, position) => derivedPoint({ point: entry.point, value: entry.close }, (growth[position]! - 1) * 100)),
+    color,
+    unit: "%",
+    unitGroup: "percent",
+    statedUnit: null,
+    priceAssetCategory: null,
+    axis: "left",
+  })];
+}
+
+/**
+ * How far the fund falls short of its daily objective, in percentage points
+ * from where the chart compares: the fund against the daily line (fees,
+ * financing, tracking), and the daily line against the factor times the index
+ * fund's return over the period (compounding, which daily resets cost in a
+ * market that swings).
+ */
+function resolveLeverageDecay(
+  spec: ChartStudySpec,
+  fund: ResolvedSeries,
+  index: ResolvedSeries,
+  anchors: ReadonlyMap<string, StudyAnchor> | undefined,
+): ResolvedSeries[] {
+  const factor = spec.parameters.factor as number;
+  const decay = leverageDecayPoints(sessionCloses(fund, anchors?.get(fund.id)), sessionCloses(index, anchors?.get(index.id)), factor);
+  const daily = `${leverageFactorLabel(factor)} daily`;
+  const line = (id: string, label: string, color: string, value: (point: (typeof decay)[number]) => number) => outputSeries(spec, fund, {
+    id: `${spec.id}:${id}`,
+    label,
+    points: decay.map((entry) => derivedPoint({ point: entry.point, value: entry.fund }, value(entry))),
+    color: spec.color ?? color,
+    unit: "pp",
+    // Not a percent group: a difference of returns reads in points (-0.96 pp), not as a return.
+    unitGroup: "pp",
+    statedUnit: null,
+    priceAssetCategory: null,
+    axis: "left",
+  });
+  return [
+    line("fund", `${leverageSymbol(fund)} decay vs ${daily} ${leverageSymbol(index)}`, DECAY_COLORS[0], (entry) => entry.fund - entry.daily),
+    // `3× QQQ`: three times QQQ's return over the period, the multiple a daily reset does not deliver.
+    line("compounding", `${daily} ${leverageSymbol(index)} decay vs ${leverageFactorLabel(factor)} ${leverageSymbol(index)}`, DECAY_COLORS[1], (entry) => entry.daily - entry.period),
+  ];
 }
 
 /**
@@ -1188,16 +1257,23 @@ export function activeStudyInputSeriesIds(
     .flatMap((spec) => spec.inputSeriesIds));
 }
 
+/**
+ * `anchors`: where each input series is measured from and to, for studies
+ * that read returns over the chart's period (a leveraged fund's daily line and
+ * its decay start where a comparison starts its legs). Without one, a series'
+ * own first and last observations.
+ */
 export function resolveStudies(
   baseSeries: readonly ResolvedSeries[],
   studySpecs: readonly ChartStudySpec[],
   marketResolution?: ManualChartResolution,
   historicalPriceSeries?: ReadonlyMap<string, ResolvedSeries>,
+  anchors?: ReadonlyMap<string, StudyAnchor>,
 ): StudyResolutionResult {
   // With one security on the chart its volume is just "Volume"; beside a
   // comparison the legend names whose volume it is.
   const nameVolumeInput = baseSeries.filter((series) => series.observationKind === "market").length > 1;
-  return resolveStudySpecs(baseSeries, studySpecs, nameVolumeInput, marketResolution, historicalPriceSeries);
+  return resolveStudySpecs(baseSeries, studySpecs, nameVolumeInput, marketResolution, historicalPriceSeries, anchors);
 }
 
 function resolveStudySpecs(
@@ -1206,6 +1282,7 @@ function resolveStudySpecs(
   nameVolumeInput: boolean,
   marketResolution?: ManualChartResolution,
   historicalPriceSeries?: ReadonlyMap<string, ResolvedSeries>,
+  anchors?: ReadonlyMap<string, StudyAnchor>,
 ): StudyResolutionResult {
   const byId = new Map(baseSeries.map((series) => [series.id, series]));
   const resolved: ResolvedSeries[] = [];
@@ -1218,7 +1295,7 @@ function resolveStudySpecs(
     const inputs = spec.inputSeriesIds.map((id) => spec.kind === "realized-vol"
       ? historicalPriceSeries?.get(id) ?? byId.get(id) : byId.get(id));
     if (inputs.length !== required || inputs.some((input) => !input)) {
-      errors.push(`${spec.id}: ${spec.kind} requires ${required} valid input series.`);
+      errors.push(`${studyMessageName(spec)}: ${spec.kind} requires ${required} valid input series.`);
       return;
     }
     const input = inputs[0]!;
@@ -1226,7 +1303,7 @@ function resolveStudySpecs(
       const pairedInput = inputs[1]!;
       const inputUnit = knownUnitSignature(input);
       if (inputUnit === null || inputUnit !== knownUnitSignature(pairedInput)) {
-        errors.push(`${spec.id}: ${unitMismatchMessage("spread", { series: input, unit: input.unit }, { series: pairedInput, unit: pairedInput.unit })}`);
+        errors.push(`${studyMessageName(spec)}: ${unitMismatchMessage("spread", { series: input, unit: input.unit }, { series: pairedInput, unit: pairedInput.unit })}`);
         return;
       }
     }
@@ -1235,17 +1312,37 @@ function resolveStudySpecs(
       const read = formulaTerms(spec, inputs as ResolvedSeries[]);
       const mismatch = "error" in read ? read.error : formulaUnitMismatch(read, inputs as ResolvedSeries[]);
       if (mismatch) {
-        errors.push(`${spec.id}: ${mismatch}`);
+        errors.push(`${studyMessageName(spec)}: ${mismatch}`);
         return;
       }
       terms = read as FormulaTerms;
     }
     const color = spec.color ?? KIND_COLORS[spec.kind] ?? STUDY_COLORS[index % STUDY_COLORS.length]!;
+    if (spec.kind === "leverage" || spec.kind === "leverage-decay") {
+      const index = inputs.at(-1)!;
+      if (!isLeverageFactor(spec.parameters.factor)) {
+        errors.push(`${studyMessageName(spec)}: choose a nonzero leverage factor of at most 5.`);
+        return;
+      }
+      const issue = inputs.map((entry) => dailyBarsIssue(spec, entry!, marketResolution)).find(Boolean);
+      if (issue) {
+        warnings.push(issue);
+        return;
+      }
+      const outputs = spec.kind === "leverage"
+        ? resolveLeverageLine(spec, index, color, anchors?.get(index.id))
+        : resolveLeverageDecay(spec, input, index, anchors);
+      if (outputs.every((output) => output.points.length < 2)) {
+        warnings.push(`${studyMessageName(spec)}: not enough shared daily closes to measure ${leverageFactorLabel(spec.parameters.factor as number)} daily ${leverageSymbol(index)}.`);
+      }
+      resolved.push(...outputs);
+      return;
+    }
     if (spec.kind === "realized-vol") {
       const window = spec.parameters.window ?? 30;
       if (typeof window !== "number" || !Number.isInteger(window) || window < 2
         || (spec.parameters.estimator !== undefined && !isRealizedVolatilityEstimator(spec.parameters.estimator))) {
-        errors.push(`${spec.id}: choose a supported volatility estimator and a whole window of at least two sessions.`);
+        errors.push(`${studyMessageName(spec)}: choose a supported volatility estimator and a whole window of at least two sessions.`);
         return;
       }
       const inputResolution = input.historyResolution === undefined ? marketResolution : input.historyResolution;
@@ -1253,17 +1350,17 @@ function resolveStudySpecs(
         || (inputResolution !== undefined && inputResolution !== "1d")
         || (input.timeBasis?.cadenceMs !== undefined && input.timeBasis.cadenceMs !== 86_400_000)
         || !(input.unitGroup === "price" || input.unitGroup.startsWith("price:"))) {
-        errors.push(`${spec.id}: realized volatility requires daily prices. Choose Auto or 1D resolution and a daily price source.`);
+        errors.push(`${studyMessageName(spec)}: realized volatility requires daily prices. Choose Auto or 1D resolution and a daily price source.`);
         return;
       }
       const cadenceIssue = realizedVolatilityCadenceIssue(input.points);
       if (cadenceIssue) {
-        errors.push(`${spec.id}: ${cadenceIssue}`);
+        errors.push(`${studyMessageName(spec)}: ${cadenceIssue}`);
         return;
       }
       const outputs = resolveRealizedVolatility(spec, input, color);
       if (outputs.every((output) => output.points.every((point) => point.value === null))) {
-        warnings.push(`${spec.id}: not enough valid daily history to calculate ${spec.parameters.estimator ?? "close-to-close"} realized volatility.`);
+        warnings.push(`${studyMessageName(spec)}: not enough valid daily history to calculate ${spec.parameters.estimator ?? "close-to-close"} realized volatility.`);
       }
       resolved.push(...outputs);
       return;
@@ -1307,11 +1404,11 @@ function resolveStudySpecs(
         && inputCurrency !== pairedCurrency;
       if (spec.kind === "ratio" && differentCurrencies) {
         warnings.push(
-          `${spec.id}: ${spec.kind} inputs use different currencies (${inputCurrency} and ${pairedCurrency}); raw values are not FX-converted.`,
+          `${studyMessageName(spec)}: ${spec.kind} inputs use different currencies (${inputCurrency} and ${pairedCurrency}); raw values are not FX-converted.`,
         );
       }
       if (spec.kind === "correlation" && input.nativeFrequency !== pairedInput.nativeFrequency) {
-        warnings.push(`${spec.id}: correlation mixes ${input.nativeFrequency} and ${pairedInput.nativeFrequency} observations; only matching observation times contribute.`);
+        warnings.push(`${studyMessageName(spec)}: correlation mixes ${input.nativeFrequency} and ${pairedInput.nativeFrequency} observations; only matching observation times contribute.`);
       }
       outputs = resolvePairStudy(spec, input, pairedInput, color);
     }
@@ -1319,7 +1416,7 @@ function resolveStudySpecs(
       spec.kind !== "volume"
       && (outputs.length === 0 || outputs.every((output) => output.points.length === 0))
     ) {
-      warnings.push(`${spec.id}: not enough valid history to calculate ${spec.kind}.`);
+      warnings.push(`${studyMessageName(spec)}: not enough valid history to calculate ${spec.kind}.`);
     }
     resolved.push(...outputs);
   });

package/src/time-series/tail-reconcile.ts

@@ -0,0 +1,121 @@
+import { logFailure } from "../utils/log-failure";
+import { fetchHistoryResult } from "../sources/history-result";
+import type { PriceHistoryResult } from "../types/price-history";
+import { CHART_RESOLUTION_STEP_MS } from "./resolution";
+import type { DataProvider } from "../types/data-provider";
+import type { TickerFinancials } from "../types/financials";
+import { getPricePointTimestamp } from "../utils/price-history";
+import { type ChartResolveSources, type ChartResolveCache, requestContext } from "./resolve-context";
+import { DAY_MS } from "./chart-bounds";
+import { priceHistoryAcquisitionIdentity, priceHistoryTailAcquisition, priceHistoryWindowsAgree, mergePriceHistoryWindows } from "./history-acquisition";
+
+/** Recent-window requests for the same history, shared by every chart asking at once. */
+const tailRequestsInFlight = new WeakMap<DataProvider, Map<string, Promise<PriceHistoryResult | null>>>();
+
+/** Older tails are left to a full history refresh rather than a recent-window request. */
+const MAX_TAIL_RECONCILE_LAG_MS = 3 * DAY_MS;
+
+function latestObservationTime(points: TickerFinancials["priceHistory"]): number {
+  for (let index = points.length - 1; index >= 0; index -= 1) {
+    const point = points[index]!;
+    const time = getPricePointTimestamp(point);
+    if (Number.isFinite(time) && Number.isFinite(point.close)) return time;
+  }
+  return Number.NaN;
+}
+
+function samePricePoints(left: TickerFinancials["priceHistory"], right: TickerFinancials["priceHistory"]): boolean {
+  if (left.length !== right.length) return false;
+  for (let index = left.length - 1; index >= 0; index -= 1) {
+    const a = left[index]!;
+    const b = right[index]!;
+    if (a === b) continue;
+    if (getPricePointTimestamp(a) !== getPricePointTimestamp(b) || a.open !== b.open || a.high !== b.high
+      || a.low !== b.low || a.close !== b.close || a.volume !== b.volume) return false;
+  }
+  return true;
+}
+
+/**
+ * Refreshes the newest bars of each intraday history the last resolve plotted
+ * up to the present, so bars formed from quotes settle to the provider's
+ * version shortly after they close. Only the recent window is requested, and a
+ * window from a different source or session contract is never mixed in.
+ * Resolves true when any plotted bar changed.
+ */
+export function reconcileChartTail(
+  sources: Pick<ChartResolveSources, "dataProvider">,
+  cache: ChartResolveCache,
+  now = Date.now(),
+): Promise<boolean> {
+  if (cache.tailReconcile) return cache.tailReconcile;
+  const provider = sources.dataProvider;
+  if (!provider || cache.liveTails.size === 0
+    || !(provider.getDetailedPriceHistoryWithMetadata || provider.getDetailedPriceHistory)) {
+    return Promise.resolve(false);
+  }
+  const run: Promise<boolean> = Promise.all([...cache.liveTails].map(async ([key, tail]) => {
+    const pending = cache.priceHistoryByRequest.get(key);
+    const loaded = pending ? await pending.catch(() => {
+      // Intentional ignore: resolveChartSpecPass already includes this history failure in the series errors.
+      return null;
+    }) : null;
+    if (!pending || !loaded || loaded.resolution !== tail.resolution) return false;
+    const accumulated = cache.accumulatedPriceHistory.get(tail.accumulationKey);
+    const latest = latestObservationTime(accumulated?.points ?? loaded.points);
+    if (!Number.isFinite(latest) || now - latest > MAX_TAIL_RECONCILE_LAG_MS) return false;
+    // The newest loaded bar may still have been forming when it was fetched.
+    // Whole-bar starts and whole-minute ends let every chart of this history
+    // that asks at the same boundary share one request and one cached window.
+    const step = CHART_RESOLUTION_STEP_MS[tail.resolution];
+    const start = Math.floor((latest - step) / step) * step;
+    const end = Math.ceil(now / 60_000) * 60_000;
+    const { symbol, exchange } = tail.source.instrument;
+    const context = { ...requestContext(tail.source), ...(tail.historySession ? { historySession: tail.historySession } : {}) };
+    const requestKey = JSON.stringify([symbol, exchange ?? "", context.brokerId ?? null,
+      context.brokerInstanceId ?? null, context.instrument ?? null, tail.resolution, start, end, tail.historySession ?? null]);
+    const shared = tailRequestsInFlight.get(provider) ?? new Map<string, Promise<PriceHistoryResult | null>>();
+    tailRequestsInFlight.set(provider, shared);
+    let request = shared.get(requestKey);
+    if (!request) {
+      const fetched = fetchHistoryResult(provider, symbol, exchange ?? "",
+        { kind: "detail", start: new Date(start), end: new Date(end), interval: tail.resolution }, context)
+        .catch(logFailure("time-series-resolve", "Could not reconcile chart history", null))
+        .finally(() => {
+          if (shared.get(requestKey) === fetched) shared.delete(requestKey);
+        });
+      shared.set(requestKey, fetched);
+      request = fetched;
+    }
+    const result = await request;
+    if (!result || result.resolution !== loaded.resolution || !!result.extendedHours !== !!loaded.extendedHours
+      || priceHistoryAcquisitionIdentity(result) !== priceHistoryAcquisitionIdentity(loaded)) return false;
+    const points = result.points.filter((point) => {
+      const time = getPricePointTimestamp(point);
+      return Number.isFinite(time) && time >= start && Number.isFinite(point.close);
+    });
+    // A full refetch that landed meanwhile supersedes this window.
+    if (points.length === 0 || cache.priceHistoryByRequest.get(key) !== pending) return false;
+    // A tail on another split basis (a split since the window was loaded) is not drawn beside it:
+    // the window stays as loaded, on one basis, until it is refetched whole.
+    if (!priceHistoryWindowsAgree(loaded.points, points, tail.resolution)) return false;
+    const refreshed = mergePriceHistoryWindows(loaded.points, points, tail.resolution);
+    if (samePricePoints(refreshed, loaded.points)) return false;
+    const acquisition = priceHistoryTailAcquisition(loaded, result);
+    // The merged bars are as current as the newer acquisition says.
+    cache.priceHistoryByRequest.set(key, Promise.resolve({ ...loaded, points: refreshed,
+      session: acquisition.session, sourceKey: acquisition.sourceKey, savedCopyBehind: acquisition.savedCopyBehind }));
+    if (accumulated) {
+      const accumulatedAcquisition = priceHistoryTailAcquisition(accumulated, result);
+      cache.accumulatedPriceHistory.set(tail.accumulationKey, { ...accumulated,
+        points: mergePriceHistoryWindows(accumulated.points, points, tail.resolution),
+        session: accumulatedAcquisition.session, sourceKey: accumulatedAcquisition.sourceKey });
+    }
+    cache.revision += 1;
+    return true;
+  })).then((changes) => changes.some(Boolean)).finally(() => {
+    if (cache.tailReconcile === run) cache.tailReconcile = null;
+  });
+  cache.tailReconcile = run;
+  return run;
+}