gloomberb 0.18.2 → 0.18.4

package/src/time-series/chart-bounds.ts

@@ -0,0 +1,349 @@
+import {
+  getTimeRangeForDateWindow,
+  isDateWindowWithinTimeRange,
+  subtractTimeRange,
+} from "./date-window";
+import {
+  chartBarSizeSource,
+  chartBarSizeStepMs,
+  getBestSupportedResolutionForVisibleWindow,
+  getNextBufferRange,
+  getSupportedPresetResolution,
+  getSupportMaxRange,
+  type ChartBarSize,
+  type ChartResolutionSupport,
+  type ManualChartResolution,
+} from "./resolution";
+import { TIME_RANGES, type TimeRange } from "./range";
+import { maxStudyWarmupPoints } from "./studies";
+import type { PriceComparison } from "./price-comparison";
+import { resolutionForExplicitMarketPeriods } from "./market-resolution";
+import { latestSessionStart, latestTradingSessionOpen, priorSessionClose } from "../market-data/market/trading-sessions";
+import type {
+  ChartSpec,
+  ResolvedSeries,
+  TimeSeriesPoint,
+} from "./types";
+import type { ChartResolveOptions } from "./resolve-context";
+
+export interface DateBounds {
+  start: number | null;
+  /** Inclusive upper bound. */
+  end: number | null;
+}
+
+export const DAY_MS = 24 * 60 * 60 * 1_000;
+const DATE_ONLY_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+
+export function finiteDate(value: string | Date | undefined): Date | null {
+  if (!value) return null;
+  const date = value instanceof Date ? new Date(value) : new Date(value);
+  return Number.isFinite(date.getTime()) ? date : null;
+}
+
+function inclusiveEndDate(value: string | Date | undefined): Date | null {
+  const parsed = finiteDate(value);
+  if (!parsed) return null;
+  return typeof value === "string" && DATE_ONLY_PATTERN.test(value.trim())
+    ? new Date(parsed.getTime() + DAY_MS - 1)
+    : parsed;
+}
+
+export function dateOnly(date: Date): string {
+  return date.toISOString().slice(0, 10);
+}
+
+export function explicitBounds(spec: ChartSpec): DateBounds | null {
+  const explicitStart = finiteDate(spec.viewport.dateWindow?.start);
+  const explicitEnd = inclusiveEndDate(spec.viewport.dateWindow?.end);
+  if (!explicitStart || !explicitEnd || explicitStart.getTime() > explicitEnd.getTime()) return null;
+  return { start: explicitStart.getTime(), end: explicitEnd.getTime() };
+}
+
+/** Calendar range limits use the authored dates; observation filters include the final day. */
+export function rangeDurationBounds(spec: ChartSpec, bounds: DateBounds): DateBounds {
+  const window = spec.viewport.dateWindow;
+  if (!window || !DATE_ONLY_PATTERN.test(window.start) || !DATE_ONLY_PATTERN.test(window.end)
+    || bounds.end !== inclusiveEndDate(window.end)?.getTime()) return bounds;
+  return { ...bounds, end: finiteDate(window.end)!.getTime() };
+}
+
+export function requestedBounds(spec: ChartSpec, latestObservation: Date): DateBounds {
+  const explicit = explicitBounds(spec);
+  if (explicit) return explicit;
+  return {
+    start: spec.viewport.range === "ALL"
+      ? null
+      : subtractTimeRange(latestObservation, spec.viewport.range).getTime(),
+    end: latestObservation.getTime(),
+  };
+}
+
+export function runtimeAutoBounds(options: ChartResolveOptions): DateBounds | null {
+  const start = options.autoViewport?.start.getTime();
+  const end = options.autoViewport?.end.getTime();
+  return typeof start === "number"
+      && Number.isFinite(start)
+      && typeof end === "number"
+      && Number.isFinite(end)
+      && start <= end
+    ? { start, end }
+    : null;
+}
+
+export function runtimeRequestBounds(options: ChartResolveOptions): DateBounds | null {
+  const start = options.requestViewport?.start.getTime();
+  const end = options.requestViewport?.end.getTime();
+  return typeof start === "number"
+      && Number.isFinite(start)
+      && typeof end === "number"
+      && Number.isFinite(end)
+      && start <= end
+    ? { start, end }
+    : null;
+}
+
+export function sameBounds(left: DateBounds | null, right: DateBounds | null): boolean {
+  return left?.start === right?.start && left?.end === right?.end;
+}
+
+function boundsRange(bounds: DateBounds): TimeRange {
+  if (bounds.start === null || bounds.end === null) return "ALL";
+  return getTimeRangeForDateWindow({
+    start: new Date(bounds.start),
+    end: new Date(bounds.end),
+  });
+}
+
+export function requestResolution(
+  spec: ChartSpec,
+  bounds: DateBounds,
+  calculationSeriesIds: ReadonlySet<string>,
+  options: ChartResolveOptions,
+  sharedSupport: readonly ChartResolutionSupport[],
+  provisionalSupport = false,
+  /** When a futures listing's sessions open, which its built bars' source bars must divide (`chartBarSizeSource`). */
+  openMinute: number | null = null,
+): ManualChartResolution {
+  const duration = rangeDurationBounds(spec, bounds);
+  if (spec.viewport.resolution === "auto" && spec.studies.some((study) => study.kind === "realized-vol" && study.visible !== false)) {
+    // A 252-session estimator must see daily observations even on a long chart.
+    const maxRange = getSupportMaxRange(sharedSupport, "1d");
+    if (sharedSupport.length === 0 || provisionalSupport || maxRange === "ALL"
+      || (maxRange !== null && duration.start !== null && duration.end !== null
+        && isDateWindowWithinTimeRange(new Date(duration.start), new Date(duration.end), maxRange))) return "1d";
+  }
+  if (spec.viewport.resolution !== "auto") {
+    // A bar size the source does not serve is built from one it does, which must reach back far enough.
+    const source = chartBarSizeSource(spec.viewport.resolution, provisionalSupport ? [] : sharedSupport, openMinute);
+    const maxRange = getSupportMaxRange(sharedSupport, source);
+    // A placeholder list cannot rule out a manual pick; the real list decides
+    // on the next pass.
+    const supported = sharedSupport.length === 0
+      || provisionalSupport
+      || maxRange === "ALL"
+      || (
+        maxRange !== null
+        && duration.start !== null
+        && duration.end !== null
+        && isDateWindowWithinTimeRange(
+          new Date(duration.start),
+          new Date(duration.end),
+          maxRange,
+        )
+      );
+    if (supported) return source;
+  }
+  const runtimeBounds = runtimeAutoBounds(options);
+  const adaptive = runtimeBounds && runtimeBounds.start !== null && runtimeBounds.end !== null
+    ? getBestSupportedResolutionForVisibleWindow(
+        { start: new Date(runtimeBounds.start), end: new Date(runtimeBounds.end) },
+        sharedSupport,
+        options.targetPointCount ?? 120,
+        options.currentResolution,
+      )
+    : null;
+  const preferred = adaptive
+    ?? getSupportedPresetResolution(
+      explicitBounds(spec) ? boundsRange(duration) : spec.viewport.range,
+      provisionalSupport ? [] : sharedSupport,
+      duration.start !== null && duration.end !== null
+        ? { start: new Date(duration.start), end: new Date(duration.end) }
+        : null,
+    );
+  const activeSeries = spec.series.filter((entry) => calculationSeriesIds.has(entry.id));
+  return resolutionForExplicitMarketPeriods(preferred, activeSeries);
+}
+
+export function calculationBounds(
+  spec: ChartSpec,
+  visibleBounds: DateBounds,
+  resolution: ChartBarSize,
+): DateBounds {
+  if (visibleBounds.start === null) return visibleBounds;
+  const warmupPoints = maxStudyWarmupPoints(spec.studies);
+
+  const duration = rangeDurationBounds(spec, visibleBounds);
+  const visibleEnd = duration.end ?? visibleBounds.start;
+  const bufferedRange = getNextBufferRange(boundsRange(duration));
+  let start = bufferedRange === "ALL"
+    ? subtractTimeRange(new Date(visibleEnd), "ALL").getTime()
+    : subtractTimeRange(new Date(visibleEnd), bufferedRange).getTime();
+
+  if (warmupPoints > 0) {
+    // Calendar gaps and closed sessions mean N observations often span more
+    // than N nominal bars. The doubled point window is a bounded safety margin.
+    const pointWarmup = warmupPoints * chartBarSizeStepMs(resolution) * 2;
+    start = Math.min(start, visibleBounds.start - pointWarmup);
+  }
+  return { start: Math.min(start, visibleBounds.start), end: visibleBounds.end };
+}
+
+/**
+ * How far past a view moved into the past its history reaches: half a view,
+ * as far as the interval's longest window allows with the view still in it.
+ * Those are the bars a pan forward meets first. Without them, a view whose
+ * bars were loaded for it alone (a zoom to finer bars, then a pan) ends where
+ * they do, and a pan forward stops there with nothing to ask for.
+ */
+export function barsAhead(view: DateBounds, maxRange: TimeRange | null, now: number): number {
+  if (view.start === null || view.end === null || view.end >= now) return 0;
+  const room = maxRange && maxRange !== "ALL"
+    ? view.start - subtractTimeRange(new Date(view.end), maxRange).getTime()
+    : Number.POSITIVE_INFINITY;
+  return Math.max(0, Math.min((view.end - view.start) / 2, room, now - view.end));
+}
+
+export function trailingRangeForStart(start: number | null, referenceDate: Date): TimeRange {
+  if (start === null) return "ALL";
+  for (const range of TIME_RANGES) {
+    if (range === "ALL" || start >= subtractTimeRange(referenceDate, range).getTime()) return range;
+  }
+  return "ALL";
+}
+
+export function exclusiveEnd(bounds: DateBounds): Date | null {
+  return bounds.end === null ? null : new Date(bounds.end + 1);
+}
+
+export function filterPoints(points: readonly TimeSeriesPoint[], bounds: DateBounds): TimeSeriesPoint[] {
+  return points.filter((point) => {
+    const time = point.date.getTime();
+    return Number.isFinite(time)
+      && (bounds.start === null || time >= bounds.start)
+      && (bounds.end === null || time <= bounds.end);
+  });
+}
+
+export function comparisonDisplayBounds(bounds: DateBounds, comparison: PriceComparison | null): DateBounds {
+  if (!comparison || comparison.start === null || comparison.end === null) return bounds;
+  // A date-only selection can include a local session that began on the prior
+  // UTC day, and a preset range's base close can be before its window (a month
+  // before a Monday is a Sunday, so the Friday). Keep both visible.
+  return {
+    start: bounds.start === null ? null : Math.min(bounds.start, comparison.start),
+    end: bounds.end === null ? null : Math.max(bounds.end, comparison.end),
+  };
+}
+
+/**
+ * An untouched market chart ends at its newest bar. A quote that arrives just
+ * after the reference time moves it on; a closed market (a night, a weekend)
+ * moves it back, so the plot does not end in an empty stretch that the first
+ * pan would then collapse.
+ */
+export function followLatestMarketObservation(
+  bounds: DateBounds,
+  series: readonly ResolvedSeries[],
+): DateBounds {
+  if (bounds.end === null) return bounds;
+  let latest = Number.NEGATIVE_INFINITY;
+  for (const entry of series) {
+    if (entry.timeBasis?.kind !== "market") continue;
+    for (const point of entry.points) {
+      const timestamp = point.date.getTime();
+      if (Number.isFinite(timestamp) && timestamp > latest) latest = timestamp;
+    }
+  }
+  if (!Number.isFinite(latest) || latest === bounds.end) return bounds;
+  const shift = latest - bounds.end;
+  return {
+    start: bounds.start === null ? null : bounds.start + shift,
+    end: latest,
+  };
+}
+
+/**
+ * The dates a capability series (CHOKE's transits) is asked for. A view the
+ * user panned or zoomed keeps the range's dates loaded too: the chart's
+ * navigation stops at the newest observation it has, so a series asked for
+ * the moved view alone ended where the view did, and the view could never go
+ * forward to the newest data again, not even by zooming out.
+ */
+export function capabilityRequestBounds(view: DateBounds, range: DateBounds, moved: boolean): DateBounds {
+  if (!moved) return view;
+  return {
+    start: view.start === null || range.start === null ? null : Math.min(view.start, range.start),
+    end: view.end === null || range.end === null ? null : Math.max(view.end, range.end),
+  };
+}
+
+/**
+ * A chart of capability series alone (CHOKE's vessel transits) ends at its
+ * newest observation, not today: such data is published days late, and an
+ * axis running on to today would read as days with nothing in them. The
+ * start stays where the range put it, so no empty span opens on the left.
+ */
+export function endAtNewestObservation(bounds: DateBounds, series: readonly ResolvedSeries[]): DateBounds {
+  if (bounds.end === null) return bounds;
+  let newest = Number.NEGATIVE_INFINITY;
+  for (const entry of series) {
+    for (const point of entry.points) {
+      const timestamp = point.date.getTime();
+      if (point.value !== null && Number.isFinite(timestamp) && timestamp > newest) newest = timestamp;
+    }
+  }
+  if (!Number.isFinite(newest) || newest >= bounds.end || (bounds.start !== null && newest <= bounds.start)) return bounds;
+  return { start: bounds.start, end: newest };
+}
+
+/**
+ * 1D shows the latest trading session of the chart's first market listing,
+ * from its open to the newest bar, with the close before it as a reference.
+ * Null keeps the rolling day: crypto, FX and venues without known hours.
+ * The reference is the quote's previous close when the quote is from the
+ * session shown, as the legend's change is; otherwise the last bar of the
+ * session before.
+ */
+export function latestSessionView(
+  primary: ResolvedSeries | undefined,
+  marketSeries: readonly ResolvedSeries[],
+  extendedHours: boolean,
+  quoteReference: { close: number; time: number } | undefined,
+): { bounds: DateBounds; priorClose: number | null } | null {
+  if (!primary?.listing) return null;
+  const bars = primary.points.flatMap((point) => {
+    const close = point.close ?? point.value;
+    const time = point.date.getTime();
+    return typeof close === "number" && Number.isFinite(close) && Number.isFinite(time) ? [{ time, close }] : [];
+  });
+  const latest = bars.at(-1)?.time;
+  if (latest === undefined) return null;
+  const { symbol, exchange } = primary.listing;
+  const open = latestSessionStart(symbol, exchange, latest, { extendedHours });
+  if (open === null) return null;
+  // The axis starts at the session's first bar, which a quiet pre-market can leave well after the open.
+  const start = bars.find((bar) => bar.time >= open)?.time ?? open;
+  // Another listing on the chart can trade later than the primary one.
+  let end = latest;
+  for (const entry of marketSeries) {
+    const last = entry.points.at(-1)?.date.getTime();
+    if (last !== undefined && Number.isFinite(last) && last > end) end = last;
+  }
+  const regularOpen = latestTradingSessionOpen(symbol, exchange, latest);
+  const quoteOpen = quoteReference ? latestTradingSessionOpen(symbol, exchange, quoteReference.time) : null;
+  const priorClose = quoteReference && regularOpen !== null && quoteOpen === regularOpen
+    ? quoteReference.close
+    : priorSessionClose(bars, open, symbol, exchange);
+  return { bounds: { start, end }, priorClose };
+}

