gloomberb 0.13.2 → 0.14.0

package/src/time-series/spec-studies.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 import { getTimeSeriesField } from "./field-catalog";
 import { normalizeChartSpec, validateChartSpec } from "./spec";
 import { maxStudyWarmupPoints, resolveStudies } from "./studies";
+import { applyResolvedSeriesTransform } from "./transforms";
 import type { ChartStudySpec, ResolvedSeries, TimeSeriesPoint } from "./types";
 
 function resolved(id: string, multiplier = 1): ResolvedSeries {
@@ -22,6 +23,7 @@ function resolved(id: string, multiplier = 1): ResolvedSeries {
     color: "#fff",
     unit: "USD/share",
     unitGroup: "price",
+    volumeUnit: "shares",
     nativeFrequency: "daily",
     dataShape: "ohlcv",
     style: "line",
@@ -381,14 +383,60 @@ describe("study resolution", () => {
     });
     expect(result.series.find(({ id }) => id === "spread")?.points).toHaveLength(5);
     const correlation = result.series.find(({ id }) => id === "correlation")?.points ?? [];
-    expect(correlation).toHaveLength(3);
-    expect(correlation.every((entry) => Math.abs((entry.value ?? 0) - 0.5) < 1e-10)).toBe(true);
+    expect(correlation).toHaveLength(0);
+    expect(result.warnings).toContain("correlation: not enough valid history to calculate correlation.");
     expect(result.series.find(({ id }) => id === "correlation")).toMatchObject({
       style: "line",
       interpolation: "none",
     });
   });
 
