gloomberb 0.13.2 → 0.14.0

package/src/time-series/resolve.ts

@@ -1,4 +1,10 @@
-import { appendLiveQuotePoint } from "./chart-data";
+import { resolveAssetDisplayKind } from "../market-data/market/format";
+import { hasValidQuoteObservationTime } from "../market-data/quotes/freshness";
+import { SnapshotHistoryUnavailableError } from "../market-data/snapshot-provider";
+import { financialPeriodCoverage, financialPeriodCoverageWarnings, limitSeriesObservations } from "./financial-period-coverage";
+import { HistoryCoverageError, historyCoverageNotice, isShellLondonTarget } from "../sources/history-coverage";
+import { FINANCIAL_VINTAGE_NOTICE, SEC_EPS_BASIS_NOTICE } from "../utils/financial-statements";
+import { appendLiveQuotePoint, hasUnknownBondHistoryBasis } from "./chart-data";
 import {
   getTimeRangeForDateWindow,
   isDateWindowWithinTimeRange,
@@ -21,9 +27,10 @@ import {
 } from "./resolution";
 import type { TimeRange } from "./range";
 import type { DataProvider, MarketDataRequestContext } from "../types/data-provider";
-import type { Quote, TickerFinancials } from "../types/financials";
+import type { Quote, QuoteMetadata, TickerFinancials } from "../types/financials";
+import { mergeQuoteMetadata, quoteMetadataFromQuote, quoteMetadataMatchesTarget } from "../market-data/quotes/metadata";
 import type { FredSeriesLoadResult, FredSeriesRequest } from "../data/fred-series";
-import { extractFredSeries } from "./economic";
+import { extractFredSeries, fredCreditCoverageNotice } from "./economic";
 import {
   getTimeSeriesField,
   isFundamentalFieldId,
@@ -32,18 +39,24 @@ import {
 } from "./field-catalog";
 import {
   fundamentalSeriesUsesAvailabilityFallback,
+  valuationCurrencyWarning,
+  valuationPriceIssues,
   valuationSeriesUsesLiveQuote,
+  valuationSeriesUsesPriceHistory,
 } from "./fundamentals";
-import { extractSecuritySeries } from "./market";
+import { FORWARD_PE_BASIS_NOTICE, REALIZED_NTM_PE_BASIS_NOTICE } from "./forward-valuation";
+import { valuationPriceWarning } from "./valuation-price";
+import { extractSecuritySeries, collectPriceHistoryIntegrity, chartPriceHistoryIntegrityNotices } from "./market";
 import {
   activeStudyInputSeriesIds,
   maxStudyWarmupPoints,
   resolveStudies,
 } from "./studies";
-import { isOhlcSeriesStyle } from "./spec";
 import { applyResolvedSeriesTransform } from "./transforms";
 import { clipSeriesToWindow } from "./alignment";
-import { chartQuoteOverrideKeyForSource } from "./live-quotes";
+import { clipPriceComparison, priceComparisonBoundsForSeries, priceComparisonSeriesIds, priceObservationWindowFilter, resolvePriceComparison, type PriceComparison } from "./price-comparison";
+import { reportingCurrencySeries } from "./reporting-currency";
+import { chartQuoteOverrideKeyForSource, compareChartQuoteRecency } from "./live-quotes";
 import { chartSeriesSourceKey } from "../capabilities/chart-series";
 import { resolutionForExplicitMarketPeriods } from "./market-resolution";
 import {
@@ -83,6 +96,8 @@ export interface ChartResolveSources {
   now?: Date;
   /** Latest streamed quote per security identity, layered over snapshot data. */
   quoteOverrides?: ReadonlyMap<string, Quote>;
+  /** Capture the resolved inputs, including the calculation buffer, for an export. */
+  onSecurityData?: (series: ChartSeriesSpec, data: TickerFinancials, includesHistory: boolean) => void;
   /** Provider-neutral boundary for plugin-owned chart series. */
   resolveCapabilitySeries?: (
     source: Extract<ChartSeriesSpec["source"], { kind: "capability" }>,
@@ -105,6 +120,7 @@ export interface ChartResolveOptions {
 /** Raw source data retained while live quotes recompute the chart tail. */
 export class ChartResolveCache {
   readonly financialsByInstrument = new Map<string, Promise<TickerFinancials | null>>();
+  readonly quoteMetadataByInstrument = new Map<string, Promise<QuoteMetadata | null>>();
   readonly priceHistoryByRequest = new Map<string, Promise<TickerFinancials["priceHistory"]>>();
   readonly accumulatedPriceHistory = new Map<string, TickerFinancials["priceHistory"]>();
   readonly resolutionSupportByInstrument = new Map<string, Promise<ChartResolutionSupport[]>>();
@@ -274,6 +290,7 @@ function requestResolution(
   if (spec.viewport.resolution !== "auto") {
     const maxRange = getSupportMaxRange(sharedSupport, spec.viewport.resolution);
     const supported = sharedSupport.length === 0
+      || maxRange === "ALL"
       || (
         maxRange !== null
         && bounds.start !== null
@@ -345,6 +362,36 @@ function filterPoints(points: readonly TimeSeriesPoint[], bounds: DateBounds): T
   });
 }
 
+function resolvePriceHistoryIntegrity(
+  spec: ChartSpec,
+  requestedSeries: readonly ResolvedSeries[],
+  visibleSeries: readonly ResolvedSeries[],
+  bounds: DateBounds,
+  resolution: ManualChartResolution,
+  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"),
+  ];
+}
+
+function comparisonDisplayBounds(bounds: DateBounds, comparison: PriceComparison | null): DateBounds {
+  if (comparison?.alignment !== "session-date" || comparison.start === null || comparison.end === null) return bounds;
+  // A date-only selection can include a local session that began on the prior
+  // UTC day. Keep its original timestamp visible in the rendering viewport.
+  return {
+    start: bounds.start === null ? null : Math.min(bounds.start, comparison.start),
+    end: bounds.end === null ? null : Math.max(bounds.end, comparison.end),
+  };
+}
+
 function followLatestMarketObservation(
   bounds: DateBounds,
   series: readonly ResolvedSeries[],
@@ -373,6 +420,7 @@ function emptyFinancials(priceHistory: TickerFinancials["priceHistory"] = []): T
 export function seedChartResolutionResult(
   spec: ChartSpec,
   historyByInstrument: ReadonlyMap<string, TickerFinancials["priceHistory"]>,
+  referenceNow?: Date,
 ): ChartResolutionResult | null {
   const series: ResolvedSeries[] = [];
   spec.series.forEach((seriesSpec, index) => {
@@ -384,22 +432,45 @@ export function seedChartResolutionResult(
     if (resolved?.points.length) series.push(resolved);
   });
   if (series.length === 0) return null;
-  // Studies ride along with the seed. Without them the chart briefly drops to
-  // base series alone whenever it falls back here, and every panel a study
-  // owns loses its rows until the first real resolve lands.
-  const seeded = spec.studies.length > 0
-    ? [...series, ...resolveStudies(series, spec.studies).series]
-    : series;
+  let latest = Number.NEGATIVE_INFINITY;
+  for (const entry of series) {
+    for (const point of entry.points) latest = Math.max(latest, point.date.getTime());
+  }
+  const bounds = requestedBounds(spec, referenceNow ?? new Date(latest));
+  const resolution = requestResolution(spec, bounds, new Set(series.map((entry) => entry.id)), {}, []);
+  const priceComparison = resolvePriceComparison(spec, series, bounds, resolution);
+  const displayBounds = comparisonDisplayBounds(bounds, priceComparison);
+  const comparisonBounds = priceComparison && priceComparison.start !== null
+    ? priceComparison : bounds;
+  const baseSeries = series.map((entry) => prepareBaseSeriesForStudies(entry, priceComparisonBoundsForSeries(entry, priceComparison) ?? comparisonBounds));
+  // Calculate studies from raw buffered inputs, then use the same presentation
+  // and visible-window rules as the network result.
+  const studies = resolveStudies(series, spec.studies);
+  const bufferedSeries = [
+    ...baseSeries,
+    ...applyStudyPresentationTransforms(studies.series, spec.studies, series, comparisonBounds, undefined, priceComparison),
+  ].map((entry) => clipPriceComparison(entry, priceComparison));
+  const visible = bufferedSeries.map((entry) => {
+    const entryBounds = presentationBounds(entry, spec.studies, priceComparison, bounds);
+    const clipped = entryBounds.start !== null && entryBounds.end !== null
+      ? clipSeriesToWindow(entry, new Date(entryBounds.start), new Date(entryBounds.end))
+      : { ...entry, points: filterPoints(entry.points, entryBounds) };
+    return clipPriceComparison(limitSeriesObservations(spec, clipped), priceComparison);
+  });
+  const priceHistoryIntegrity = resolvePriceHistoryIntegrity(spec, series, visible, bounds, resolution, spec.viewport.dateWindow ?? null);
   return {
-    series: seeded,
-    legendSeries: seeded,
-    bufferedSeries: seeded,
-    loading: false,
-    errors: [],
-    warnings: [],
-    resolution: spec.viewport.resolution === "auto"
-      ? getPresetResolution(spec.viewport.range)
-      : spec.viewport.resolution,
+    series: visible,
+    ...(priceHistoryIntegrity.length ? { priceHistoryIntegrity } : {}),
+    ...(priceComparison ? { priceComparison } : {}),
+    legendSeries: visible,
+    ...(spec.viewport.maxPoints === undefined ? { bufferedSeries } : {}),
+    ...((explicitBounds(spec) !== null || spec.viewport.maxPoints === undefined)
+      && displayBounds.start !== null && displayBounds.end !== null
+      ? { viewport: { start: new Date(displayBounds.start), end: new Date(displayBounds.end) } } : {}),
+    loading: true,
+    errors: studies.errors,
+    warnings: [...studies.warnings, ...chartPriceHistoryIntegrityNotices(priceHistoryIntegrity), ...(priceComparison ? [priceComparison.notice] : [])],
+    resolution,
   };
 }
 
@@ -542,10 +613,7 @@ function clampHistoryBoundsToSupport(
 function latestQuote(snapshot: Quote | undefined, override: Quote | undefined): Quote | undefined {
   if (!snapshot) return override;
   if (!override) return snapshot;
-  if (override.lastUpdated !== snapshot.lastUpdated) {
-    return override.lastUpdated > snapshot.lastUpdated ? override : snapshot;
-  }
-  return (override.receivedAt ?? 0) >= (snapshot.receivedAt ?? 0) ? override : snapshot;
+  return compareChartQuoteRecency(override, snapshot) >= 0 ? override : snapshot;
 }
 
 function mergeHistory(
@@ -554,12 +622,16 @@ function mergeHistory(
   quoteOverride: Quote | undefined,
   now: number,
   liveBarResolution?: ManualChartResolution,
+  exchange?: string,
+  appendQuote = true,
+  assetCategory?: string,
 ): TickerFinancials {
   const base = financials ?? emptyFinancials();
   const quote = latestQuote(base.quote, quoteOverride);
-  const priceHistory = appendLiveQuotePoint(history, quote, liveBarResolution
-    ? { now, mode: "ohlc", resolution: liveBarResolution }
-    : { now });
+  const unknownHistoryBasis = hasUnknownBondHistoryBasis(quote, assetCategory, base.quoteMetadata?.instrumentType);
+  const priceHistory = appendQuote && !unknownHistoryBasis ? appendLiveQuotePoint(history, quote, liveBarResolution
+    ? { now, mode: "ohlc", resolution: liveBarResolution, exchange }
+    : { now }) : history;
   return { ...base, quote, priceHistory };
 }
 
@@ -569,6 +641,12 @@ async function loadPriceHistory(
   request: PriceHistoryRequest,
 ): Promise<TickerFinancials["priceHistory"]> {
   const context = requestContext(source);
+  let coverageNotice: string | null = null;
+  const observeCoverage = (points: TickerFinancials["priceHistory"]) => {
+    if (isShellLondonTarget(source.instrument.symbol, source.instrument.exchange)) {
+      coverageNotice ??= historyCoverageNotice(points, request.visibleBounds.start);
+    }
+  };
   const detailStart = request.bounds.start === null ? null : new Date(request.bounds.start);
   const detailEnd = exclusiveEnd(request.bounds);
   if (request.explicitWindow && detailStart && detailEnd && provider.getDetailedPriceHistory) {
@@ -581,8 +659,11 @@ async function loadPriceHistory(
         request.resolution,
         context,
       );
+      observeCoverage(detailed);
       if (historyIntersectsBounds(detailed, request.visibleBounds)) return detailed;
-    } catch {
+    } catch (error) {
+      if (error instanceof SnapshotHistoryUnavailableError) throw error;
+      if (error instanceof HistoryCoverageError) coverageNotice ??= error.message;
       // Fall through to trailing history when a provider cannot serve the exact window.
     }
   }
@@ -595,6 +676,7 @@ async function loadPriceHistory(
         request.resolution,
         context,
       );
+      observeCoverage(resolved);
       if (
         resolved.length > 0
         && (!request.explicitWindow || historyIntersectsBounds(resolved, request.visibleBounds))
@@ -610,7 +692,9 @@ async function loadPriceHistory(
         );
         return resolved;
       }
-    } catch {
+    } catch (error) {
+      if (error instanceof SnapshotHistoryUnavailableError) throw error;
+      if (error instanceof HistoryCoverageError) coverageNotice ??= error.message;
       // Some providers expose the resolution API but only support a subset.
     }
   }
@@ -618,7 +702,7 @@ async function loadPriceHistory(
     // getPriceHistory chooses its own interval, so using it here would make a
     // manual interval label claim a granularity the provider did not honor.
     throw new Error(
-      `Requested ${request.resolution} price history is unavailable for ${instrumentLabel(source)}. Choose Auto or a supported interval.`,
+      coverageNotice ?? `Requested ${request.resolution} price history is unavailable for ${instrumentLabel(source)}. Choose Auto or a supported interval.`,
     );
   }
   const fallback = await provider.getPriceHistory(
@@ -626,13 +710,18 @@ async function loadPriceHistory(
     source.instrument.exchange ?? "",
     request.fallbackRange,
     context,
-  );
+  ).catch((error: unknown) => {
+    if (coverageNotice) throw new Error(coverageNotice);
+    throw error;
+  });
+  observeCoverage(fallback);
+  if (fallback.length === 0 && coverageNotice) throw new Error(coverageNotice);
   if (
     request.explicitWindow
     && fallback.length > 0
     && !historyIntersectsBounds(fallback, request.visibleBounds)
   ) {
-    throw new Error(`Price history for the requested window is unavailable for ${instrumentLabel(source)}.`);
+    throw new Error(coverageNotice ?? `Price history for the requested window is unavailable for ${instrumentLabel(source)}.`);
   }
   return fallback;
 }
@@ -642,17 +731,30 @@ function baseSecuritySeries(
   financials: TickerFinancials,
   index: number,
   marketResolution?: ManualChartResolution,
+  quoteMetadata: QuoteMetadata | null | undefined = financials.quoteMetadata,
 ): ResolvedSeries | null {
   if (spec.source.kind !== "security") return null;
   const field = getTimeSeriesField(spec.source.fieldId);
   if (!field) return null;
   const points = extractSecuritySeries(financials, spec.source);
   const symbol = instrumentLabel(spec.source);
-  const currency = financials.quote?.currency;
-  const unit = field.unit.startsWith("currency") && currency
-    ? field.unit.replace("currency", currency)
+  const statementCurrency = field.id.startsWith("fundamental.") && field.unit.startsWith("currency")
+    ? reportingCurrencySeries(points, financials.financialCurrency) : null;
+  const currency = statementCurrency ? statementCurrency.currency : financials.quote?.currency || quoteMetadata?.currency;
+  const assetKind = resolveAssetDisplayKind({ assetCategory: financials.quote?.instrumentType || quoteMetadata?.instrumentType });
+  const unknownBondBasis = hasUnknownBondHistoryBasis(financials.quote,
+    spec.source.instrument.instrument?.secType, quoteMetadata?.instrumentType);
+  const volumeUnit = unknownBondBasis ? undefined : assetKind === "equity" ? "shares" as const : assetKind === "contract" ? "contracts" as const : undefined;
+  // A price quote establishes its currency, but only instrument metadata can
+  // establish a per-share or per-crypto-unit basis. This does not establish the
+  // provider's volume denomination or a derivative's contract multiplier.
+  const unitTemplate = field.unitGroup === "price" && isMarketFieldId(field.id)
+    ? unknownBondBasis ? "unknown" : `currency${assetKind === "equity" ? "/share" : assetKind === "crypto" ? "/unit" : ""}`
     : field.unit;
-  const currencyUnitGroup = field.unit.startsWith("currency") && currency
+  const unit = field.id === "market.volume" ? volumeUnit ?? ""
+    : unitTemplate.startsWith("currency") && currency ? unitTemplate.replace("currency", currency) : unitTemplate;
+  const currencyUnitGroup = unknownBondBasis && field.unitGroup === "price" ? "price:unknown"
+    : field.unit.startsWith("currency") && currency
     ? `${field.unitGroup}:${currency}`
     : field.unitGroup;
   const marketExchange = spec.source.instrument.exchange
@@ -664,14 +766,23 @@ function baseSecuritySeries(
     ? resolveExchangeTimeZone(marketExchange)
     : null;
   const latestChangePercent = marketField && field.unit.startsWith("currency")
-    ? financials.quote?.changePercent
+    && !unknownBondBasis
+    && financials.quote && hasValidQuoteObservationTime(financials.quote)
+    ? financials.quote.changePercent
     : undefined;
+  const priceIssues = valuationPriceIssues(financials, spec.source);
   return {
     id: spec.id,
     label: spec.label?.trim() || `${symbol} ${field.shortLabel}`,
     color: spec.color ?? SERIES_COLORS[index % SERIES_COLORS.length]!,
     unit,
     unitGroup: currencyUnitGroup,
+    priceAssetCategory: marketField && field.unitGroup === "price" && !unknownBondBasis
+      ? financials.quote?.instrumentType || quoteMetadata?.instrumentType : undefined,
+    volumeUnit,
+    ...(priceIssues.length ? { valuationPriceIssues: priceIssues } : {}),
+    warning: field.id === "market.volume" && !volumeUnit && points.length > 0
+      ? "Volume unit unknown." : statementCurrency?.warning ?? valuationCurrencyWarning(financials, spec.source),
     nativeFrequency: spec.source.period && spec.source.period !== "auto"
       ? spec.source.period
       : field.nativeFrequency,
@@ -682,6 +793,7 @@ function baseSecuritySeries(
     axis: spec.axis === "right" ? "right" : "left",
     panelId: spec.panelId,
     interpolation: spec.interpolation,
+    observationKind: marketField ? "market" : undefined,
     timeBasis: marketTimeZone
       ? {
           kind: "market",
@@ -833,12 +945,25 @@ function studyForOutput(
     .sort((left, right) => right.id.length - left.id.length)[0];
 }
 
+function presentationBounds(
+  series: ResolvedSeries,
+  studies: readonly ChartSpec["studies"][number][],
+  comparison: PriceComparison | null,
+  fallback: DateBounds,
+): DateBounds {
+  const study = studyForOutput(series.id, studies);
+  const sourceId = study && (study.kind === "sma" || study.kind === "ema" || study.kind === "bollinger")
+    ? study.inputSeriesIds[0] : series.id;
+  return (sourceId && comparison?.sourceBounds?.[sourceId]) || fallback;
+}
+
 function applyStudyPresentationTransforms(
   outputs: ResolvedSeries[],
   studies: readonly ChartSpec["studies"][number][],
   rawSeries: readonly ResolvedSeries[],
   visibleBounds: DateBounds,
   fallbackBaselineBounds?: DateBounds,
+  priceComparison?: PriceComparison | null,
 ): ResolvedSeries[] {
   const rawById = new Map(rawSeries.map((series) => [series.id, series] as const));
   return outputs.map((output) => {
@@ -849,10 +974,12 @@ function applyStudyPresentationTransforms(
     const input = rawById.get(study.inputSeriesIds[0] ?? "");
     if (!input || input.transform === "raw") return output;
     const baseline = input.transform === "percent" || input.transform === "index100"
-      ? scalarBaseline(input, visibleBounds)
+      ? scalarBaseline(input, priceComparisonBoundsForSeries(input, priceComparison ?? null) ?? visibleBounds)
         ?? (fallbackBaselineBounds ? scalarBaseline(input, fallbackBaselineBounds) : null)
       : undefined;
-    return applyResolvedSeriesTransform(output, input.transform, { baseline });
+    const transformed = applyResolvedSeriesTransform(output, input.transform, { baseline });
+    const inputBounds = priceComparison?.sourceBounds?.[input.id];
+    return inputBounds ? { ...transformed, points: filterPoints(transformed.points, inputBounds) } : transformed;
   });
 }
 
@@ -863,7 +990,9 @@ export async function resolveChartSpecData(
   options: ChartResolveOptions = {},
 ): Promise<ChartResolutionResult> {
   const errors: string[] = [];
-  const warnings: string[] = [];
+  const warnings: string[] = spec.series.some((entry) => entry.visible !== false
+    && entry.source.kind === "security" && isFundamentalFieldId(entry.source.fieldId))
+    ? [FINANCIAL_VINTAGE_NOTICE] : [];
   const priorityWarnings: string[] = [];
   const baseSeriesIds = new Set(spec.series.map((entry) => entry.id));
   const visibleSeriesIds = new Set(spec.series
@@ -883,24 +1012,55 @@ export async function resolveChartSpecData(
     return { series: [], loading: false, errors: ["Market data is unavailable."], warnings };
   }
 
-  const referenceNow = sources.now ?? new Date();
+  const resolutionStartedAt = Date.now();
+  const referenceNow = sources.now ?? new Date(resolutionStartedAt);
+  const comparedSeriesIds = new Set(priceComparisonSeriesIds(spec) ?? []);
   const initialVisibleBounds = requestedBounds(spec, referenceNow);
 
   const loadFinancials = (source: Extract<ChartSeriesSpec["source"], { kind: "security" }>) => {
-    const key = instrumentKey(source);
+    const fieldId = getTimeSeriesField(source.fieldId)?.id ?? source.fieldId;
+    // Calendar-window research needs the same full source bundle as a period
+    // count. The extended bundle also carries the estimate history behind the
+    // forward multiples; PEG alone has no historical series.
+    const statementHistory = /^(fundamental|valuation)\./.test(fieldId)
+      && fieldId !== "valuation.pegRatio"
+      ? "extended" as const : undefined;
+    const key = `${instrumentKey(source)}|history:${statementHistory ?? "default"}`;
     let pending = cache.financialsByInstrument.get(key);
     if (!pending) {
       pending = sources.dataProvider!
         .getTickerFinancials(
           source.instrument.symbol,
           source.instrument.exchange ?? "",
-          requestContext(source),
+          { ...requestContext(source), statementHistory },
         )
-        .catch(() => null);
+        .then((value) => {
+          if (value.statementHistory?.status === "retryable-failure") {
+            warnings.push(`${source.instrument.symbol}: extended SEC history is temporarily unavailable; retained observations may be from an earlier retrieval.`);
+          }
+          if (statementHistory && (!value.statementHistory || value.statementHistory.status === "retryable-failure")) cache.financialsByInstrument.delete(key);
+          return value;
+        })
+        .catch(() => { cache.financialsByInstrument.delete(key); return null; });
       cache.financialsByInstrument.set(key, pending);
     }
     return pending;
   };
+  const loadQuoteMetadata = (source: Extract<ChartSeriesSpec["source"], { kind: "security" }>) => {
+    const key = instrumentKey(source);
+    let pending = cache.quoteMetadataByInstrument.get(key);
+    if (!pending) {
+      const provider = sources.dataProvider!;
+      pending = Promise.resolve().then(() => provider.getQuoteMetadata
+        ? provider.getQuoteMetadata(source.instrument.symbol, source.instrument.exchange ?? "", requestContext(source))
+        : provider.getQuote(source.instrument.symbol, source.instrument.exchange ?? "", requestContext(source)).then(quoteMetadataFromQuote))
+        .then((metadata) => metadata && quoteMetadataMatchesTarget(metadata, source.instrument.symbol, source.instrument.exchange) ? metadata : null)
+        .then((metadata) => { if (!metadata) cache.quoteMetadataByInstrument.delete(key); return metadata; })
+        .catch(() => { cache.quoteMetadataByInstrument.delete(key); return null; });
+      cache.quoteMetadataByInstrument.set(key, pending);
+    }
+    return pending;
+  };
   const loadResolutionSupport = (
     source: Extract<ChartSeriesSpec["source"], { kind: "security" }>,
     immediate: boolean,
@@ -1015,6 +1175,9 @@ export async function resolveChartSpecData(
       cache.priceHistoryByRequest.set(key, pending);
     }
     const history = await pending;
+    const coverageNotice = isShellLondonTarget(source.instrument.symbol, source.instrument.exchange)
+      ? historyCoverageNotice(history, request.visibleBounds.start) : null;
+    if (coverageNotice) priorityWarnings.push(coverageNotice);
     const accumulationKey = `${instrumentKey(source)}|${request.resolution}`;
     const previousHistory = cache.accumulatedPriceHistory.get(accumulationKey) ?? [];
     if (
@@ -1081,6 +1244,9 @@ export async function resolveChartSpecData(
         };
         const fred = await loadEconomicSeries(request);
         const result = baseEconomicSeries(seriesSpec, fred, index);
+        const coverageNotice = fredCreditCoverageNotice(seriesSpec.source.seriesId, fred.data.info,
+          requestVisibleBounds.start, fred.data.observations);
+        if (result && coverageNotice) priorityWarnings.push(`${result.label}: ${coverageNotice}`);
         const freshnessWarning = staleFredWarning(fred);
         if (result && freshnessWarning) priorityWarnings.push(`${result.label}: ${freshnessWarning}`);
         return result;
@@ -1089,12 +1255,13 @@ export async function resolveChartSpecData(
       const source = seriesSpec.source;
       const marketField = isMarketFieldId(source.fieldId);
       const quoteDerivedValuation = valuationSeriesUsesLiveQuote(source.fieldId);
-      const needsHistory = marketField || quoteDerivedValuation;
+      const historyPricedValuation = valuationSeriesUsesPriceHistory(source.fieldId);
+      // Forward P/E only prices a history when the bundle carries estimates;
+      // otherwise the provider's single figure stands and history is not required.
+      const forwardPE = getTimeSeriesField(source.fieldId)?.id === "valuation.forwardPE";
+      const needsHistory = marketField || (historyPricedValuation && !forwardPE);
       const needsFinancials = !isPriceOnlyMarketFieldId(source.fieldId)
         || !source.instrument.exchange?.trim();
-      const quoteOverride = marketField || quoteDerivedValuation
-        ? sources.quoteOverrides?.get(chartQuoteOverrideKeyForSource(source))
-        : undefined;
       const financialsPromise = needsFinancials ? loadFinancials(source) : Promise.resolve(null);
       let resolvedSource = source;
       let financials: TickerFinancials | null;
@@ -1102,30 +1269,81 @@ export async function resolveChartSpecData(
       if (needsHistory && !source.instrument.exchange?.trim()) {
         financials = await financialsPromise;
         resolvedSource = sourceWithResolvedExchange(source, financials);
-        history = await loadHistory(resolvedSource, quoteDerivedValuation);
+        history = await loadHistory(resolvedSource, historyPricedValuation);
       } else {
         [financials, history] = await Promise.all([
           financialsPromise,
-          needsHistory ? loadHistory(source, quoteDerivedValuation) : Promise.resolve(null),
+          needsHistory ? loadHistory(source, historyPricedValuation) : Promise.resolve(null),
         ]);
         resolvedSource = sourceWithResolvedExchange(source, financials);
       }
-      const liveBarResolution = isOhlcSeriesStyle(seriesSpec.style) ? initialResolution : undefined;
-      const merged = history
-        ? mergeHistory(financials, history, quoteOverride, referenceNow.getTime(), liveBarResolution)
-        : quoteOverride && financials
-          ? { ...financials, quote: latestQuote(financials.quote, quoteOverride) }
-          : financials;
+      if (forwardPE && financials?.epsEstimates && !history) {
+        history = await loadHistory(resolvedSource, true).catch((error: unknown) => {
+          warnings.push(`${seriesSpec.label ?? seriesSpec.id}: ${error instanceof Error ? error.message : String(error)}`);
+          return null;
+        });
+      }
+      // A provider's forward P/E snapshot keeps its own timestamp; only a series
+      // that prices today's consensus itself follows the live quote.
+      const followsLiveQuote = marketField
+        || (quoteDerivedValuation && (!forwardPE || !!financials?.epsEstimates));
+      const quoteOverride = followsLiveQuote
+        ? sources.quoteOverrides?.get(chartQuoteOverrideKeyForSource(source))
+        : undefined;
+      // Display style does not change the sampling interval: line and candle
+      // charts must merge a live quote into the same active price bar.
+      const liveBarResolution = initialResolution;
+      // The viewport's initial reference stays fixed while a source request
+      // runs. Validate a newly arrived quote against the elapsed clock.
+      const observationNow = referenceNow.getTime() + Math.max(0, Date.now() - resolutionStartedAt);
+      let merged = financials ?? (history ? emptyFinancials() : null);
+      if (merged && quoteOverride) merged = { ...merged, quote: latestQuote(merged.quote, quoteOverride) };
       if (!merged) throw new Error(`No financial data is available for ${instrumentLabel(source)}.`);
+      // Historical labels can retain listing facts after the live price is
+      // unavailable. Reuse existing facts before requesting a price-free snapshot.
+      const existingMetadata = merged.quoteMetadata && quoteMetadataMatchesTarget(merged.quoteMetadata, resolvedSource.instrument.symbol, resolvedSource.instrument.exchange)
+        ? merged.quoteMetadata : undefined;
+      const needsMetadata = marketField && (
+        !(merged.quote?.currency || existingMetadata?.currency)
+        || !(merged.quote?.instrumentType || existingMetadata?.instrumentType)
+      );
+      const quoteMetadata = mergeQuoteMetadata(existingMetadata, needsMetadata ? await loadQuoteMetadata(resolvedSource) : null);
+      if (quoteMetadata || merged.quoteMetadata) merged = { ...merged, quoteMetadata };
+      if (history) {
+        // Classification must be available before combining observations. A
+        // quote cannot establish the price basis of independent bond history.
+        // Comparison endpoints also retain source history: a streamed quote
+        // could otherwise update only one leg within a shared weekly bar.
+        merged = mergeHistory(merged, history, undefined, observationNow,
+          liveBarResolution, resolvedSource.instrument.exchange,
+          !comparedSeriesIds.has(seriesSpec.id), resolvedSource.instrument.instrument?.secType);
+      }
+      if ((source.fieldId === "fundamental.eps" || source.fieldId === "valuation.trailingPE")
+        && [...merged.annualStatements, ...merged.quarterlyStatements].some((row) => row.epsBasis)) {
+        warnings.push(SEC_EPS_BASIS_NOTICE);
+      }
+      const resolvedSpec = resolvedSource === source ? seriesSpec : { ...seriesSpec, source: resolvedSource };
+      sources.onSecurityData?.(resolvedSpec, merged, history !== null);
       const result = baseSecuritySeries(
-        resolvedSource === source ? seriesSpec : { ...seriesSpec, source: resolvedSource },
+        resolvedSpec,
         merged,
         index,
         initialResolution,
+        quoteMetadata,
       );
       if (!result) throw new Error(`Unknown field ${source.fieldId}.`);
+      const reportedForwardPE = merged.fundamentals?.forwardPE;
+      if (source.fieldId === "valuation.forwardPE" && merged.epsEstimates) {
+        warnings.push(FORWARD_PE_BASIS_NOTICE);
+      } else if (source.fieldId === "valuation.forwardPE" && reportedForwardPE != null
+        && Number.isFinite(reportedForwardPE) && reportedForwardPE <= 0) {
+        result.warning = [result.warning, "Reported forward P/E is non-positive and is not meaningful for valuation."].filter(Boolean).join(" ");
+      }
+      if (source.fieldId === "valuation.realizedNtmPE" && merged.epsEstimates) {
+        warnings.push(REALIZED_NTM_PE_BASIS_NOTICE);
+      }
       if (isFundamentalFieldId(source.fieldId) && fundamentalSeriesUsesAvailabilityFallback(merged, source)) {
-        result.warning = "Publication dates are unavailable for some observations; period-end dates are used as a fallback.";
+        result.warning = [result.warning, "Publication dates are unavailable for some observations; period-end dates are used as a fallback."].filter(Boolean).join(" ");
       }
       return result;
     } catch (error) {
@@ -1146,10 +1364,14 @@ export async function resolveChartSpecData(
   const bounds = hasExplicitWindow
     ? requestVisibleBounds
     : followLatestMarketObservation(initialVisibleBounds, rawSeries);
+  const priceComparison = resolvePriceComparison(spec, rawSeries, bounds, initialResolution, requestBounds ? null : spec.viewport.dateWindow);
+  const displayBounds = comparisonDisplayBounds(bounds, priceComparison);
+  const comparisonBounds = priceComparison && priceComparison.start !== null
+    ? priceComparison : bounds;
   const resolution = initialResolution;
   const baseSeries = rawSeries
     .filter((entry) => visibleSeriesIds.has(entry.id))
-    .map((entry) => prepareBaseSeriesForStudies(entry, bounds, false, requestVisibleBounds));
+    .map((entry) => prepareBaseSeriesForStudies(entry, priceComparisonBoundsForSeries(entry, priceComparison) ?? comparisonBounds, false, priceComparison ? undefined : requestVisibleBounds));
   // Studies run over the same loaded history their base series carries. Clipping
   // them to the requested window instead left a study with no observations
   // wherever the accumulated buffer had already been panned past, so a study's
@@ -1166,26 +1388,48 @@ export async function resolveChartSpecData(
         studyResult.series,
         spec.studies,
         rawSeries,
-        bounds,
-        requestVisibleBounds,
+        comparisonBounds,
+        priceComparison ? undefined : requestVisibleBounds,
+        priceComparison,
       ),
     ];
     warnings.push(...studyResult.warnings);
     errors.push(...studyResult.errors);
   }
 
-  const bufferedSeries = assignAxes(resolved, [...spec.series, ...spec.studies], warnings);
-  resolved = bufferedSeries.map((entry) => (
-    bounds.start !== null && bounds.end !== null
-      ? clipSeriesToWindow(entry, new Date(bounds.start), new Date(bounds.end))
-      : { ...entry, points: filterPoints(entry.points, bounds) }
-  ));
-  if (spec.viewport.maxPoints !== undefined) {
-    resolved = resolved.map((entry) => ({
-      ...entry,
-      points: entry.points.slice(-spec.viewport.maxPoints!),
-    }));
-  }
+  const bufferedSeries = assignAxes(resolved, [...spec.series, ...spec.studies], warnings)
+    .map((entry) => clipPriceComparison(entry, priceComparison));
+  resolved = bufferedSeries.map((entry) => {
+    const entryBounds = presentationBounds(entry, spec.studies, priceComparison, bounds);
+    return entryBounds.start !== null && entryBounds.end !== null
+      ? clipSeriesToWindow(entry, new Date(entryBounds.start), new Date(entryBounds.end))
+      : { ...entry, points: filterPoints(entry.points, entryBounds) };
+  });
+  resolved = resolved.map((entry) => limitSeriesObservations(spec, entry));
+  resolved = resolved.map((entry) => clipPriceComparison(entry, priceComparison));
+  resolved = resolved.map((entry) => {
+    const visibleIssues = entry.points.flatMap((point) => point.provenance?.valuationPriceIssues ?? []);
+    if (!entry.valuationPriceIssues?.length && !visibleIssues.length) return entry;
+    const dates = new Set(entry.points.map((point) => point.date.getTime()));
+    const requestedIssues = (entry.valuationPriceIssues ?? []).filter((issue) => {
+      const time = issue.affectedAt ? Date.parse(issue.affectedAt) : NaN;
+      if (issue.kind === "history") return dates.has(time);
+      // Explicit financial-period requests exclude Current observations entirely.
+      if (spec.viewport.maxPoints !== undefined) return false;
+      if (!Number.isFinite(time)) return !hasExplicitWindow || bounds.end === null || bounds.end >= referenceNow.getTime();
+      return (bounds.start === null || time >= bounds.start) && (bounds.end === null || time <= bounds.end);
+    });
+    const issues = [...new Map([...requestedIssues, ...visibleIssues].map((issue) => [JSON.stringify(issue), issue])).values()];
+    return { ...entry, valuationPriceIssues: issues.length ? issues : undefined,
+      warning: [entry.warning, valuationPriceWarning(issues)].filter(Boolean).join(" ") || undefined };
+  });
+  const priceHistoryIntegrity = resolvePriceHistoryIntegrity(
+    spec, rawSeries, resolved,
+    bounds, resolution, requestBounds ? null : spec.viewport.dateWindow ?? null,
+  );
+  if (priceComparison) warnings.push(priceComparison.notice);
+  warnings.push(...chartPriceHistoryIntegrityNotices(priceHistoryIntegrity));
+  warnings.push(...financialPeriodCoverageWarnings(financialPeriodCoverage(spec, resolved)));
   const resolvedById = new Map(resolved.map((entry) => [entry.id, entry] as const));
   const hiddenBaseSeries = rawSeries
     .filter((entry) => !visibleSeriesIds.has(entry.id))
@@ -1215,11 +1459,13 @@ export async function resolveChartSpecData(
   }
 
   const exposeViewport = hasExplicitWindow || spec.viewport.maxPoints === undefined;
-  const viewport = exposeViewport && bounds.start !== null && bounds.end !== null
-    ? { start: new Date(bounds.start), end: new Date(bounds.end) }
+  const viewport = exposeViewport && displayBounds.start !== null && displayBounds.end !== null
+    ? { start: new Date(displayBounds.start), end: new Date(displayBounds.end) }
     : undefined;
   return {
     series: resolved,
+    ...(priceHistoryIntegrity.length ? { priceHistoryIntegrity } : {}),
+    ...(priceComparison ? { priceComparison } : {}),
     ...(sharedSupport.length > 0 ? { resolutionSupport: sharedSupport } : {}),
     legendSeries,
     ...(spec.viewport.maxPoints === undefined ? { bufferedSeries } : {}),