package/src/time-series/chart-seed.ts

@@ -0,0 +1,142 @@
+import { limitSeriesObservations } from "./financial-period-coverage";
+import {
+  chartBarSizeSource,
+  intersectChartResolutionSupport,
+  isCustomChartResolution,
+  type ChartResolutionSupport,
+  type ManualChartResolution,
+} from "./resolution";
+import { aggregatePriceBars, futuresOpenMinuteOf, withBuiltBarSize } from "./bar-aggregation";
+import type { TickerFinancials } from "../types/financials";
+import { isMarketFieldId } from "./field-catalog";
+import { chartPriceHistoryIntegrityNotices } from "./market";
+import { resolveStudies } from "./studies";
+import { clipSeriesToWindow } from "./alignment";
+import { bufferPriceComparison, clipPriceComparison, priceComparisonBoundsForSeries, resolvePriceComparison } from "./price-comparison";
+import { readSeedListingFacts } from "./parsed-history-cache";
+import { getPricePointTimestamp } from "../utils/price-history";
+import type {
+  ChartResolutionResult,
+  ChartSpec,
+  ResolvedSeries,
+} from "./types";
+import { type ChartResolveOptions, instrumentKey } from "./resolve-context";
+import {
+  explicitBounds,
+  requestedBounds,
+  runtimeRequestBounds,
+  requestResolution,
+  filterPoints,
+  comparisonDisplayBounds,
+  followLatestMarketObservation,
+  latestSessionView,
+} from "./chart-bounds";
+import { emptyFinancials, chartCalculationSeriesIds, baseSecuritySeries } from "./base-series";
+import {
+  resolvePriceHistoryIntegrity,
+  assignAxes,
+  prepareBaseSeriesForStudies,
+  presentationBounds,
+  applyStudyPresentationTransforms,
+  studyAnchors,
+} from "./series-presentation";
+
+/** Select the provisional seed cadence before provider resolution support arrives. */
+function seedOpenMinute(spec: ChartSpec): number | null {
+  return futuresOpenMinuteOf(spec.series.flatMap((entry) => (
+    entry.source.kind === "security" && isMarketFieldId(entry.source.fieldId) ? [entry.source.instrument] : []
+  )));
+}
+
+export function chartSeedResolution(spec: ChartSpec, now: Date, options: ChartResolveOptions = {}): ManualChartResolution {
+  return requestResolution(spec, requestedBounds(spec, now), chartCalculationSeriesIds(spec), options, [], false, seedOpenMinute(spec));
+}
+
+export function seedChartResolutionResult(
+  spec: ChartSpec,
+  historyByInstrument: ReadonlyMap<string, TickerFinancials["priceHistory"]>,
+  referenceNow?: Date,
+  options: ChartResolveOptions = {},
+): ChartResolutionResult | null {
+  let latest = Number.NEGATIVE_INFINITY;
+  for (const history of historyByInstrument.values()) {
+    for (const point of history) latest = Math.max(latest, getPricePointTimestamp(point));
+  }
+  if (!Number.isFinite(latest)) return null;
+  const now = referenceNow ?? new Date(latest);
+  const resolution = chartSeedResolution(spec, now, options);
+  // A size the source does not serve is built from its bars, as the settled chart builds it.
+  const builtBarSize = isCustomChartResolution(spec.viewport.resolution)
+    && resolution === chartBarSizeSource(spec.viewport.resolution, [], seedOpenMinute(spec)) ? spec.viewport.resolution : null;
+  // The seed is replaced by the settled chart moments later. Draw it with
+  // what that chart will know (units, served cadence, where its axis ends) so
+  // the swap changes no label and moves no plot.
+  const support: ChartResolutionSupport[][] = [];
+  const series: ResolvedSeries[] = [];
+  spec.series.forEach((seriesSpec, index) => {
+    if (seriesSpec.visible === false || seriesSpec.source.kind !== "security") return;
+    if (!isMarketFieldId(seriesSpec.source.fieldId)) return;
+    const history = historyByInstrument.get(instrumentKey(seriesSpec.source));
+    if (!history?.length) return;
+    const facts = readSeedListingFacts(seriesSpec.source.instrument);
+    const { symbol, exchange } = seriesSpec.source.instrument;
+    const bars = builtBarSize ? aggregatePriceBars(history, builtBarSize, { symbol, exchange }) : history;
+    const base = baseSecuritySeries(seriesSpec, emptyFinancials(bars), index, resolution, facts?.quoteMetadata, facts?.contractUnit);
+    const resolved = base && builtBarSize ? withBuiltBarSize(base, builtBarSize) : base;
+    if (!resolved?.points.length) return;
+    series.push(resolved);
+    if (facts?.resolutionSupport?.length) support.push(facts.resolutionSupport);
+  });
+  if (series.length === 0) return null;
+  const requested = requestedBounds(spec, now);
+  const sessionView = spec.viewport.range === "1D" && !explicitBounds(spec)
+    ? latestSessionView(series[0], series, spec.viewport.extendedHours === true, undefined)
+    : null;
+  const bounds = explicitBounds(spec) || runtimeRequestBounds(options)
+    ? requested
+    : sessionView?.bounds ?? followLatestMarketObservation(requested, series);
+  const primary = series[0]!;
+  if (sessionView?.priorClose != null && primary.transform === "raw"
+    && primary.unitGroup.startsWith("price") && primary.unitGroup !== "price:unknown") {
+    series[0] = { ...primary, priorClose: sessionView.priorClose };
+  }
+  const resolutionSupport = support.length === series.length ? intersectChartResolutionSupport(support) : [];
+  const priceComparison = resolvePriceComparison(spec, series, bounds, resolution, spec.viewport.dateWindow,
+    { preset: explicitBounds(spec) || runtimeRequestBounds(options) ? null : spec.viewport.range, now: referenceNow?.getTime() ?? Date.now() });
+  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, resolution, undefined, studyAnchors(series, priceComparison, comparisonBounds));
+  const axisWarnings: string[] = [];
+  const bufferedSeries = assignAxes([
+    ...baseSeries,
+    ...applyStudyPresentationTransforms(studies.series, spec.studies, series, comparisonBounds, undefined, priceComparison, bounds),
+  ], [...spec.series, ...spec.studies], axisWarnings).map((entry) => bufferPriceComparison(entry, priceComparison, bounds));
+  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: visible,
+    ...(priceHistoryIntegrity.length ? { priceHistoryIntegrity } : {}),
+    ...(priceComparison ? { priceComparison } : {}),
+    ...(resolutionSupport.length > 0 ? { resolutionSupport } : {}),
+    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, ...axisWarnings, ...chartPriceHistoryIntegrityNotices(priceHistoryIntegrity), ...(priceComparison ? [priceComparison.notice] : [])],
+    resolution,
+    ...(builtBarSize ? { barSize: builtBarSize } : {}),
+  };
+}

