gloomberb 0.18.4 → 0.19.0

package/src/time-series/filed-trailing-eps.ts

@@ -0,0 +1,197 @@
+import type { Fundamentals, FinancialStatement, TickerFinancials } from "../types/financials";
+import { resolveCurrencyUnit } from "../utils/currency-units";
+import { areNearbyFinancialPeriodEnds, statementFieldAvailability } from "../utils/financial-statements";
+import { extractFundamentalSeries, knownWhenFiled } from "./fundamentals";
+import type { SecuritySeriesSource, TimeSeriesPoint } from "./types";
+
+const DAY_MS = 86_400_000;
+/**
+ * A figure stops pricing this long after its period end. Sixteen months
+ * covers a fiscal year plus its filing, so a year of unavailable quarterly
+ * sums falls back on the last annual figure but never on one long overdue.
+ */
+export const STALE_TRAILING_EPS_MS = 487 * DAY_MS;
+/**
+ * The latest period's trailing figure reads statements this far back at most:
+ * its four quarters (some 270 days), and for a fiscal fourth quarter read from
+ * its year, the three quarters before it. Older rows change nothing.
+ */
+const LATEST_WINDOW_MS = 760 * DAY_MS;
+
+/** One trailing-twelve-month EPS figure and when it became known. */
+export interface EpsStep {
+  /** ISO period end. */
+  periodEnd: string;
+  /** Four reported quarters summed, or a reported fiscal year. */
+  basis: "ttm" | "annual";
+  knownAt: Date;
+  /** False when no publication date or report is on record and `knownAt` is the period end. */
+  dated: boolean;
+  /** Statement currency units; null when unavailable (a declared gap or an incomplete run of quarters). */
+  eps: number | null;
+  currency: string | null;
+}
+
+function epsSeries(financials: TickerFinancials, period: "ttm" | "annual"): TimeSeriesPoint[] {
+  const source: SecuritySeriesSource = { kind: "security", instrument: { symbol: "" }, fieldId: "fundamental.eps", period, timestampMode: "available-at" };
+  return extractFundamentalSeries(financials, source);
+}
+
+/**
+ * Trailing EPS through time, oldest first. Four reported quarters are summed
+ * by the shared statement series, which keeps declared gaps and broken runs
+ * of quarters unavailable and reads a fiscal fourth quarter with no EPS of its
+ * own from its year. A reported fiscal year is itself a trailing twelve-month
+ * figure; at a fiscal year end it replaces the quarterly sum. `known` dates
+ * each row's figures (PEB dates them by the company's reports as well).
+ */
+export function trailingEpsSteps(
+  financials: TickerFinancials,
+  known: (row: FinancialStatement) => FinancialStatement = knownWhenFiled,
+): EpsStep[] {
+  const adjusted = { ...financials, quarterlyStatements: financials.quarterlyStatements.map(known),
+    annualStatements: financials.annualStatements.map(known) };
+  const toStep = (basis: EpsStep["basis"]) => (point: TimeSeriesPoint): EpsStep => ({
+    periodEnd: point.observedAt.toISOString().slice(0, 10), basis, knownAt: point.date, dated: point.availableAt !== undefined,
+    eps: point.value != null && Number.isFinite(point.value) ? point.value : null, currency: point.provenance?.currency ?? null,
+  });
+  const steps = epsSeries(adjusted, "annual").map(toStep("annual"));
+  for (const step of epsSeries(adjusted, "ttm").map(toStep("ttm"))) {
+    const index = steps.findIndex((other) => areNearbyFinancialPeriodEnds(other.periodEnd, step.periodEnd));
+    if (index < 0) steps.push(step);
+    else if (steps[index]!.eps == null && step.eps != null) steps[index] = step;
+  }
+  return steps.sort((a, b) => a.knownAt.getTime() - b.knownAt.getTime() || a.periodEnd.localeCompare(b.periodEnd));
+}
+
+/** The trailing EPS of the last period filed, with that period's end and the statements' currency. */
+interface FiledTrailingEps {
+  eps: number;
+  periodEnd: string;
+  currency: string;
+}
+
+/**
+ * How far the filed figure may sit from Gloom Cloud's, either way, before it
+ * is taken for another share basis (a receipt or a class the flags miss, as
+ * BRK.B's statements are per Class A share) rather than newer or restated
+ * quarters: PLTR's 1.17 against 1.13 stands, 4.00 against 0.40 does not.
+ */
+const SERVED_EPS_RATIO_LIMIT = 1.5;
+
+type TrailingEpsInputs = Pick<TickerFinancials, "quote" | "fundamentals" | "annualStatements" | "quarterlyStatements" | "financialCurrency">;
+
+const isReceipt = (financials: TrailingEpsInputs) => !!(
+  financials.quote?.isDepositaryReceipt || financials.fundamentals?.isDepositaryReceipt
+  || financials.fundamentals?.shareBasis === "depositary_receipt" || financials.quote?.adrRatio || financials.fundamentals?.adrRatio
+);
+
+/** `filed` is the day the latest EPS on record was filed (a restated one's restating filing), the period end when none is dated. */
+type LatestStep = { periodEnd: string; eps: number; currency: string; filed: string } | null;
+
+/**
+ * The last period's step by what it is read from: the router answers the same
+ * rows many times, in new arrays. Bounded; the oldest entry leaves first.
+ */
+const latestSteps = new Map<string, LatestStep>();
+const LATEST_STEPS_KEPT = 500;
+
+/** What the trailing EPS series reads of a row. */
+const rowKey = (row: FinancialStatement) => [
+  row.date, row.currency ?? "", row.eps ?? "", statementFieldAvailability(row, "eps") ?? "", row.availableAt ?? "", row.dateSource ?? "",
+  Object.keys(row.fieldAvailability ?? {}).length,
+  row.unavailableFields?.join("+") ?? "", row.unavailableEarnings?.join("+") ?? "", row.epsBasis?.status ?? "", row.shareBasis ?? "",
+].join("|");
+
+/** The trailing EPS step for the last period on record, null when that period gives none. */
+function latestStep(financials: TrailingEpsInputs): LatestStep {
+  const rows = [...financials.quarterlyStatements, ...financials.annualStatements];
+  const latest = rows.map((row) => row.date).filter((date) => Number.isFinite(Date.parse(date))).sort().at(-1);
+  if (!latest) return null;
+  const recent = (row: FinancialStatement) => Date.parse(latest) - Date.parse(row.date) <= LATEST_WINDOW_MS;
+  const quarterlyStatements = financials.quarterlyStatements.filter(recent);
+  const annualStatements = financials.annualStatements.filter(recent);
+  const key = [financials.financialCurrency ?? "", quarterlyStatements.map(rowKey).join(";"), annualStatements.map(rowKey).join(";")].join("#");
+  if (latestSteps.has(key)) return latestSteps.get(key)!;
+  const found = trailingEpsSteps({ financialCurrency: financials.financialCurrency, priceHistory: [], quarterlyStatements, annualStatements })
+    .find((candidate) => areNearbyFinancialPeriodEnds(candidate.periodEnd, latest));
+  const filed = [...quarterlyStatements, ...annualStatements]
+    .flatMap((row) => typeof row.eps === "number" ? [statementFieldAvailability(row, "eps")?.slice(0, 10)] : [])
+    .filter((date): date is string => !!date).sort().at(-1);
+  const step = found?.eps != null && found.currency
+    ? { periodEnd: found.periodEnd, eps: found.eps, currency: found.currency, filed: filed && filed > found.periodEnd ? filed : found.periodEnd }
+    : null;
+  if (latestSteps.size >= LATEST_STEPS_KEPT) latestSteps.delete(latestSteps.keys().next().value!);
+  latestSteps.set(key, step);
+  return step;
+}
+
+/**
+ * The headline trailing EPS, as PEB and GE read the statements: the diluted
+ * EPS of the last four filed quarters, or of the fiscal year when that is the
+ * last period filed. Null when that period gives none (a quarter missing or
+ * withheld, a split basis unresolved, two share bases), when it is overdue,
+ * when its currency is not the price's, for a depositary receipt, whose
+ * statements are per ordinary share, when a split went ex after the last of
+ * its figures was filed (they are on the old share count until a filing
+ * restates them), and when it is more than SERVED_EPS_RATIO_LIMIT times
+ * Gloom Cloud's figure either way.
+ */
+function filedTrailingEps(financials: TrailingEpsInputs, now = Date.now()): FiledTrailingEps | null {
+  const price = resolveCurrencyUnit(financials.quote?.currency);
+  if (!financials.quote || price.divisor !== 1 || !/^[A-Z]{3}$/.test(price.currency) || isReceipt(financials)) return null;
+  const step = latestStep(financials);
+  if (!step || now - Date.parse(step.periodEnd) > STALE_TRAILING_EPS_MS) return null;
+  const currency = resolveCurrencyUnit(step.currency);
+  if (currency.currency !== price.currency || currency.divisor !== 1) return null;
+  // The trailing block's amounts are in another currency: an EPS beside them in this one would be read as theirs.
+  const block = financials.fundamentals?.financialCurrency?.trim();
+  if (block && resolveCurrencyUnit(block).currency !== price.currency) return null;
+  const split = financials.fundamentals?.splitShareBasis?.exDate;
+  if (split && split > step.filed) return null;
+  const served = financials.fundamentals?.eps;
+  if (typeof served === "number" && Number.isFinite(served) && !withinServedRatio(step.eps, served)) return null;
+  return { eps: step.eps, periodEnd: step.periodEnd, currency: price.currency };
+}
+
+/** Same sign and within SERVED_EPS_RATIO_LIMIT of each other; a figure against a zero is not. */
+function withinServedRatio(filed: number, served: number): boolean {
+  const ratio = filed / served;
+  return Number.isFinite(ratio) && ratio > 0 && ratio <= SERVED_EPS_RATIO_LIMIT && ratio >= 1 / SERVED_EPS_RATIO_LIMIT;
+}
+
+const finite = (value: number | null | undefined): value is number => typeof value === "number" && Number.isFinite(value);
+const positive = (value: number | null | undefined): value is number => finite(value) && value > 0;
+
+/**
+ * The financials with their headline trailing EPS and P/E on the filed
+ * quarters (filedTrailingEps): `fundamentals.eps` is that figure and
+ * `trailingPE` the quote's price over it, so every view that moves the P/E to
+ * the regular session price (atRegularSessionPrice, liveTrailingPE) reads the
+ * multiple PEB and GE read. Without one, Gloom Cloud's trailing EPS and P/E
+ * stand, marked `served`, as does a P/E it serves with no EPS (a fund's). A
+ * block with neither is left as it is.
+ */
+export function withFiledTrailingEps<T extends TrailingEpsInputs>(financials: T, now = Date.now()): T {
+  const fundamentals = financials.fundamentals;
+  if (!fundamentals) return financials;
+  const filed = filedTrailingEps(financials, now);
+  if (!filed) {
+    const served = finite(fundamentals.eps) || finite(fundamentals.trailingPE);
+    if (!served || (fundamentals.trailingEpsSource === "served" && fundamentals.trailingEpsPeriodEnd === undefined)) return financials;
+    const { trailingEpsPeriodEnd: _period, ...rest } = fundamentals;
+    return { ...financials, fundamentals: { ...rest, trailingEpsSource: "served" } };
+  }
+  const { trailingPEConversion: _conversion, epsCurrency: _currency, trailingPE: _served, ...rest } = fundamentals;
+  // filedTrailingEps reads a quote's currency, so there is a quote; its price is the one atRegularSessionPrice moves from.
+  const price = financials.quote!.price;
+  const next: Fundamentals = {
+    ...rest,
+    eps: filed.eps,
+    // A loss leaves no multiple: priceEarningsOnEarnings reads the EPS as not meaningful.
+    ...(positive(price) && filed.eps > 0 ? { trailingPE: price / filed.eps } : {}),
+    trailingEpsSource: "filed-quarters",
+    trailingEpsPeriodEnd: filed.periodEnd,
+  };
+  return { ...financials, fundamentals: next };
+}