+  test("correlates returns over shared observations without inventing closed-market zero returns", () => {
+    const series = (id: string, rows: Array<[string, number | null]>): ResolvedSeries => ({
+      ...resolved(id),
+      points: rows.map(([day, value]) => ({ date: new Date(day), observedAt: new Date(day), value })),
+    });
+    // Stock closes Friday, then Tuesday after a holiday. Crypto also trades
+    // throughout the weekend. Both have identical returns on common dates.
+    const stock = series("stock", [["2026-09-04", 100], ["2026-09-08", 110], ["2026-09-09", 99], ["2026-09-10", 118.8]]);
+    const crypto = series("crypto", [["2026-09-04", 1000], ["2026-09-05", 2000], ["2026-09-06", 500], ["2026-09-07", 1500], ["2026-09-08", 1100], ["2026-09-09", 990], ["2026-09-10", 1188]]);
+    const result = resolveStudies([stock, crypto], [study("corr", "correlation", ["stock", "crypto"], { period: 3 })]);
+    const points = result.series[0]!.points;
+    expect(points).toHaveLength(1);
+    expect(points[0]!.date.toISOString().slice(0, 10)).toBe("2026-09-10");
+    expect(points[0]!.value).toBeCloseTo(1, 12);
+
+    // A missing stock observation cannot be replaced by its previous close.
+    stock.points.splice(1, 0, { date: new Date("2026-09-07"), observedAt: new Date("2026-09-07"), value: null });
+    expect(resolveStudies([stock, crypto], [study("corr", "correlation", ["stock", "crypto"], { period: 3 })]).series[0]!.points).toEqual(points);
+  });
+
+  test("correlation waits for matching publication times instead of pairing equal observation dates", () => {
+    const left = resolved("left");
+    left.points = left.points.slice(0, 3);
+    const right = { ...resolved("right", 2), points: left.points.map((point) => ({
+      ...point, value: point.value! * 2,
+      availableAt: new Date(point.date.getTime() + 12 * 60 * 60_000),
+    })) };
+    const calculation = study("corr", "correlation", ["left", "right"], { period: 2 });
+    expect(resolveStudies([left, right], [calculation]).series[0]!.points).toHaveLength(0);
+    left.points = left.points.map((point) => ({ ...point, availableAt: new Date(point.date.getTime() + 12 * 60 * 60_000) }));
+    const [point] = resolveStudies([left, right], [calculation]).series[0]!.points;
+    expect(point?.date).toEqual(new Date("2024-01-03T12:00:00Z"));
+    expect(point?.availableAt).toEqual(point?.date);
+    expect(point?.value).toBeCloseTo(1, 12);
+  });
+
+  test("volume studies preserve known instrument units and disclose unspecified provider volume", () => {
+    for (const volumeUnit of ["shares", "contracts", undefined] as const) {
+      const input = { ...resolved("volume-input"), volumeUnit };
+      const result = resolveStudies([input], [study("volume", "volume", [input.id])]);
+      expect(result.series[0]?.unit).toBe(volumeUnit ?? "");
+      expect(result.series[0]?.points.map((point) => point.value)).toEqual(input.points.map((point) => point.volume));
+      expect(result.warnings).toEqual(volumeUnit ? [] : ["Volume unit unknown: VOLUME-INPUT."]);
+    }
+  });
+
   test("returns actionable errors for missing inputs instead of throwing", () => {
     const result = resolveStudies([resolved("a")], [study("ratio", "ratio", ["a", "missing"])]);
     expect(result.series).toEqual([]);
@@ -410,7 +458,7 @@ describe("study resolution", () => {
     expect(result.series[0]?.points.every(({ value }) => value === 0.5)).toBe(true);
   });
 
-  test("warns when raw pair formulas mix currencies without FX conversion", () => {
+  test("rejects a foreign-currency spread while preserving the ratio's derived units and warning", () => {
     const usd = { ...resolved("usd"), unit: "USD/share", unitGroup: "price:USD" };
     const jpy = { ...resolved("jpy"), unit: "JPY/share", unitGroup: "price:JPY" };
     const result = resolveStudies([usd, jpy], [
@@ -420,8 +468,9 @@ describe("study resolution", () => {
 
     expect(result.warnings).toEqual([
       "ratio: ratio inputs use different currencies (USD and JPY); raw values are not FX-converted.",
-      "spread: spread inputs use different currencies (USD and JPY); raw values are not FX-converted.",
     ]);
+    expect(result.errors).toEqual([expect.stringContaining("spread: spread cannot subtract JPY (JPY/share) from USD (USD/share)")]);
+    expect(result.series.find(({ id }) => id === "spread")).toBeUndefined();
     expect(result.series.find(({ id }) => id === "ratio")).toMatchObject({
       unit: "USD/JPY",
       unitGroup: "derived-unit:usd/jpy",
@@ -435,8 +484,130 @@ describe("study resolution", () => {
       study("spread", "spread", ["price", "revenue"]),
     ]);
 
-    expect(result.warnings).toEqual([
-      "spread: spread cannot subtract USD from USD/share; choose inputs with matching units.",
+    expect(result.warnings).toEqual([]);
+    expect(result.errors).toEqual([expect.stringContaining("spread: spread cannot subtract REVENUE (USD) from PRICE (USD/share)")]);
+    expect(result.series).toEqual([]);
+  });
+
+  test.each([
+    ["unknown peer currency", "USD/share", "price:USD", "currency/share", "price", false],
+    ["two unknown currencies", "currency/share", "price", "currency/share", "price", false],
+    ["blank units", "", "unknown", "", "unknown", false],
+    ["placeholder units", "unknown", "unknown", "unknown", "unknown", false],
+    ["untyped scalar unit", "unit", "unknown", "unit", "unknown", false],
+    ["unspecified price versus total", "USD", "price:USD", "USD", "currency-total:USD", false],
+    ["two unspecified price bases", "USD", "price:USD", "USD", "price:USD", false],
+    ["trailing price denominator", "USD/", "price:USD", "USD/", "price:USD", false],
+    ["blank price denominator", "USD/   ", "price:USD", "USD/   ", "price:USD", false],
+    ["empty compound price denominator", "USD//barrel", "price:USD", "USD//barrel", "price:USD", false],
+    ["placeholder price denominator", "USD/?", "price:USD", "USD/?", "price:USD", false],
+    ["explicit common physical basis", "USD/barrel", "price:USD", "USD/barrel", "price:USD", true],
+    ["different physical bases", "USD/barrel", "price:USD", "USD/gallon", "price:USD", false],
+    ["physical basis with conflicting currency metadata", "USD/barrel", "price:EUR", "USD/barrel", "price:EUR", false],
+    ["same totals", "USD", "currency-total:USD", "USD", "currency-total:USD", true],
+    ["price versus EPS", "USD/share", "price:USD", "USD/share", "per-share:USD", true],
+    ["known crypto units", "USD/unit", "price:USD", "USD/unit", "price:USD", true],
+    ["explicit common currency", "USD/share", "price:USD", "USD/share", "price:USD", true],
+    ["pounds versus pence", "GBP/share", "price:GBP", "GBp/share", "price:GBp", false],
+    ["equivalent pence symbols", "GBp/share", "price:GBp", "GBX/share", "price:GBX", true],
+    ["same FX units", "USD/EUR", "derived-unit:usd/eur", "USD/EUR", "derived-unit:usd/eur", true],
+    ["inverted FX units", "USD/EUR", "derived-unit:usd/eur", "EUR/USD", "derived-unit:eur/usd", false],
+    ["rate percentages", "%", "percent", "%", "percent", true],
+  ] as const)("checks spread units independently of ratio/correlation: %s", (_label, leftUnit, leftGroup, rightUnit, rightGroup, available) => {
+    const inputs = [
+      { ...resolved("left"), unit: leftUnit, unitGroup: leftGroup },
+      { ...resolved("right", 2), unit: rightUnit, unitGroup: rightGroup },
+    ];
+    const others = [study("ratio", "ratio", ["left", "right"]), study("correlation", "correlation", ["left", "right"], { period: 3 })]
+      .map((spec) => ({ ...spec, color: "#fff" }));
+    const result = resolveStudies(inputs, [study("spread", "spread", ["left", "right"]), ...others]);
+    expect(result.series.filter(({ id }) => id !== "spread")).toEqual(resolveStudies(inputs, others).series);
+    expect(result.series.some(({ id }) => id === "spread")).toBe(available);
+    expect(result.errors.length).toBe(available ? 0 : 1);
+  });
+
+  test("uses actual normalized input units and ignores their original currency provenance", () => {
+    const usd = { ...resolved("usd"), unitGroup: "price:USD" };
+    const eur = { ...resolved("eur", 2), unit: "EUR/share", unitGroup: "price:EUR" };
+    for (const transform of ["percent", "index100"] as const) {
+      const result = resolveStudies([usd, eur].map((input) => applyResolvedSeriesTransform(input, transform)), [study("spread", "spread", ["usd", "eur"])]);
+      expect(result.errors).toEqual([]);
+      expect(result.series[0]?.points.every(({ value }) => value === 0)).toBe(true);
+    }
+  });
+
+  test("rejects incompatible spread metadata before empty or interrupted history can bypass it", () => {
+    const left = resolved("left");
+    const right = { ...resolved("right", 2), unit: "EUR/share", unitGroup: "price:EUR" };
+    left.points[1] = { ...left.points[1]!, value: null, close: undefined, provenance: { priceHistoryIntegrity: {
+      reason: "inconsistent-ohlc", sourcePoints: [{ date: left.points[1]!.date.toISOString(), open: 2, high: 1, low: 0, close: 2 }],
+    } } };
+    for (const inputs of [[left, right], [left, right].map((input) => ({ ...input, points: [] }))]) {
+      const result = resolveStudies(inputs, [study("spread", "spread", ["left", "right"])]);
+      expect(result.series).toEqual([]);
+      expect(result.errors).toHaveLength(1);
+      expect(result.errors[0]).toContain("spread: spread cannot subtract");
+    }
+  });
+
+  test("a multiplier cannot establish missing physical price units even across interrupted history", () => {
+    const inputs = ["left", "right"].map((id) => ({ ...resolved(id), unit: "USD", unitGroup: "price:USD", priceAssetCategory: "FUTURE" }));
+    inputs[0]!.points[1] = { ...inputs[0]!.points[1]!, value: null, close: undefined };
+    for (const multiplier of [1, 42]) {
+      const result = resolveStudies(inputs, [study("spread", "spread", ["left", "right"], { multiplier })]);
+      expect(result.series).toEqual([]);
+      expect(result.errors).toHaveLength(1);
+    }
+  });
+
+  test.each([
+    ["missing price basis", "USD", "price:USD", "USD", "price:USD", "unknown"],
+    ["blank denominator", "USD/", "price:USD", "USD/", "price:USD", "unknown"],
+    ["placeholder denominator", "USD/-", "price:USD", "USD/?", "price:USD", "unknown"],
+    ["conflicting currency metadata", "USD/share", "price:EUR", "USD/share", "price:EUR", "unknown"],
+    ["explicit same physical basis", "USD/barrel", "price:USD", "USD/barrel", "price:USD", "x"],
+    ["explicit different physical bases", "USD/barrel", "price:USD", "USD/gallon", "price:USD", "gallon/barrel"],
+    ["same currency totals", "USD", "currency-total:USD", "USD", "currency-total:USD", "x"],
+    ["currency scales", "GBP/share", "price:GBP", "GBp/share", "price:GBp", "GBP/GBp"],
+    ["pence aliases", "GBp/share", "price:GBp", "GBX/share", "price:GBX", "x"],
+    ["currency and share aliases", "usd/shares", "price:USD", "USD/share", "price:USD", "x"],
+  ] as const)("retains ratio values with verified unit factors: %s", (_label, leftUnit, leftGroup, rightUnit, rightGroup, expected) => {
+    const inputs = [
+      { ...resolved("left"), unit: leftUnit, unitGroup: leftGroup },
+      { ...resolved("right", 2), unit: rightUnit, unitGroup: rightGroup },
+    ];
+    inputs[1]!.points[1] = { ...inputs[1]!.points[1]!, value: 0, close: 0 };
+    const result = resolveStudies(inputs, [study("ratio", "ratio", ["left", "right"])]);
+    expect(result.errors).toEqual([]);
+    expect(result.series[0]?.unit).toBe(expected);
+    expect(result.series[0]?.points[1]?.value).toBeNull();
+    expect(result.series[0]?.points.filter((_, index) => index !== 1).every(({ value }) => value === 0.5)).toBe(true);
+  });
+
+  test("unknown ratio units remain unknown through nested ratios and cannot establish a spread", () => {
+    const inputs = ["left", "right"].map((id) => ({ ...resolved(id), unit: "USD", unitGroup: "price:USD" }));
+    const first = resolveStudies(inputs, [study("ratio", "ratio", ["left", "right"])]);
+    const nested = resolveStudies(first.series, [study("nested", "ratio", ["ratio", "ratio"])]);
+    const combined = [...first.series, ...nested.series];
+    const spread = resolveStudies(combined, [study("spread", "spread", ["nested", "ratio"])]);
+    expect(combined.map(({ id, unit, unitGroup }) => ({ id, unit, unitGroup }))).toEqual([
+      { id: "ratio", unit: "unknown", unitGroup: "derived-unit:unknown" },
+      { id: "nested", unit: "unknown", unitGroup: "derived-unit:unknown" },
+    ]);
+    expect(combined.every(({ points }) => points.every(({ value }) => value === 1))).toBe(true);
+    expect(spread.errors).toEqual([expect.stringContaining("spread cannot subtract")]);
+  });
+
+  test("ratio axis groups distinguish opposite currency scales while retaining equivalent aliases", () => {
+    const inputs = ["GBP", "GBp", "GBX"].map((currency) => ({ ...resolved(currency), unit: `${currency}/share`, unitGroup: `price:${currency}` }));
+    const result = resolveStudies(inputs, [
+      study("up", "ratio", ["GBP", "GBp"]),
+      study("down", "ratio", ["GBp", "GBP"]),
+      study("alias", "ratio", ["GBP", "GBX"]),
     ]);
+    expect(result.series.map(({ unit }) => unit)).toEqual(["GBP/GBp", "GBp/GBP", "GBP/GBX"]);
+    expect(result.series[0]!.unitGroup).not.toBe(result.series[1]!.unitGroup);
+    expect(result.series[0]!.unitGroup).toBe(result.series[2]!.unitGroup);
+    expect(result.series.every(({ points }) => points.every(({ value }) => value === 1))).toBe(true);
   });
 });

package/src/time-series/studies.ts

@@ -1,4 +1,6 @@
-import { alignTimeSeries, scalarPointValue } from "./alignment";
+import { alignTimeSeries, effectiveTimeSeriesPointTime, scalarPointValue } from "./alignment";
+import { mergePriceHistoryIntegrity } from "../utils/price-history-integrity";
+import { resolveCurrencyUnit } from "../utils/currency-units";
 import type {
   ChartStudyKind,
   ChartStudySpec,
@@ -81,6 +83,8 @@ function outputSeries(
     color: options.color,
     unit: options.unit ?? input.unit,
     unitGroup: options.unitGroup ?? input.unitGroup,
+    priceAssetCategory: (options.unit ?? input.unit) === input.unit
+      && (options.unitGroup ?? input.unitGroup) === input.unitGroup ? input.priceAssetCategory : undefined,
     nativeFrequency: options.nativeFrequency ?? input.nativeFrequency,
     dataShape: "scalar",
     style: options.style ?? "line",
@@ -89,6 +93,7 @@ function outputSeries(
     panelId: spec.panelId,
     interpolation: options.interpolation ?? "none",
     timeBasis: input.timeBasis,
+    observationKind: input.observationKind,
     points: options.points,
   };
 }
@@ -306,7 +311,7 @@ function resolveVolume(spec: ChartStudySpec, input: ResolvedSeries, color: strin
     label: `Volume ${input.label}`,
     points,
     color,
-    unit: "shares",
+    unit: input.volumeUnit ?? "",
     unitGroup: "volume",
     style: "columns",
     axis: "left",
@@ -319,11 +324,6 @@ interface PairedSample {
   right: number;
 }
 
-interface SeriesUnit {
-  currency: string | null;
-  dimension: string;
-}
-
 function seriesCurrency(series: ResolvedSeries): string | null {
   const grouped = series.unitGroup.match(/:([A-Z]{3})$/i)?.[1];
   if (grouped) return grouped.toUpperCase();
@@ -331,15 +331,33 @@ function seriesCurrency(series: ResolvedSeries): string | null {
   return series.unit.match(/^([A-Z]{3})(?:$|\/)/i)?.[1]?.toUpperCase() ?? null;
 }
 
-function seriesUnit(series: ResolvedSeries): SeriesUnit {
-  const currency = seriesCurrency(series);
+function unitFactorIdentity(value: string): string {
+  const token = value.trim();
+  if (/^[A-Za-z]{3}$/.test(token)) {
+    const { currency, divisor } = resolveCurrencyUnit(token);
+    return `${currency}:${divisor}`;
+  }
+  return token.toLowerCase().replace(/^shares$/, "share");
+}
+
+function knownUnitSignature(series: ResolvedSeries): string | null {
   const unit = series.unit.trim();
-  return {
-    currency,
-    dimension: currency && unit.toUpperCase().startsWith(currency)
-      ? `currency${unit.slice(currency.length).toLowerCase()}`
-      : unit.toLowerCase(),
-  };
+  if (!unit || /(?:^|\W)(?:currency|unknown|unspecified|n\/a)(?:$|\W)/i.test(unit)
+    || /^(?:units?|[-?]+)$/i.test(unit)) return null;
+  if (unit.split("/").some((part) => !part.trim() || /^[-?]+$/.test(part.trim()))) return null;
+
+  const monetary = series.unitGroup.match(/^(price|currency-total|per-share)(?::([^:]+))?$/);
+  const currency = unit.match(/^([A-Za-z]{3})(?:$|\/)/)?.[1];
+  if (monetary && (!currency || (monetary[2] && unitFactorIdentity(monetary[2]) !== unitFactorIdentity(currency)))) return null;
+
+  // Currency alone does not establish a price's physical/share basis. A scalar
+  // multiplier cannot establish it either. Explicit USD/share price and EPS
+  // units, however, match despite different groups.
+  if (monetary?.[1] === "price" && !unit.includes("/")) return null;
+  const basis = monetary && !unit.includes("/") ? monetary[1] : "";
+  // Keep currency scale and compound order: GBp/GBX are pence, not pounds;
+  // USD/EUR cannot subtract EUR/USD.
+  return `${basis ?? ""}|${unit.split("/").map(unitFactorIdentity).join("/")}`;
 }
 
 function unitFactors(unit: string): { numerator: string[]; denominator: string[] } {
@@ -359,13 +377,16 @@ function ratioUnit(left: ResolvedSeries, right: ResolvedSeries): {
   unit: string;
   unitGroup: string;
 } {
+  if (!knownUnitSignature(left) || !knownUnitSignature(right)) {
+    return { unit: "unknown", unitGroup: "derived-unit:unknown" };
+  }
   const leftFactors = unitFactors(left.unit);
   const rightFactors = unitFactors(right.unit);
   const numerator = [...leftFactors.numerator, ...rightFactors.denominator];
   const denominator = [...leftFactors.denominator, ...rightFactors.numerator];
   for (let index = numerator.length - 1; index >= 0; index -= 1) {
     const match = denominator.findIndex((factor) => (
-      factor.toLowerCase() === numerator[index]!.toLowerCase()
+      unitFactorIdentity(factor) === unitFactorIdentity(numerator[index]!)
     ));
     if (match < 0) continue;
     numerator.splice(index, 1);
@@ -374,19 +395,27 @@ function ratioUnit(left: ResolvedSeries, right: ResolvedSeries): {
   const unit = denominator.length === 0
     ? numerator.join("·") || "x"
     : `${numerator.join("·") || "1"}/${denominator.join("·")}`;
+  const groupFactor = (value: string) => {
+    const identity = unitFactorIdentity(value);
+    return (/^[A-Za-z]{3}$/.test(value.trim()) ? identity.replace(/:1$/, "") : identity).toLowerCase();
+  };
+  const groupNumerator = numerator.map(groupFactor).join("·");
+  const groupDenominator = denominator.map(groupFactor).join("·");
+  const group = groupDenominator ? `${groupNumerator || "1"}/${groupDenominator}` : groupNumerator;
   return {
     unit,
-    unitGroup: unit === "x" ? "ratio" : `derived-unit:${unit.toLowerCase()}`,
+    unitGroup: unit === "x" ? "ratio" : `derived-unit:${group}`,
   };
 }
 
-function pairedSamples(left: ResolvedSeries, right: ResolvedSeries): PairedSample[] {
+function pairedSamples(left: ResolvedSeries, right: ResolvedSeries, carryForward: boolean): PairedSample[] {
   return alignTimeSeries([left, right], {
     mode: "intersection",
-    // Formula inputs are point-in-time values, regardless of how either
-    // source is drawn. Carry only the latest publicly available observation;
-    // alignTimeSeries still gates every value by availableAt.
-    carryForward: true,
+    // Ratios/spreads compare latest known levels; correlations need actual
+    // shared observations before calculating returns. Carrying a closed market
+    // invents zero returns and mismatches both sides of a weekend/holiday move.
+    // Both modes still respect the publication time of each observation.
+    carryForward,
   }).flatMap((row) => {
     const leftValue = row.values[left.id];
     const rightValue = row.values[right.id];
@@ -419,7 +448,7 @@ function resolvePairStudy(
   right: ResolvedSeries,
   color: string,
 ): ResolvedSeries[] {
-  const paired = pairedSamples(left, right);
+  const paired = pairedSamples(left, right, spec.kind !== "correlation");
   if (spec.kind === "ratio" || spec.kind === "spread") {
     const multiplier = finiteNumber(spec.parameters.multiplier) ? spec.parameters.multiplier : 1;
     const points = paired.map((sample) => derivedPoint(
@@ -479,7 +508,7 @@ function resolvePairStudy(
       rightVariance += rightDelta ** 2;
     }
     const denominator = Math.sqrt(leftVariance * rightVariance);
-    const value = denominator === 0 ? null : covariance / denominator;
+    const value = denominator === 0 ? null : Math.max(-1, Math.min(1, covariance / denominator));
     points.push(derivedPoint({ point: values[index]!.point, value: values[index]!.left }, value));
   }
   return [outputSeries(spec, left, {
@@ -497,6 +526,97 @@ function requiredInputs(kind: ChartStudyKind): number {
   return kind === "ratio" || kind === "spread" || kind === "correlation" ? 2 : 1;
 }
 
+/**
+ * A contradictory observation interrupts the input history. Running studies on
+ * each continuous segment keeps finite windows from skipping the missing bar
+ * and makes recursive indicators warm up again from valid observations.
+ */
+function resolveInterruptedStudy(
+  inputs: readonly ResolvedSeries[],
+  spec: ChartStudySpec,
+): StudyResolutionResult | null {
+  const gaps = new Map<number, TimeSeriesPoint>();
+  for (const input of inputs) {
+    for (const point of input.points) {
+      const integrity = point.provenance?.priceHistoryIntegrity;
+      const priceIssues = point.provenance?.valuationPriceIssues;
+      if (!integrity && !priceIssues?.length) continue;
+      const timestamp = effectiveTimeSeriesPointTime(point);
+      const previous = gaps.get(timestamp)?.provenance;
+      gaps.set(timestamp, {
+        date: new Date(timestamp), observedAt: new Date(timestamp), value: null,
+        provenance: {
+          quality: "derived",
+          ...(integrity || previous?.priceHistoryIntegrity ? { priceHistoryIntegrity: previous?.priceHistoryIntegrity && integrity
+            ? mergePriceHistoryIntegrity(previous.priceHistoryIntegrity, integrity) : integrity ?? previous?.priceHistoryIntegrity } : {}),
+          ...(priceIssues?.length || previous?.valuationPriceIssues?.length
+            ? { valuationPriceIssues: [...(previous?.valuationPriceIssues ?? []), ...(priceIssues ?? [])] } : {}),
+        },
+      });
+    }
+  }
+  if (!gaps.size) return null;
+  const times = [...gaps.keys()].sort((left, right) => left - right);
+  const outputs = new Map<string, ResolvedSeries>();
+  const warnings = new Set<string>();
+  const errors = new Set<string>();
+  const cursors = inputs.map((input) => ({
+    input,
+    points: [...input.points].sort((left, right) => effectiveTimeSeriesPointTime(left) - effectiveTimeSeriesPointTime(right)),
+    index: 0,
+    previous: undefined as TimeSeriesPoint | undefined,
+  }));
+  let start = Number.NEGATIVE_INFINITY;
+  for (const end of [...times, Number.POSITIVE_INFINITY]) {
+    const segmentInputs = cursors.map((cursor) => {
+      while (cursor.index < cursor.points.length && effectiveTimeSeriesPointTime(cursor.points[cursor.index]!) <= start) {
+        cursor.previous = cursor.points[cursor.index++];
+      }
+      const previous = cursor.previous;
+      const points: TimeSeriesPoint[] = [];
+      while (cursor.index < cursor.points.length && effectiveTimeSeriesPointTime(cursor.points[cursor.index]!) < end) {
+        const point = cursor.points[cursor.index++]!;
+        points.push(point);
+        cursor.previous = point;
+      }
+      // A valid unaffected peer remains usable for as-of ratio/spread levels.
+      // Correlations instead restart their shared observations and returns.
+      if (spec.kind === "ratio" || spec.kind === "spread") {
+        if (previous && !previous.provenance?.priceHistoryIntegrity && !previous.provenance?.valuationPriceIssues?.length) points.unshift(previous);
+      }
+      return { ...cursor.input, points };
+    });
+    const segment = resolveStudies(segmentInputs, [spec]);
+    for (const output of segment.series) {
+      const points = output.points.filter((point) => effectiveTimeSeriesPointTime(point) > start);
+      const gap = gaps.get(start);
+      if (gap && spec.kind !== "ratio" && spec.kind !== "spread" && spec.kind !== "volume") {
+        // A gap just outside the visible window still invalidates the next
+        // warmup observations. Keep those nulls and their original diagnostic
+        // explicit so clipping cannot hide why a study is unavailable.
+        const firstComputed = points[0] ? effectiveTimeSeriesPointTime(points[0]) : Number.POSITIVE_INFINITY;
+        points.unshift(...segmentInputs[0]!.points.filter((point) => effectiveTimeSeriesPointTime(point) < firstComputed).map((point) => ({
+          date: new Date(point.date), observedAt: new Date(point.observedAt),
+          availableAt: point.availableAt ? new Date(point.availableAt) : undefined,
+          value: null, provenance: gap.provenance,
+        })));
+      }
+      const previous = outputs.get(output.id);
+      outputs.set(output.id, { ...output, points: [...(previous?.points ?? []), ...points] });
+    }
+    for (const warning of segment.warnings) {
+      if (!warning.includes("not enough valid history")) warnings.add(warning);
+    }
+    for (const error of segment.errors) errors.add(error);
+    start = end;
+  }
+  for (const output of outputs.values()) {
+    output.points.push(...gaps.values());
+    output.points.sort((left, right) => left.date.getTime() - right.date.getTime());
+  }
+  return { series: [...outputs.values()], warnings: [...warnings], errors: [...errors] };
+}
+
 /** Base series that must be calculated for currently visible studies. */
 export function activeStudyInputSeriesIds(
   studySpecs: readonly ChartStudySpec[],
@@ -524,33 +644,48 @@ export function resolveStudies(
       return;
     }
     const input = inputs[0]!;
+    if (spec.kind === "spread") {
+      const pairedInput = inputs[1]!;
+      const inputUnit = knownUnitSignature(input);
+      if (inputUnit === null || inputUnit !== knownUnitSignature(pairedInput)) {
+        errors.push(`${spec.id}: spread cannot subtract ${pairedInput.label} (${pairedInput.unit || "unit unknown"}) from ${input.label} (${input.unit || "unit unknown"}); inputs require matching known units, currencies and scales.`);
+        return;
+      }
+    }
     const color = spec.color ?? STUDY_COLORS[index % STUDY_COLORS.length]!;
+    const interrupted = resolveInterruptedStudy(inputs as ResolvedSeries[], { ...spec, color });
+    if (interrupted) {
+      resolved.push(...interrupted.series);
+      warnings.push(...interrupted.warnings);
+      errors.push(...interrupted.errors);
+      return;
+    }
     let outputs: ResolvedSeries[] = [];
     if (spec.kind === "sma") outputs = resolveMovingAverage(spec, input, color, false);
     else if (spec.kind === "ema") outputs = resolveMovingAverage(spec, input, color, true);
     else if (spec.kind === "bollinger") outputs = resolveBollinger(spec, input, color);
     else if (spec.kind === "rsi") outputs = resolveRsi(spec, input, color);
     else if (spec.kind === "macd") outputs = resolveMacd(spec, input, color);
-    else if (spec.kind === "volume") outputs = resolveVolume(spec, input, color);
+    else if (spec.kind === "volume") {
+      outputs = resolveVolume(spec, input, color);
+      if (!input.volumeUnit && outputs.some((output) => output.points.length > 0)) {
+        warnings.push(`Volume unit unknown: ${input.label}.`);
+      }
+    }
     else {
       const pairedInput = inputs[1]!;
-      const inputUnit = seriesUnit(input);
-      const pairedUnit = seriesUnit(pairedInput);
-      const sameDimension = inputUnit.dimension === pairedUnit.dimension;
-      const differentCurrencies = inputUnit.currency !== null
-        && pairedUnit.currency !== null
-        && inputUnit.currency !== pairedUnit.currency;
-      if (spec.kind === "spread" && !sameDimension) {
-        warnings.push(
-          `${spec.id}: spread cannot subtract ${pairedInput.unit} from ${input.unit}; choose inputs with matching units.`,
-        );
-      } else if ((spec.kind === "ratio" || spec.kind === "spread") && differentCurrencies) {
+      const inputCurrency = seriesCurrency(input);
+      const pairedCurrency = seriesCurrency(pairedInput);
+      const differentCurrencies = inputCurrency !== null
+        && pairedCurrency !== null
+        && inputCurrency !== pairedCurrency;
+      if (spec.kind === "ratio" && differentCurrencies) {
         warnings.push(
-          `${spec.id}: ${spec.kind} inputs use different currencies (${inputUnit.currency} and ${pairedUnit.currency}); raw values are not FX-converted.`,
+          `${spec.id}: ${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 using as-of alignment.`);
+        warnings.push(`${spec.id}: correlation mixes ${input.nativeFrequency} and ${pairedInput.nativeFrequency} observations; only matching observation times contribute.`);
       }
       outputs = resolvePairStudy(spec, input, pairedInput, color);
     }

package/src/time-series/transforms.test.ts

@@ -1,10 +1,10 @@
 import { describe, expect, test } from "bun:test";
 import { alignTimeSeries, effectiveTimeSeriesPointTime } from "./alignment";
 import { extractPriceSeries } from "./market";
-import { applySeriesTransform } from "./transforms";
+import { applyResolvedSeriesTransform, applySeriesTransform } from "./transforms";
 import type { ResolvedSeries, TimeSeriesPoint } from "./types";
 
-function point(date: string, value: number, availableAt?: string): TimeSeriesPoint {
+function point(date: string, value: number | null, availableAt?: string): TimeSeriesPoint {
   const observedAt = new Date(`${date}T00:00:00Z`);
   return {
     date: observedAt,
@@ -33,6 +33,20 @@ function series(id: string, points: TimeSeriesPoint[], interpolation: ResolvedSe
 }
 
 describe("series transformations", () => {
+  test("price display transforms preserve supporting share volume", () => {
+    const points = [
+      { ...point("2024-01-01", 10), open: 9, high: 11, low: 8, close: 10, volume: 1000 },
+      { ...point("2024-01-02", 15), open: 12, high: 16, low: 11, close: 15, volume: 2000 },
+    ];
+    for (const transform of ["percent", "index100", "log", "yoy"] as const) {
+      const transformed = applySeriesTransform(points, transform);
+      expect(transformed.map(({ volume }) => volume)).toEqual([1000, 2000]);
+    }
+    expect(applySeriesTransform(points, "percent")[1]).toMatchObject({ value: 50, close: 50, open: 20 });
+    const volumes = points.map((point) => ({ ...point, value: point.volume }));
+    expect(applySeriesTransform(volumes, "percent").map(({ value }) => value)).toEqual([0, 100]);
+  });
+
   test("normalizes to percent and index 100 from the first nonzero observation", () => {
     const points = [point("2024-01-01", 10), point("2024-02-01", 15), point("2024-03-01", 20)];
     expect(applySeriesTransform(points, "percent").map(({ value }) => value)).toEqual([0, 50, 100]);
@@ -40,6 +54,28 @@ describe("series transformations", () => {
     expect(points.map(({ value }) => value)).toEqual([10, 15, 20]);
   });
 
+  test("retains original scalars and units through repeated transforms without changing negative-baseline arithmetic", () => {
+    const source = series("price", [
+      point("2024-01-01", -10),
+      point("2024-02-01", -5),
+      point("2024-03-01", null),
+      point("2024-04-01", 0),
+      { ...point("2024-05-01", null), close: 2 },
+    ], "none");
+    const original = structuredClone(source);
+    const percent = applyResolvedSeriesTransform(source, "percent");
+    const indexed = applyResolvedSeriesTransform(percent, "index100");
+
+    expect(percent.points.map(({ value }) => value)).toEqual([0, 50, null, 100, null]);
+    expect(percent.points.at(-1)?.close).toBe(120);
+    expect(indexed.points.map(({ value }) => value)).toEqual([0, 100, null, 200, null]);
+    expect(indexed.points.map(({ rawValue }) => rawValue)).toEqual([-10, -5, null, 0, 2]);
+    expect(percent).toMatchObject({ unit: "%", rawUnit: "value" });
+    expect(indexed).toMatchObject({ unit: "index", rawUnit: "value" });
+    expect(applySeriesTransform([{ ...point("2024-01-01", 10), rawValue: null }], "log")[0]?.rawValue).toBeNull();
+    expect(source).toEqual(original);
+  });
+
   test("matches QoQ and YoY by observation calendar instead of adjacent array position", () => {
     const points = [
       point("2023-03-31", 80),

package/src/time-series/transforms.ts

@@ -1,7 +1,9 @@
 import type { ResolvedSeries, SeriesTransform, TimeSeriesPoint } from "./types";
 
 const DAY_MS = 24 * 60 * 60 * 1_000;
-const NUMERIC_POINT_FIELDS = ["value", "open", "high", "low", "close", "volume"] as const;
+// Volume is separate supporting data, not another price. A volume series has
+// its primary measurement in `value`, which still receives the transform.
+const NUMERIC_POINT_FIELDS = ["value", "open", "high", "low", "close"] as const;
 
 function finiteNumber(value: unknown): value is number {
   return typeof value === "number" && Number.isFinite(value);
@@ -106,6 +108,7 @@ function mapNumericFields(
   mapper: (value: number | null | undefined, field: typeof NUMERIC_POINT_FIELDS[number]) => number | null,
 ): TimeSeriesPoint {
   const transformed = clonePoint(point);
+  transformed.rawValue = point.rawValue === undefined ? primaryValue(point) : point.rawValue;
   for (const field of NUMERIC_POINT_FIELDS) {
     const value = point[field];
     if (field !== "value" && value === undefined) continue;
@@ -172,6 +175,7 @@ export function applyResolvedSeriesTransform(
   return {
     ...series,
     transform,
+    rawUnit: series.rawUnit ?? series.unit,
     unit: percent ? "%" : transform === "index100" ? "index" : "log",
     unitGroup: percent ? "percent" : transform === "index100" ? "index" : "log",
     dataShape: "scalar",