package/src/time-series/economic.ts

@@ -43,6 +43,8 @@ export interface FredObservationLike {
   value: string | number | null;
   realtime_start?: string;
   realtimeStart?: string;
+  /** The day the value was released, which Gloom Cloud sets on a series' newest observation. */
+  releasedOn?: string;
 }
 
 export interface FredExtractionOptions {
@@ -71,10 +73,13 @@ export function extractFredSeries(
         : Number.NaN;
     if (!observedAt || !Number.isFinite(numericValue)) continue;
     const availableAt = parsedDate(observation.realtime_start ?? observation.realtimeStart);
+    // One observation's release is not a vintage: the series stays drawn by period, and the line says when it was released.
+    const releasedOn = parsedDate(observation.releasedOn)?.toISOString().slice(0, 10);
     points.push({
       date: options.timestampMode !== "period-end" && availableAt ? availableAt : observedAt,
       observedAt,
       availableAt: availableAt ?? undefined,
+      ...(releasedOn ? { releasedOn } : {}),
       value: numericValue,
       periodLabel: observation.date,
       provenance: {

package/src/time-series/fundamentals.ts

@@ -6,6 +6,7 @@ import { areNearbyFinancialPeriodEnds, completeAvailability, statementFieldAvail
 import { copyIncomeField, incomeFieldKnowledgeDate, incomeFieldOwner, isIncomeStatementField } from "../utils/income-statement";
 import { fiscalPeriodLabel, fiscalYearEndMonth, ttmPeriodLabel } from "../utils/fiscal-period";
 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 { reportingCurrencySeries } from "./reporting-currency";
@@ -72,6 +73,7 @@ const QUARTERLY_SNAPSHOT_FIELDS: readonly NumericStatementField[] = [
 const QUARTERLY_AVERAGE_FIELDS: readonly NumericStatementField[] = ["basicShares", "dilutedShares"];
 // Reported common-income allocations and EPS may be summed for TTM, but
 // independently determined annual values cannot establish a missing quarter.
+// A trailing year across a fiscal Q4 without EPS reads that year's own EPS.
 const TTM_SUM_FIELDS: readonly NumericStatementField[] = [...QUARTERLY_FLOW_FIELDS, "netIncomeCommonStockholders", "eps"];
 
 const NUMERIC_STATEMENT_FIELDS: readonly NumericStatementField[] = [
@@ -398,8 +400,12 @@ export function deriveQuarterlyStatements(
   return mergeStatementsByPeriod([...byDate.values()]);
 }
 
-function buildTtmStatements(statements: readonly FinancialStatement[]): InternalStatement[] {
+function buildTtmStatements(
+  statements: readonly FinancialStatement[],
+  annualStatements: readonly FinancialStatement[],
+): InternalStatement[] {
   const sorted = mergeStatementsByPeriod(statements);
+  const annual = mergeStatementsByPeriod(annualStatements);
   const result: InternalStatement[] = [];
   for (let index = 3; index < sorted.length; index += 1) {
     const window = sorted.slice(index - 3, index + 1);
@@ -451,6 +457,15 @@ function buildTtmStatements(statements: readonly FinancialStatement[]): Internal
       )));
       if (availableAt) ttm.fieldAvailability![field] = availableAt;
     }
+    // A fiscal Q4 the 10-K reports only inside its year: the year's EPS plus the quarters since, less the same quarters a year earlier.
+    const acrossYearEnd = statementNumber(ttm, "eps") === null && !unresolvedEps
+      ? trailingEpsAcrossFiscalYearEnd(window, sorted, annual, "eps") : null;
+    if (acrossYearEnd) {
+      ttm.eps = acrossYearEnd.value;
+      ttm.__timeSeriesDerivedFields!.push("eps");
+      const availableAt = completeAvailability(acrossYearEnd.inputs.map((statement) => statementFieldAvailability(statement, "eps")));
+      if (availableAt) ttm.fieldAvailability!.eps = availableAt;
+    }
 
     for (const field of QUARTERLY_SNAPSHOT_FIELDS) {
       const value = statementNumber(latest, field);
@@ -503,7 +518,7 @@ function sourceStatements(
     return { statements: mergeStatementsByPeriod(known.annual), period: "annual" };
   }
   if (normalized === "ttm" || valuationMetric) {
-    const ttm = buildTtmStatements(quarterly);
+    const ttm = buildTtmStatements(quarterly, known.annual);
     if (normalized === "ttm" && ttm.length > 0) return { statements: ttm, period: "ttm" };
     if (valuationMetric && ttm.some((statement) => hasValuationInputs(statement, valuationMetric))) {
       return { statements: ttm, period: "ttm" };
@@ -860,7 +875,7 @@ function currentValuationStatements(
 ): InternalStatement[] {
   if (selected.period !== "annual") return selected.statements;
   const known = valuationStatements(financials);
-  const trailing = buildTtmStatements(deriveQuarterlyStatements(known.quarterly, known.annual))
+  const trailing = buildTtmStatements(deriveQuarterlyStatements(known.quarterly, known.annual), known.annual)
     .filter((statement) => hasValuationInputs(statement, metric));
   return [...selected.statements, ...trailing];
 }