package/src/time-series/forward-valuation.ts

@@ -9,6 +9,7 @@ import type { ValuationCurrencyContext } from "./valuation-currency";
 import { currentValuationPrice, valuationPriceAtOrBefore } from "./valuation-price";
 import type { TimeSeriesPoint } from "./types";
 import { isFiniteNumber } from "../utils/guards";
+import { dailyValuationHistory, type DailyValuationBasis } from "./daily-valuation";
 
 /**
  * Forward multiples over time. No source serves the consensus as it stood on
@@ -236,6 +237,37 @@ export function forwardPeHistory(
   return points;
 }
 
+/** Daily closes over consensus that was actually observed by that date. */
+export function dailyForwardPeHistory(
+  financials: TickerFinancials,
+  currencies: ValuationCurrencyContext,
+  exchange?: string,
+): TimeSeriesPoint[] {
+  const history = financials.epsEstimates;
+  if (!history) return [];
+  // Pre-report estimates from future quarters are final-vintage figures,
+  // not the forecasts investors had on an earlier day. Only dated snapshots
+  // establish a historical daily forward denominator.
+  const bases: DailyValuationBasis[] = [...snapshotsByDay(history.snapshots)].map(([day, periods]) => {
+    const current = periods.get("current year");
+    const next = periods.get("next year");
+    const eps = blendedNextTwelveMonthsEps(day,
+      current ? { periodEnd: current.periodEnd, eps: current.epsAverage } : undefined,
+      next ? { eps: next.epsAverage } : undefined);
+    const date = new Date(day);
+    return {
+      availableAt: day,
+      observedAt: date,
+      periodLabel: `Consensus observed ${day}`,
+      atPrice: (price: number) => {
+        const comparable = currencies.priceInStatementUnits({ date: day, currency: history.currency ?? financials.financialCurrency }, price);
+        return comparable !== null && eps !== null ? comparable / eps : null;
+      },
+    };
+  });
+  return dailyValuationHistory(financials.priceHistory, bases, financials.quote?.listingExchangeName || financials.quote?.exchangeName || exchange);
+}
+
 /** Price at each report date over the EPS reported in the following four quarters. */
 export function realizedNtmPeHistory(
   financials: TickerFinancials,

package/src/time-series/fundamentals.ts

@@ -8,7 +8,9 @@ import { fiscalPeriodLabel, fiscalYearEndMonth, ttmPeriodLabel } from "../utils/
 import { hasStatementGap, mergeStatementGaps } from "../utils/statement-gaps";
 import { trailingEpsAcrossFiscalYearEnd } from "../utils/trailing-eps";
 import { canonicalTimeSeriesFieldId, getTimeSeriesField } from "./field-catalog";
-import { forwardPeHistory, realizedNtmPeHistory } from "./forward-valuation";
+import { dailyForwardPeHistory, forwardPeHistory, realizedNtmPeHistory } from "./forward-valuation";
+import { dailyValuationHistory, type DailyValuationBasis } from "./daily-valuation";
+import { statementAtRelease } from "./valuation-releases";
 import { reportingCurrencySeries } from "./reporting-currency";
 import { createValuationCurrencyContext, type ValuationCurrencyContext } from "./valuation-currency";
 import { currentValuationPrice, valuationPriceAtOrBefore, valuationQuoteIssue, type ValuationPriceIssue } from "./valuation-price";
@@ -474,7 +476,7 @@ function buildTtmStatements(
       const availableAt = statementFieldAvailability(latest, field);
       if (availableAt) ttm.fieldAvailability![field] = availableAt;
     }
-    ttm.availableAt = completeStatementAvailability(ttm);
+    ttm.availableAt = completeStatementAvailability(ttm) ?? latest.availableAt;
     result.push(ttm);
   }
   return result;
@@ -490,7 +492,7 @@ function buildTtmStatements(
 export function knownWhenFiled(row: FinancialStatement): FinancialStatement {
   const filed = row.epsBasis?.status === "split-adjusted" ? row.epsBasis.originalFiled : undefined;
   if (!filed || !Number.isFinite(Date.parse(filed))) return row;
-  const current = row.fieldAvailability !== undefined ? row.fieldAvailability.eps : row.availableAt;
+  const current = statementFieldAvailability(row, "eps");
   if (current && Date.parse(current) <= Date.parse(filed)) return row;
   return { ...row, fieldAvailability: { ...row.fieldAvailability, eps: filed } };
 }
@@ -500,6 +502,56 @@ function valuationStatements(financials: TickerFinancials): { quarterly: Financi
   return { quarterly: financials.quarterlyStatements.map(knownWhenFiled), annual: financials.annualStatements.map(knownWhenFiled) };
 }
 
+/**
+ * A fiscal fourth quarter's EPS stated without a filing date of its own (a
+ * 10-K states the year, the results release the quarter) was public once its
+ * year's filing was, so it is dated by that filing. The daily P/E of the
+ * quarters after it then sums the same four quarters PEB and the headline EPS
+ * (TTM) sum (time-series/filed-trailing-eps), rather than reading the quarter
+ * from the year and landing a cent of rounding away from them. The window that
+ * ends with the year takes the year's own EPS (fiscalYearEpsAtYearEnd).
+ */
+function fourthQuarterEpsAtYearFiling(row: FinancialStatement, annual: readonly FinancialStatement[]): FinancialStatement {
+  if (!isFiniteNumber(row.eps) || hasStatementGap(row, "eps") || statementFieldAvailability(row, "eps")) return row;
+  const year = annual.find((candidate) => candidate.currency === row.currency && areNearbyFinancialPeriodEnds(candidate.date, row.date));
+  const filed = year && isFiniteNumber(year.eps) ? statementFieldAvailability(year, "eps") : undefined;
+  return filed ? { ...row, fieldAvailability: { ...row.fieldAvailability, eps: filed } } : row;
+}
+
+/**
+ * At a fiscal year end the filed year's diluted EPS is the daily trailing
+ * figure, as PEB and the headline EPS (TTM) read it (filed-trailing-eps): four
+ * quarters need not add up to their year (3.90 for the year beside four
+ * quarters of 1.00), so their sum stands only where the year gives no dated EPS.
+ */
+function fiscalYearEpsAtYearEnd(statements: readonly InternalStatement[], annual: readonly FinancialStatement[]): InternalStatement[] {
+  return statements.map((statement) => {
+    const year = annual.find((row) => row.currency === statement.currency && areNearbyFinancialPeriodEnds(row.date, statement.date));
+    const eps = year && !hasStatementGap(year, "eps") ? statementNumber(year, "eps") : null;
+    if (!year || eps === null) return statement;
+    const { epsBasis: _sum, ...rest } = statement;
+    const fieldAvailability = { ...statement.fieldAvailability };
+    const filed = statementFieldAvailability(year, "eps");
+    if (filed) fieldAvailability.eps = filed;
+    else delete fieldAvailability.eps;
+    const next: InternalStatement = {
+      ...rest, eps, fieldAvailability, ...(year.epsBasis ? { epsBasis: year.epsBasis } : {}),
+      __timeSeriesDerivedFields: [...new Set([...(statement.__timeSeriesDerivedFields ?? []), "eps" as const])],
+    };
+    next.availableAt = completeStatementAvailability(next) ?? statement.availableAt;
+    return next;
+  });
+}
+
+/** An undated vendor value cannot block a derivation from dated filings. */
+function datedValuationStatement(statement: FinancialStatement): FinancialStatement {
+  const dated = { ...statement };
+  for (const field of NUMERIC_STATEMENT_FIELDS) {
+    if (!statementFieldAvailability(statement, field)) delete dated[field];
+  }
+  return dated;
+}
+
 function normalizeFundamentalPeriod(period: SeriesPeriod | undefined): "annual" | "quarterly" | "ttm" | "auto" {
   return period === "annual" || period === "quarterly" || period === "ttm" ? period : "auto";
 }
@@ -508,12 +560,67 @@ function sourceStatements(
   financials: TickerFinancials,
   period: SeriesPeriod | undefined,
   valuationMetric?: string,
+  exchange?: string,
 ): { statements: InternalStatement[]; period: "annual" | "quarterly" | "ttm" } {
   const normalized = normalizeFundamentalPeriod(period);
-  const known = valuationMetric
+  let known = valuationMetric
     ? valuationStatements(financials)
     : { quarterly: financials.quarterlyStatements, annual: financials.annualStatements };
+  if (period === "daily" && valuationMetric) {
+    const releases = financials.earningsReleases ?? [];
+    const venue = financials.quote?.listingExchangeName || financials.quote?.exchangeName || exchange;
+    known = { quarterly: known.quarterly.map(row => statementAtRelease(row, releases, venue)),
+      annual: known.annual.map(row => statementAtRelease(row, releases, venue)) };
+    const annualRows = known.annual;
+    known = { ...known, quarterly: known.quarterly.map((row) => fourthQuarterEpsAtYearFiling(row, annualRows)) };
+    known = { quarterly: known.quarterly.map(datedValuationStatement), annual: known.annual.map(datedValuationStatement) };
+    // A later comparative quarter may repeat a year-end balance sheet that
+    // the annual filing already published. Only identical, same-currency
+    // snapshots can inherit that earlier evidence; changed values cannot.
+    known.quarterly = known.quarterly.map((statement) => {
+      const dated = { ...statement, fieldAvailability: Object.fromEntries(NUMERIC_STATEMENT_FIELDS.flatMap((field) => {
+        const availableAt = statementFieldAvailability(statement, field);
+        return availableAt ? [[field, availableAt]] : [];
+      })) };
+      for (const annual of known.annual) {
+        if (annual.currency !== dated.currency || !areNearbyFinancialPeriodEnds(annual.date, dated.date)) continue;
+        for (const field of QUARTERLY_SNAPSHOT_FIELDS) {
+          const value = statementNumber(dated, field);
+          const earlier = statementFieldAvailability(annual, field);
+          const current = statementFieldAvailability(dated, field);
+          if (value !== null && value === statementNumber(annual, field) && earlier
+            && (!current || Date.parse(earlier) < Date.parse(current))) {
+            dated.fieldAvailability[field] = earlier;
+          }
+        }
+      }
+      return dated;
+    });
+  }
   const quarterly = deriveQuarterlyStatements(known.quarterly, known.annual);
+  if (period === "daily" && valuationMetric) {
+    // Sparse or loss-making quarters are gaps, not permission to substitute
+    // an older annual denominator. Annual-only issuers retain their years.
+    if (!known.quarterly.length) return { statements: mergeStatementsByPeriod(known.annual), period: "annual" };
+    const statements = fiscalYearEpsAtYearEnd(buildTtmStatements(quarterly, known.annual), known.annual);
+    // Capitalization uses the latest reported share count, not an average
+    // of four quarters. Keep TTM average shares for the income/EPS fallback.
+    if (valuationMetric !== "trailingPE") for (const statement of statements) {
+      const latest = quarterly.find((row) => row.date === statement.date);
+      const year = known.annual.find((row) => areNearbyFinancialPeriodEnds(row.date, statement.date));
+      const shareRow = latest && selectedShares(latest) ? latest : year;
+      for (const field of ["dilutedShares", "basicShares", "ordinarySharesNumber", "shareIssued"] as const) {
+        delete statement[field];
+        delete statement.fieldAvailability?.[field];
+        if (shareRow?.[field] !== undefined) {
+          statement[field] = shareRow[field];
+          const availableAt = statementFieldAvailability(shareRow, field);
+          if (availableAt) (statement.fieldAvailability ??= {})[field] = availableAt;
+        }
+      }
+    }
+    return { statements, period: "ttm" };
+  }
   if (normalized === "annual") {
     return { statements: mergeStatementsByPeriod(known.annual), period: "annual" };
   }
@@ -727,7 +834,7 @@ function historicalValuation(
   currencies: ValuationCurrencyContext,
 ) {
   // A price failure cannot make absent financial inputs appear available.
-  if (currencies.priceInStatementUnits(statement, 1) === null || valuationAtPrice(statement, metric, 1) === null) return null;
+  if (currencies.priceInStatementUnits(statement, 1) === null || valuationAtPrice(statement, metric, 1, true) === null) return null;
   const priceDate = metricAvailability(statement, metric) ?? statement.date;
   const price = valuationPriceAtOrBefore(financials.priceHistory, priceDate);
   if (!price) return null;
@@ -754,6 +861,7 @@ function valuationAtPrice(
   statement: FinancialStatement,
   metric: string,
   price: number,
+  checkingInputs = false,
 ): number | null {
   const shares = selectedShares(statement);
   const marketCap = shares ? price * shares.value : null;
@@ -769,12 +877,83 @@ function valuationAtPrice(
     return eps && eps > 0 ? price / eps : null;
   }
   if (metric === "priceSales") return ratio(marketCap, statement.totalRevenue);
+  // The probe at price=1 checks input coverage, not the historical EV sign.
+  if (!checkingInputs && enterpriseValue !== null && enterpriseValue < 0 && (metric === "evSales" || metric === "evEbitda")) return null;
   if (metric === "evSales") return ratio(enterpriseValue, statement.totalRevenue);
   if (metric === "evEbitda") return ratio(enterpriseValue, statement.ebitda);
   if (metric === "priceFcf") return ratio(marketCap, freeCashFlow(statement).value);
   return null;
 }
 
+function dailyStatementValuation(financials: TickerFinancials, metric: string, exchange?: string): TimeSeriesPoint[] {
+  const earningsMetric = metric === "pegRatio" ? "trailingPE" : metric;
+  const selected = sourceStatements(financials, "daily", earningsMetric, exchange);
+  const currencies = createValuationCurrencyContext(financials);
+  const yearEndMonth = fiscalYearEndMonth(financials.annualStatements);
+  const bases: DailyValuationBasis[] = selected.statements.flatMap((statement) => {
+    const usable = valuationAtPrice(statement, earningsMetric, 1, true) !== null;
+    // Missing dates cannot put information at the period end: until its
+    // publication is known there is no historical denominator to use.
+    let publication = metricAvailability(statement, earningsMetric)
+      ?? (!usable ? statement.availableAt : undefined);
+    let growth: number | null = null;
+    if (metric === "pegRatio") {
+      const prior = selected.statements.find((candidate) => {
+        const days = (statementTime(statement) - statementTime(candidate)) / DAY_MS;
+        return days >= 330 && days <= 400;
+      });
+      const currentEps = selectedEps(statement)?.value;
+      const previousEps = prior ? selectedEps(prior)?.value : null;
+      if (prior && currentEps != null && currentEps > 0 && previousEps != null && previousEps > 0) {
+        publication = completeAvailability([publication, metricAvailability(prior, "trailingPE")]);
+        const change = (currentEps / previousEps - 1) * 100;
+        if (change > 0) growth = change;
+      }
+    }
+    const observedAt = validDate(statement.date);
+    if (!observedAt) return [];
+    const availableAt = validDate(publication);
+    if (availableAt && availableAt < observedAt) publication = undefined;
+    const point = pointForStatement(statement, earningsMetric, null, selected.period, "available-at", true, yearEndMonth);
+    return [{
+      availableAt: publication,
+      observedAt,
+      periodLabel: point?.periodLabel,
+      atPrice: (price: number) => {
+        // An undated newer period must stop the previous TTM from continuing.
+        // Its period end only bounds the gap; it never publishes a value.
+        if (!publication || !availableAt) return null;
+        const comparable = currencies.priceInStatementUnits(statement, price);
+        if (comparable === null) return null;
+        const value = valuationAtPrice(statement, earningsMetric, comparable);
+        // Negative cash flow, revenue or EBITDA cannot produce a meaningful
+        // multiple. Explicit period views retain their historical behavior.
+        const denominator = earningsMetric === "priceFcf" ? freeCashFlow(statement).value
+          : earningsMetric === "evEbitda" ? statement.ebitda
+            : earningsMetric === "priceSales" || earningsMetric === "evSales" ? statement.totalRevenue : 1;
+        if (denominator == null || denominator <= 0 || value === null) return null;
+        return metric === "pegRatio" ? growth === null ? null : value / growth : value;
+      },
+    }];
+  });
+  const points = dailyValuationHistory(financials.priceHistory, bases, financials.quote?.listingExchangeName || financials.quote?.exchangeName || exchange);
+  return points.some((point) => point.value !== null) ? points : [];
+}
+
+/** A daily history cannot be dated at all, but the issuer still has reported figures. */
+export function dailyValuationFallbackPeriod(financials: TickerFinancials, source: SecuritySeriesSource): "annual" | "quarterly" | "ttm" | null {
+  if (source.period !== "daily") return null;
+  const [namespace, metric = ""] = canonicalTimeSeriesFieldId(source.fieldId).split(".");
+  const inputMetric = metric === "pegRatio" ? "trailingPE" : metric;
+  if (namespace !== "valuation" || !QUOTE_DERIVED_VALUATION_IDS.has(inputMetric)) return null;
+  const daily = sourceStatements(financials, "daily", inputMetric, source.instrument.exchange);
+  if (daily.statements.some(row => metricAvailability(row, inputMetric))) return null;
+  const annual = sourceStatements(financials, "annual", inputMetric);
+  if (annual.statements.some(row => valuationAtPrice(row, inputMetric, 1, true) !== null)) return "annual";
+  const reported = sourceStatements(financials, "auto", inputMetric);
+  return reported.statements.some(row => valuationAtPrice(row, inputMetric, 1, true) !== null) ? reported.period : null;
+}
+
 function providerCurrentValuationPoint(
   financials: TickerFinancials,
   metric: string,
@@ -887,9 +1066,9 @@ export function valuationSeriesUsesLiveQuote(fieldId: string): boolean {
 }
 
 /** Whether a valuation field needs the full price history to date its observations. */
-export function valuationSeriesUsesPriceHistory(fieldId: string): boolean {
+export function valuationSeriesUsesPriceHistory(fieldId: string, period?: SeriesPeriod): boolean {
   const [namespace, metric = ""] = canonicalTimeSeriesFieldId(fieldId).split(".");
-  return namespace === "valuation" && PRICE_HISTORY_VALUATION_IDS.has(metric);
+  return namespace === "valuation" && (PRICE_HISTORY_VALUATION_IDS.has(metric) || (metric === "pegRatio" && period === "daily"));
 }
 
 function preferredPeriodPoint(
@@ -983,6 +1162,15 @@ export function extractFundamentalSeries(
   }
 
   if (namespace !== "valuation" || !VALUATION_IDS.has(metric)) return [];
+  const fallback = dailyValuationFallbackPeriod(financials, source);
+  if (fallback) return extractFundamentalSeries(financials, { ...source, period: fallback });
+  if (source.period === "daily" && metric !== "realizedNtmPE") {
+    if (metric !== "forwardPE") return dailyStatementValuation(financials, metric, source.instrument.exchange);
+    const points = dailyForwardPeHistory(financials, createValuationCurrencyContext(financials), source.instrument.exchange);
+    if (points.some((point) => point.value !== null)) return points;
+    const current = providerCurrentValuationPoint(financials, metric);
+    return current ? [current] : [];
+  }
   if (metric === "forwardPE") {
     const points = forwardPeHistory(financials, createValuationCurrencyContext(financials));
     if (points.length > 0) return points;
@@ -1066,6 +1254,9 @@ export function valuationCurrencyWarning(financials: TickerFinancials, source: S
 
 /** Structured failures preserve source values independently of the chart's ratios. */
 export function valuationPriceIssues(financials: TickerFinancials, source: SecuritySeriesSource): ValuationPriceIssue[] {
+  if (source.period === "daily" && canonicalTimeSeriesFieldId(source.fieldId).startsWith("valuation.")) {
+    return extractFundamentalSeries(financials, source).flatMap((point) => point.provenance?.valuationPriceIssues ?? []);
+  }
   if (!valuationSeriesUsesLiveQuote(source.fieldId)) return [];
   const metric = canonicalTimeSeriesFieldId(source.fieldId).split(".")[1]!;
   const currencies = createValuationCurrencyContext(financials);

package/src/time-series/hooks.ts

@@ -79,6 +79,7 @@ export function useResolvedChartSpec(
   const sources = useMemo(() => ({
     dataProvider,
     loadFredSeries: loadFred,
+    loadEarningsHistory: (symbol: string) => apiClient.getCloudEarningsHistory(symbol, 100),
     resolveCapabilitySeries: createChartSeriesResolver(capabilityInvoker),
     capabilityRefreshMs: registeredSeriesRefreshMs,
     loadFuturesPriceUnit: (symbol: string) => loadFuturesPriceUnit(symbol),

package/src/time-series/ice-credit.ts

@@ -17,6 +17,9 @@ export interface IceCreditSeries {
   tags: readonly string[];
 }
 
+/** What every surface that shows an ICE series says about how far back FRED carries it. */
+export const ICE_HISTORY_LIMIT_NOTICE = "History limited to 3 years by the publisher.";
+
 const HIGH_YIELD = ["high yield", "junk"];
 
 export const ICE_CREDIT_SERIES: readonly IceCreditSeries[] = [

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

@@ -10,6 +10,19 @@ import {
 } from "../market-data/market/period-return";
 
 const PRICE_COMPARISON_BASIS = "Price returns in each listing's currency; cash distributions and FX conversion excluded.";
+const TOTAL_COMPARISON_BASIS = "Total returns in each listing's currency; cash distributions reinvested at the ex-date close, FX conversion excluded.";
+
+/**
+ * What a comparison's returns are: price returns, or total returns when the
+ * chart asked for them, naming any leg whose distributions could not be read
+ * (it stays a price return, and the others do not wait for it).
+ */
+function comparisonBasis(spec: ChartSpec, legs: ReadonlyArray<{ label: string; entry: ResolvedSeries | undefined }>): string {
+  if (spec.viewport.totalReturn !== true) return PRICE_COMPARISON_BASIS;
+  const priceOnly = legs.filter(({ entry }) => entry?.returnBasis === "price").map(({ label }) => label);
+  if (priceOnly.length === legs.length && legs.length > 0) return PRICE_COMPARISON_BASIS;
+  return priceOnly.length ? `${TOTAL_COMPARISON_BASIS} Price return for ${priceOnly.join(", ")}: distribution history unavailable.` : TOTAL_COMPARISON_BASIS;
+}
 
 export interface PriceComparison {
   seriesIds: string[];
@@ -111,6 +124,20 @@ export function priceComparisonSeriesIds(spec: ChartSpec): string[] | null {
   return visible.map((entry) => entry.id);
 }
 
+/**
+ * What a total-return chart's price levels are when it is not a comparison (the
+ * raw price axis): prices with cash distributions reinvested, not what the
+ * listing quotes. Null for a price chart, and when no leg is a total return.
+ */
+export function totalReturnLevelsNotice(spec: ChartSpec, series: readonly ResolvedSeries[]): string | null {
+  if (spec.viewport.totalReturn !== true) return null;
+  const legs = series.filter((entry) => entry.returnBasis !== undefined);
+  if (!legs.some((entry) => entry.returnBasis === "total")) return null;
+  const priceOnly = legs.filter((entry) => entry.returnBasis === "price").map((entry) => entry.label);
+  return `Total return levels in each listing's currency: prices include cash distributions reinvested at the ex-date close, so they are not quoted prices; FX conversion excluded.${
+    priceOnly.length ? ` Price only for ${priceOnly.join(", ")}: distribution history unavailable.` : ""}`;
+}
+
 interface ComparedLeg {
   id: string;
   label: string;
@@ -152,7 +179,8 @@ export function resolvePriceComparison(
     return source?.kind === "security" ? source.instrument.symbol : id;
   };
   // A leg not loaded yet (a seed from cached history) has not failed: nothing compares until it is.
-  const unavailable = `${PRICE_COMPARISON_BASIS} Comparison unavailable: need two shared dates and a nonzero baseline.`;
+  const basis = comparisonBasis(spec, seriesIds.map((id) => ({ label: symbolOf(id), entry: byId.get(id) })));
+  const unavailable = `${basis} Comparison unavailable: need two shared dates and a nonzero baseline.`;
   if (seriesIds.some((id) => !byId.has(id))) return { seriesIds, start: null, end: null, notice: unavailable };
   const dropped: NonNullable<PriceComparison["dropped"]> = [];
   const reported = new Set<string>();
@@ -259,7 +287,7 @@ export function resolvePriceComparison(
     sourceBounds,
     legs: legDays,
     ...(dropped.length ? { dropped } : {}),
-    notice: `${PRICE_COMPARISON_BASIS} ${span}${droppedText}`,
+    notice: `${basis} ${span}${droppedText}`,
   };
 }