gloomberb 0.18.2 → 0.18.4

package/src/market-data/market/change-basis.ts

@@ -5,7 +5,7 @@ import { canonicalExchange } from "../../utils/exchanges";
 import { isFiniteNumber } from "../../utils/guards";
 import { formatUtcDayTime } from "../../utils/utc-time";
 import { zonedDateKey } from "../../utils/zoned-date-time";
-import { futuresChangeBasis, isFuturesInstrument } from "../futures-contract";
+import { futuresChangeBasis, futuresSettleText, isFuturesInstrument } from "../futures-contract";
 import { quoteTradingDay } from "../quotes/day-range";
 import { previousPublishedSession } from "./freshness";
 import { getActiveQuoteDisplay, getRegularSessionDisplay, regularSessionDisplayDate } from "./status";
@@ -65,6 +65,30 @@ function quoteVenue(quote: Quote): string {
   return canonicalExchange(quote.listingExchangeName || quote.exchangeName);
 }
 
+/**
+ * The venue whose calendar an index's sessions follow, where its quote names
+ * the index's publisher or feed instead of a venue: the Hang Seng family's
+ * HKSE trades HKEX's days, the Nikkei 225's OSAKA JPX's, and the US
+ * publishers' the US equity calendar. An index quoted under a venue (KRX, NSE,
+ * SSE) is that venue's already.
+ */
+const INDEX_CALENDAR_VENUES: Readonly<Record<string, string>> = {
+  HKSE: "HKEX",
+  OSAKA: "JPX",
+  SNP: "NYSE",
+  DJI: "NYSE",
+  "NASDAQ GIDS": "NASDAQ",
+  "CBOE INDICES": "CBOE",
+  "CHICAGO OPTIONS": "CBOE",
+};
+
+/** The venue whose published calendar dates the quote's sessions. */
+function calendarVenue(quote: Quote): string {
+  const venue = quoteVenue(quote);
+  const index = classifyInstrumentType(quote.instrumentType) === "index" || kindFromListingSyntax(quote.symbol) === "index";
+  return (index && INDEX_CALENDAR_VENUES[venue]) || venue;
+}
+
 function isCurrencyPair(quote: Quote): boolean {
   return classifyInstrumentType(quote.instrumentType) === "currency"
     || kindFromListingSyntax(quote.symbol, quote.listingExchangeName || quote.exchangeName) === "currency";
@@ -93,11 +117,12 @@ function previousIndexSession(quote: Quote, date: string): string | null {
 
 /**
  * The session before the one a move is dated to: from the venue's published
- * calendar, with the closures in between; for an index from its own sessions;
- * for a currency pair the weekday before. Null when nothing dates it.
+ * calendar, with the closures in between (an index's, the venue whose days it
+ * follows); otherwise for an index from its own sessions; for a currency pair
+ * the weekday before. Null when nothing dates it.
  */
 function previousSession(quote: Quote, sessionDate: string): DatedChangeBasis | null {
-  const venue = quoteVenue(quote);
+  const venue = calendarVenue(quote);
   const published = previousPublishedSession(venue, sessionDate);
   if (published) return { kind: "close", date: published.date, venue, closed: published.closed };
   const index = previousIndexSession(quote, sessionDate);
@@ -110,7 +135,8 @@ function previousSession(quote: Quote, sessionDate: string): DatedChangeBasis |
  * What the quote's move is measured from. A coin moves from its previous UTC
  * day's close, the price at 00:00 UTC, unless Gloom Cloud says it moves over
  * the last 24 hours; a perpetual always moves over 24 hours. A future's is the
- * settlement or trade its terms name (futuresChangeBasis). Anything else is
+ * settlement or trade its terms name, or the close of the trade date before
+ * on its venue's holiday calendar (futuresChangeBasis). Anything else is
  * the close of the session before the move's, dated by the venue's calendar;
  * a venue without one has a previous close that is left undated, never
  * guessed. Null for a quote with no move: none reported, or a listing that no
@@ -127,13 +153,27 @@ export function quoteChangeBasis(
   if (isSpotCoin(quote)) return { kind: "utc day" };
   const sessionDate = (session === "active" ? quote.changeSessionDate : regularSessionDisplayDate(quote)) ?? quoteTradingDay(quote);
   if (isFuturesInstrument(quote.symbol, quote.instrumentType)) {
-    const basis = futuresChangeBasis(terms ?? { settlement: null }, { ...display, sessionDate });
+    const basis = futuresChangeBasis(terms ?? { settlement: null }, { ...display, sessionDate }, quoteVenue(quote));
     return basis ? { kind: basis.kind, date: basis.session } : { kind: "previous close" };
   }
   if (!sessionDate || !ISO_DATE.test(sessionDate)) return { kind: "previous close" };
   return previousSession(quote, sessionDate) ?? { kind: "previous close" };
 }
 
+/**
+ * A futures quote's Settle line, paired with its Change line: the settlement
+ * is shown when it is of the session the move is measured from or a later one,
+ * and reads `--` with that session when the terms have not caught up to it
+ * (futuresSettleText), so the two lines never name different sessions.
+ */
+export function quoteSettleText(
+  quote: Quote | null | undefined,
+  terms: NonNullable<QuoteChangeBasisOptions["terms"]> & Parameters<typeof futuresSettleText>[0],
+): string {
+  const basis = quoteChangeBasis(quote, { terms });
+  return futuresSettleText(terms, quote, basis && "date" in basis ? basis.date : null);
+}
+
 /**
  * The exchange-local date of `quote.previousClose`: the session before the
  * one the quote's change is declared for (changeSessionDate), the UTC day
@@ -146,7 +186,9 @@ export function quotePreviousCloseDate(quote: Quote | null | undefined): string
   const sessionDate = quote.changeSessionDate ?? quoteTradingDay(quote);
   if (!sessionDate || !ISO_DATE.test(sessionDate)) return null;
   if (isSpotCoin(quote)) return dayBefore(sessionDate);
-  if (isFuturesInstrument(quote.symbol, quote.instrumentType)) return futuresChangeBasis({ settlement: null }, { price: quote.price, change: 0, sessionDate })?.session ?? null;
+  if (isFuturesInstrument(quote.symbol, quote.instrumentType)) {
+    return futuresChangeBasis({ settlement: null }, { price: quote.price, change: 0, sessionDate }, quoteVenue(quote))?.session ?? null;
+  }
   return previousSession(quote, sessionDate)?.date ?? null;
 }
 

package/src/market-data/market/freshness.ts

@@ -2,6 +2,7 @@ import type { MarketState, QuoteIndexSession } from "../../types/financials";
 import { canonicalExchange, EXCHANGE_TIME_ZONES, isUsListingExchange } from "../../utils/exchanges";
 import { hasPublishedApacCalendar, isPublishedApacClosure } from "../published-apac-sessions";
 import { hasPublishedCnCalendar, isPublishedCnClosure } from "../published-cn-sessions";
+import { hasPublishedFuturesCalendar, isPublishedFuturesClosure, isPublishedFuturesVenue } from "../published-futures-sessions";
 import { hasPublishedJpxCalendar, isPublishedJpxClosure } from "../published-jpx-sessions";
 import { hasPublishedNseCalendar, isPublishedNseClosure } from "../published-nse-sessions";
 import { getPublishedUsEquityCalendarDay, getPublishedUsEquityCalendarYears, getPublishedUsEquitySession } from "../published-us-sessions";
@@ -275,7 +276,7 @@ function isPublishedClosure(exchange: string, date: string): boolean {
   if (exchange === "JPX") return isPublishedJpxClosure(date);
   if (exchange === "NSE" || exchange === "BSE") return isPublishedNseClosure(date);
   if (exchange === "SSE" || exchange === "SZSE") return isPublishedCnClosure(date);
-  if (isPublishedApacClosure(exchange, date)) return true;
+  if (isPublishedApacClosure(exchange, date) || isPublishedFuturesClosure(exchange, date)) return true;
   return getPublishedUsEquityCalendarDay(exchange, date) === "closed";
 }
 
@@ -284,6 +285,16 @@ export function isTradingWeekday(exchange: string, weekday: number, weekendDays?
   return !(weekendDays ?? WEEKEND_DAYS[exchange] ?? DEFAULT_WEEKEND_DAYS).includes(weekday);
 }
 
+/**
+ * Whether the venue trades on its local `date` (YYYY-MM-DD): a day of its
+ * trading week that is not a published closure. A venue without published
+ * closures counts every day of its trading week; an unknown venue Monday to
+ * Friday.
+ */
+export function isVenueTradingDay(exchange: string | undefined, date: string): boolean {
+  return isLocalTradingDay(canonicalExchange(exchange), date);
+}
+
 /** `weekendDays` replaces the venue's days off (historySourceWeekendDays). */
 function isLocalTradingDay(exchange: string, date: string, weekendDays?: readonly number[]): boolean {
   const weekday = localWeekday(date);
@@ -319,6 +330,11 @@ function regularCloseMinutes(exchange: string, date: string): number | undefined
   return (weekday == null ? undefined : WEEKDAY_CLOSE_MINUTES[exchange]?.[weekday]) ?? REGULAR_CLOSE_MINUTES[exchange];
 }
 
+/** Whether the venue's regular close hour is known, so its sessions end on its own clock rather than at local midnight. */
+export function hasRegularCloseHour(exchange: string | undefined): boolean {
+  return REGULAR_CLOSE_MINUTES[canonicalExchange(exchange)] !== undefined;
+}
+
 /** The zone a venue's session dates are read in, or null when unknown. */
 export function sessionCalendarTimeZone(exchange: string | undefined): string | null {
   const canonical = canonicalExchange(exchange);
@@ -487,9 +503,13 @@ export function isRegularSessionTime(
  * True when the venue's full-day closures for the year of `date` are
  * published: US venues, JPX, NSE, BSE, SSE, SZSE, KRX, KOSDAQ, TWSE, TPEX,
  * HKEX, SGX, ASX and EGX. Elsewhere a local holiday reads as a trading day.
+ * For the futures venues (CME, CBT, NYM, CMX, NYB) a closure is a weekday
+ * with no trade date, and a day some of a venue's contracts settled and
+ * others did not is unknown.
  */
 export function hasPublishedSessionCalendar(exchange: string | undefined, date: string): boolean {
   const canonical = canonicalExchange(exchange);
+  if (isPublishedFuturesVenue(canonical)) return hasPublishedFuturesCalendar(canonical, date);
   const year = Number(date.slice(0, 4));
   if (canonical === "JPX") return hasPublishedJpxCalendar(year);
   if (canonical === "NSE" || canonical === "BSE") return hasPublishedNseCalendar(year);
@@ -505,17 +525,22 @@ export function hasPublishedSessionCalendar(exchange: string | undefined, date:
  * Mon 19 Oct 2026 lies between Fri 16 and Tue 20 Oct). A `date` that is no
  * session (a quote dated by when it was read, on a Saturday or a holiday) is
  * the latest session on or before it: Friday's move, read on Saturday, is
- * from Thursday's close. Null for round-the-clock and unknown venues, and
- * when a day the walk passes is in a year whose closures the venue has not
- * published: a holiday there would read as a session.
+ * from Thursday's close. With `closedDayRollsForward`, a `date` the venue had
+ * no session on is instead the next session's: CME Globex trades most US
+ * holidays and books those trades on the next trade date, so a future's move
+ * dated Memorial Day is Tuesday's, from Friday's settlement. Null for
+ * round-the-clock and unknown venues, and when a day the walk passes is in a
+ * year whose closures the venue has not published: a holiday there would
+ * read as a session.
  */
 export function previousPublishedSession(
   exchange: string | undefined,
   date: string,
+  { closedDayRollsForward = false }: { closedDayRollsForward?: boolean } = {},
 ): { date: string; closed: string[] } | null {
   const canonical = canonicalExchange(exchange);
   const day = isoLocalDateToUtcDay(date);
-  if (day == null || ALWAYS_OPEN_EXCHANGES.has(canonical) || !sessionCalendarTimeZone(canonical)) return null;
+  if (day == null || ALWAYS_OPEN_EXCHANGES.has(canonical)) return null;
   let session: number | null = null;
   const closed: string[] = [];
   for (let offset = 0; offset <= SESSION_LOOKBACK_DAYS * 2; offset++) {
@@ -527,6 +552,10 @@ export function previousPublishedSession(
     // First the session the move is from's own day, then the one before it.
     if (session == null) {
       if (open) session = offset;
+      else if (offset === 0 && closedDayRollsForward) {
+        session = offset;
+        closed.push(iso);
+      }
       continue;
     }
     if (offset - session > SESSION_LOOKBACK_DAYS) return null;

package/src/market-data/market/period-return.ts

@@ -0,0 +1,163 @@
+import { calendarMonthsBefore } from "../../utils/calendar-date";
+import { zonedDateKey } from "../../utils/zoned-date-time";
+import { isAlwaysOpenExchange, latestRegularSessionClose, sessionCalendarTimeZone } from "./freshness";
+
+/**
+ * One convention for every period return (CMP, RETURN, the futures board,
+ * sector and short-interest boards, the volatility curve's look-backs): a
+ * period runs from the close on or before the same calendar date one period
+ * before its end, and says so, `from Mon 21 Sep close`. A month before Wed 21
+ * Oct is Mon 21 Sep, so 1M is measured from Mon 21 Sep's close; a month
+ * before Tue 20 Oct is Sun 20 Sep, so from Fri 18 Sep's close.
+ */
+export type ReturnPeriod = "1W" | "1M" | "3M" | "6M" | "1Y" | "3Y" | "5Y" | "YTD";
+
+const PERIOD_MONTHS: Readonly<Record<Exclude<ReturnPeriod, "1W" | "YTD">, number>> = { "1M": 1, "3M": 3, "6M": 6, "1Y": 12, "3Y": 36, "5Y": 60 };
+const PERIODS: ReadonlySet<string> = new Set<ReturnPeriod>(["1W", "1M", "3M", "6M", "1Y", "3Y", "5Y", "YTD"]);
+const DAY_MS = 86_400_000;
+
+/**
+ * How far before its base day a base close may be: a weekend with the longest
+ * closures markets take (Spring Festival put TWSE's previous session twelve
+ * days back in February 2026). A close further back is a gap in the history (a
+ * halt, a listing that started later), so the period has no base.
+ */
+export const PERIOD_BASE_MAX_GAP_DAYS = 14;
+
+/** What a period whose newest point is the session still trading says of that point. */
+export const LATEST_INTRADAY_TEXT = "latest, intraday";
+
+export function isReturnPeriod(value: unknown): value is ReturnPeriod {
+  return typeof value === "string" && PERIODS.has(value);
+}
+
+function shiftDay(day: string, days: number): string {
+  return new Date(Date.parse(`${day}T00:00:00Z`) + days * DAY_MS).toISOString().slice(0, 10);
+}
+
+/**
+ * The calendar date a period ending on `endDay` (`YYYY-MM-DD`) is measured
+ * from: seven days before for a week, the same day of the month before for a
+ * month (31 Mar's is 28 or 29 Feb), and 31 Dec of the year before for YTD.
+ */
+export function periodBaseDay(endDay: string, period: ReturnPeriod): string {
+  const day = endDay.slice(0, 10);
+  if (period === "YTD") return `${Number(day.slice(0, 4)) - 1}-12-31`;
+  if (period === "1W") return shiftDay(day, -7);
+  return calendarMonthsBefore(new Date(`${day}T00:00:00Z`), PERIOD_MONTHS[period]).toISOString().slice(0, 10);
+}
+
+/**
+ * The session day of a daily or longer bar stamped at `time`, `YYYY-MM-DD`:
+ * a date-only stamp (UTC midnight) is its UTC date; any other is read on the
+ * venue's clock, as feeds stamp a JPX bar at 00:00 JST (15:00 UTC the day
+ * before) and a European one at local midnight. The UTC date for a venue
+ * that trades every day or whose sessions are unknown.
+ */
+export function barSessionDay(time: number, venue?: string): string {
+  const utc = new Date(time).toISOString().slice(0, 10);
+  if (time % DAY_MS === 0 || !venue || isAlwaysOpenExchange(venue)) return utc;
+  const zone = sessionCalendarTimeZone(venue);
+  return zone ? zonedDateKey(time, zone) : utc;
+}
+
+/**
+ * The day a bar's close is from, to compare with a base day: a daily bar's own
+ * date, a weekly bar's (dated by the Monday its week starts) Friday, or Sunday
+ * at a venue that trades every day, a monthly bar's last day of the month.
+ * `YYYY-MM-DD`.
+ */
+export function barCloseDay(day: string, interval?: string | null, venue?: string): string {
+  const date = day.slice(0, 10);
+  if (interval === "1wk") return shiftDay(date, venue && isAlwaysOpenExchange(venue) ? 6 : 4);
+  if (interval === "1mo") {
+    const start = new Date(`${date}T00:00:00Z`);
+    return new Date(Date.UTC(start.getUTCFullYear(), start.getUTCMonth() + 1, 0)).toISOString().slice(0, 10);
+  }
+  return date;
+}
+
+/**
+ * The index of the close a period is measured from among chronological
+ * `days` (each close's day, barCloseDay): the last on or before `baseDay`,
+ * at most `maxGapDays` before it. -1 when there is none, because the history
+ * starts after the base day or has a gap there.
+ */
+export function periodBaseIndex(days: readonly string[], baseDay: string, maxGapDays = PERIOD_BASE_MAX_GAP_DAYS): number {
+  const earliest = Number.isFinite(maxGapDays) ? shiftDay(baseDay, -maxGapDays) : "";
+  for (let index = days.length - 1; index >= 0; index -= 1) {
+    const day = days[index]!;
+    if (day > baseDay) continue;
+    return day >= earliest ? index : -1;
+  }
+  return -1;
+}
+
+export interface PeriodClose {
+  /** The close's day, `YYYY-MM-DD`. */
+  day: string;
+  close: number;
+}
+
+export interface PeriodReturn {
+  /** The calendar date the period is measured back to (periodBaseDay). */
+  baseDay: string;
+  /** The close it is measured from: the last on or before `baseDay`. */
+  base: PeriodClose;
+  /** The price it runs to: the newest close, or the live price given. */
+  end: PeriodClose;
+  /** The return in percent. */
+  percent: number;
+}
+
+/**
+ * A period return over chronological closes, from the close on or before
+ * the base day (periodBaseIndex) to the newest close, or to `latest` when a
+ * live price is given, dated by its session day. Null without a base, an end,
+ * or a positive base close.
+ */
+export function periodReturn(
+  closes: readonly PeriodClose[],
+  period: ReturnPeriod,
+  latest?: PeriodClose | null,
+  maxGapDays = PERIOD_BASE_MAX_GAP_DAYS,
+): PeriodReturn | null {
+  const end = latest && Number.isFinite(latest.close) ? latest : closes.at(-1);
+  if (!end) return null;
+  const baseDay = periodBaseDay(end.day, period);
+  const index = periodBaseIndex(closes.map((close) => close.day), baseDay, maxGapDays);
+  const base = index < 0 ? null : closes[index]!;
+  if (!base || !(base.close > 0) || !Number.isFinite(end.close)) return null;
+  const percent = (end.close / base.close - 1) * 100;
+  return Number.isFinite(percent) ? { baseDay, base, end, percent } : null;
+}
+
+const WEEKDAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"] as const;
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"] as const;
+
+/** `Mon 21 Sep`, with the year when it is not `currentYear`'s: `Tue 21 Oct 2025`. */
+export function periodDayText(day: string, currentYear: number): string {
+  const date = new Date(`${day.slice(0, 10)}T00:00:00Z`);
+  if (!Number.isFinite(date.getTime())) return day;
+  const year = date.getUTCFullYear() === currentYear ? "" : ` ${date.getUTCFullYear()}`;
+  return `${WEEKDAYS[date.getUTCDay()]} ${date.getUTCDate()} ${MONTHS[date.getUTCMonth()]}${year}`;
+}
+
+/** `from Mon 21 Sep close`: the close a period is measured from, as its output names it. */
+export function periodBaseText(day: string, now = Date.now()): string {
+  return `from ${periodDayText(day, new Date(now).getUTCFullYear())} close`;
+}
+
+/**
+ * Whether a daily bar dated `day` is the session still trading at `venue`
+ * at `now`: dated after the venue's latest closed session, or today's UTC
+ * date for a venue that never closes. False where the venue's sessions are
+ * unknown, which cannot tell.
+ */
+export function isIntradayDailyBar(day: string, venue: string | undefined, now: number): boolean {
+  if (!venue || !Number.isFinite(now)) return false;
+  if (isAlwaysOpenExchange(venue)) return day.slice(0, 10) === new Date(now).toISOString().slice(0, 10);
+  if (!sessionCalendarTimeZone(venue)) return false;
+  const last = latestRegularSessionClose(venue, now);
+  return !!last && day.slice(0, 10) > last.date;
+}

package/src/market-data/market/trading-sessions.ts

@@ -72,6 +72,19 @@ export function latestTradingSessionOpen(symbol: string | undefined, exchange: s
   return futures ? latestOpen(futures, time) : latestRegularSessionOpen(exchange, time);
 }
 
+/**
+ * When a futures listing's sessions open, in minutes after local midnight:
+ * its source's minute and hour bars start on the clock, not at the open, so a
+ * bar built from them must not straddle it. Null for other listings, whose
+ * bars start at the open.
+ */
+export function futuresSessionOpenMinute(symbol: string | undefined, exchange: string | undefined): number | null {
+  const session = symbol || exchange ? futuresSessionOpen(symbol ?? "", exchange) : null;
+  if (!session) return null;
+  const gcd = (left: number, right: number): number => (right === 0 ? left : gcd(right, left % right));
+  return session.sundayOpen === undefined ? session.open : gcd(session.open, session.sundayOpen);
+}
+
 /**
  * The zone a listing's intraday times read in: a futures venue's own clock
  * (Chicago for CME Group, New York for ICE U.S.), otherwise the venue's. Null

package/src/market-data/market/year-to-date.ts

@@ -1,4 +1,5 @@
 import { barLastSession } from "./bar-period";
+import { barCloseDay, barSessionDay, periodBaseDay, periodBaseIndex } from "./period-return";
 
 const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"] as const;
 
@@ -29,18 +30,12 @@ export function yearToDateBaseLabel(day: string, venue: string | undefined, now
  * every bar is from the year itself (a listing that started trading in it);
  * -1 without bars.
  */
-export function yearToDateStartIndex(dates: readonly string[], interval?: string | null): number {
-  const last = dates.at(-1);
+export function yearToDateStartIndex(dates: readonly string[], interval?: string | null, venue?: string): number {
+  // A timestamped bar is read on the venue's clock (barSessionDay), a crypto week as running through Sunday.
+  const days = dates.map((date) => date.length > 10 && Number.isFinite(Date.parse(date)) ? barSessionDay(Date.parse(date), venue) : date.slice(0, 10));
+  const last = days.at(-1);
   if (!last) return -1;
-  const yearEnd = `${Number(last.slice(0, 4)) - 1}-12-31`;
-  const closes = (date: string) => {
-    const day = Date.parse(`${date.slice(0, 10)}T00:00:00Z`);
-    if (interval === "1wk") return new Date(day + 6 * 86_400_000).toISOString().slice(0, 10);
-    if (interval === "1mo") return new Date(Date.UTC(new Date(day).getUTCFullYear(), new Date(day).getUTCMonth() + 1, 0)).toISOString().slice(0, 10);
-    return date.slice(0, 10);
-  };
-  for (let index = dates.length - 1; index >= 0; index -= 1) {
-    if (closes(dates[index]!) <= yearEnd) return index;
-  }
-  return 0;
+  // The listing's whole history counts here, however far before 31 Dec its last close of the year was.
+  const index = periodBaseIndex(days.map((day) => barCloseDay(day, interval, venue)), periodBaseDay(last, "YTD"), Number.POSITIVE_INFINITY);
+  return Math.max(0, index);
 }

package/src/market-data/performance.ts

@@ -1,6 +1,7 @@
 import type { PricePoint, Quote } from "../types/financials";
 import { pricePointIntegrity } from "../utils/price-history-integrity";
 import { calendarMonthsBefore } from "../utils/calendar-date";
+import { barSessionDay, isReturnPeriod, periodBaseDay, periodBaseIndex } from "./market/period-return";
 
 export interface PriceReturnHorizon {
   id: string;
@@ -66,20 +67,26 @@ export function appendQuoteToPriceReturnHistory(
   ];
 }
 
-function subtractHorizon(date: Date, horizon: PriceReturnHorizon): Date {
-  return calendarMonthsBefore(date, horizon.amount * (horizon.unit === "year" ? 12 : 1));
+/** The calendar date a horizon ending on `day` is measured back to (periodBaseDay). */
+function horizonBaseDay(day: string, horizon: PriceReturnHorizon): string {
+  return isReturnPeriod(horizon.id)
+    ? periodBaseDay(day, horizon.id)
+    : calendarMonthsBefore(new Date(`${day}T00:00:00Z`), horizon.amount * (horizon.unit === "year" ? 12 : 1)).toISOString().slice(0, 10);
 }
 
+/** `venue` is the listing's exchange, whose clock dates its bars and quote (barSessionDay). */
 export function computePriceReturnForHorizon(
   points: readonly PricePoint[],
   horizon: PriceReturnHorizon,
+  venue?: string,
 ): number | null {
-  return priceReturnForHorizon(points, horizon).value;
+  return priceReturnForHorizon(points, horizon, venue).value;
 }
 
 function priceReturnForHorizon(
   points: readonly PricePoint[],
   horizon: PriceReturnHorizon,
+  venue: string | undefined,
 ): Pick<PriceReturnField, "value" | "unavailableReason"> {
   const history = normalizePriceReturnHistory(points);
   if (history.length < 2) return {
@@ -88,16 +95,14 @@ function priceReturnForHorizon(
   };
 
   const latest = history.at(-1)!;
-  const cutoff = subtractHorizon(latest.date, horizon);
-  let baseline: PricePoint | null = null;
-
-  for (const point of history) {
-    if (point.date.getTime() <= cutoff.getTime()) {
-      baseline = point;
-    } else {
-      break;
-    }
-  }
+  // The close on or before the same date a horizon earlier, as every period return is measured. No gap
+  // limit: the overview's history can be sparse, and its base is whatever close it holds on or before then.
+  // Each bar and the quote by its session day: a JPX bar stamped 00:00 JST, or a quote after a New York close, is not the UTC date's.
+  const days = history.map((point) => barSessionDay(point.date.getTime(), venue));
+  const baseDay = horizonBaseDay(days.at(-1)!, horizon);
+  const baseIndex = periodBaseIndex(days, baseDay, Number.POSITIVE_INFINITY);
+  const baseline = baseIndex < 0 ? null : history[baseIndex]!;
+  const cutoff = new Date(`${baseDay}T00:00:00Z`);
 
   if (history.some((point) => point.date >= (baseline?.date ?? cutoff) && pricePointIntegrity(point))) {
     return { value: null, unavailableReason: "inconsistent-ohlc" };
@@ -109,11 +114,12 @@ function priceReturnForHorizon(
 
 export function buildPriceReturnFields(
   points: readonly PricePoint[],
+  venue?: string,
   horizons: readonly PriceReturnHorizon[] = PRICE_RETURN_HORIZONS,
 ): PriceReturnField[] {
   return horizons.map((horizon) => ({
     id: horizon.id,
     label: horizon.label,
-    ...priceReturnForHorizon(points, horizon),
+    ...priceReturnForHorizon(points, horizon, venue),
   }));
 }

package/src/market-data/perpetual-premium.ts

@@ -0,0 +1,32 @@
+import type { Quote } from "../types/financials";
+
+/** What a stock perpetual's premium to its stock is worked out from: its row, as PERP and the lists read it. */
+export interface PerpetualPremiumRow {
+  markPrice?: number | null;
+  priceMultiplier?: number;
+  underlying?: { currency: string } | null;
+  /**
+   * How Gloom Cloud matched the contract to the listing asked about: that very listing, or another of its issuer's
+   * (a GOOGL contract for GOOG, BRK.A's for BRK.B), whose price is not the contract's reference.
+   */
+  equityMatch?: { basis: "listing" | "issuer" } | null;
+  /** Gloom Cloud's figure: against the stock's stored price, or its regular close while its market is shut. */
+  underlyingPremium: number | null;
+}
+
+/**
+ * A stock perpetual's premium to its stock. While the stock's market is open, the stored price Gloom Cloud compares a
+ * streaming mark with is minutes old, so a live quote of the stock, where the screen has one, is the reference
+ * instead, when the contract tracks that very listing. Otherwise (another listing of the issuer, a quote that is
+ * itself a contract's, a delayed quote, a shut market, another currency) the row's own figure stands.
+ */
+export function premiumToUnderlying(row: PerpetualPremiumRow, stock: Quote | null | undefined): number | null {
+  const mark = row.markPrice;
+  if (
+    mark == null || !row.underlying || row.equityMatch?.basis !== "listing" || !stock || stock.instrumentType === "PERP"
+    || stock.stale === true || stock.dataSource !== "live"
+    || stock.marketState !== "REGULAR" || stock.currency !== row.underlying.currency
+    || !Number.isFinite(stock.price) || stock.price <= 0
+  ) return row.underlyingPremium;
+  return mark / (row.priceMultiplier ?? 1) / stock.price - 1;
+}

package/src/market-data/published-apac-sessions.ts

@@ -5,6 +5,7 @@
 // KRX, also KOSDAQ: http://open.krx.co.kr/contents/MKD/01/0110/01100305/MKD01100305.jsp
 // TWSE, whose closures TPEx shares: https://www.twse.com.tw/en/trading/holiday.html
 //   (2027 not yet published; 12 and 13 Feb 2026 are clearing-only days without trading)
+//   and a day it closed unscheduled: 23 Oct 2026 for Typhoon Champi, announced the evening before
 // BHB closes on the dates its own daily closes skip in 2026, which match the holidays it lists
 //   (some moved, as its list warns), and on National Day, 16 and 17 Dec. Its week is Sunday to Thursday.
 // HKEX: https://www.hkex.com.hk/-/media/HKEX-Market/Services/Circulars-and-Notices/Participant-and-Members-Circulars/SEHK/2025/ce_SEHK_CT_075_2025.pdf
@@ -39,7 +40,7 @@ const WIENER_BOERSE_CLOSURES: Record<number, readonly string[]> = {
 const TWSE_CLOSURES: Record<number, readonly string[]> = {
   2026: [
     "01-01", "02-12", "02-13", "02-16", "02-17", "02-18", "02-19", "02-20", "02-27",
-    "04-03", "04-06", "05-01", "06-19", "09-25", "09-28", "10-09", "10-26", "12-25",
+    "04-03", "04-06", "05-01", "06-19", "09-25", "09-28", "10-09", "10-23", "10-26", "12-25",
   ],
 };
 

package/src/market-data/published-futures-sessions.ts

@@ -0,0 +1,69 @@
+// Published trade-date holidays of the futures venues quotes name (weekend
+// dates omitted), not a holiday-rule engine: weekdays with no trade date, on
+// which nothing settles. CME Globex trades an abbreviated session on most of
+// them and books it on the next trade date; ICE Futures U.S. softs do not
+// trade at all. A year a venue has not published is unknown, not open.
+// Checked 2026-10-21:
+// CME Group, one calendar for CME, CBOT, NYMEX and COMEX:
+//   https://www.cmegroup.com/trading-hours.html (2026 and 2027 Globex holiday schedules and notes)
+//   and its clearing advisories, such as
+//   https://www.cmegroup.com/tools-information/holiday-calendar/files/2026/2026-memorial-day-clearing-advisory.pdf
+//   ("Prices will be carried forward from Prior day").
+// ICE Futures U.S. softs (cocoa, coffee, cotton, FCOJ, sugar):
+//   https://www.ice.com/publicdocs/futures_us/exchange_notices/ICE_Futures_US_Exchange_Notice_2026_Holiday_Calendar_20260609.pdf
+//   https://www.ice.com/publicdocs/futures_us/exchange_notices/ICE_Futures_US_Exchange_Notice-2027_Holiday_Calendar_20260604.pdf
+//   Its canola closes on Canada's holidays and its financial contracts trade most US ones; Gloom
+//   Cloud quotes neither (RS=F and DX=F are not tickers), so NYB is its softs.
+// ICE Futures Europe has no listing Gloom Cloud quotes, so no calendar.
+const CME_GROUP_CLOSURES: Record<number, readonly string[]> = {
+  2026: ["01-01", "01-19", "02-16", "04-03", "05-25", "06-19", "07-03", "09-07", "11-26", "12-25"],
+  2027: ["01-01", "01-18", "02-15", "03-26", "05-31", "06-18", "07-05", "09-06", "11-25", "12-24"],
+};
+
+const ICE_US_SOFTS_CLOSURES: Record<number, readonly string[]> = {
+  2026: ["01-01", "01-19", "02-16", "04-03", "05-25", "06-19", "07-03", "09-07", "11-26", "12-25"],
+  2027: ["01-01", "01-18", "02-15", "03-26", "05-31", "06-18", "07-05", "09-06", "11-25", "12-24"],
+};
+
+/** Closures by canonical venue code. */
+export const PUBLISHED_FUTURES_CLOSURES: Readonly<Record<string, Record<number, readonly string[]>>> = {
+  CME: CME_GROUP_CLOSURES,
+  CBT: CME_GROUP_CLOSURES,
+  NYM: CME_GROUP_CLOSURES,
+  CMX: CME_GROUP_CLOSURES,
+  NYB: ICE_US_SOFTS_CLOSURES,
+};
+
+/**
+ * Closures some of a venue's contracts settled on and others did not, which
+ * its calendar cannot say either way. Good Friday 2026 fell on a payrolls
+ * release: CME and CBOT settled their FX, interest rate and crypto contracts
+ * and rolled their equity index and agricultural ones forward from Thursday
+ * (https://www.cmegroup.com/tools-information/holiday-calendar/files/2026/2026-good-friday-clearing-advisory.pdf).
+ * NYMEX and COMEX settled nothing.
+ */
+const PARTIAL_CLOSURES: Readonly<Record<string, readonly string[]>> = {
+  CME: ["2026-04-03"],
+  CBT: ["2026-04-03"],
+};
+
+/** Whether `exchange` (a canonical venue code) is a futures venue with a published calendar. */
+export function isPublishedFuturesVenue(exchange: string): boolean {
+  return Object.hasOwn(PUBLISHED_FUTURES_CLOSURES, exchange);
+}
+
+/** True only for a published trade-date holiday; unpublished years are unknown, not open. */
+export function isPublishedFuturesClosure(exchange: string, date: string): boolean {
+  if (!isPublishedFuturesVenue(exchange)) return false;
+  return PUBLISHED_FUTURES_CLOSURES[exchange]![Number(date.slice(0, 4))]?.includes(date.slice(5)) ?? false;
+}
+
+/**
+ * True when the venue's calendar says whether `date` had a trade date: its
+ * year is published and the day is not one some of its contracts settled and
+ * others did not.
+ */
+export function hasPublishedFuturesCalendar(exchange: string, date: string): boolean {
+  return isPublishedFuturesVenue(exchange) && PUBLISHED_FUTURES_CLOSURES[exchange]![Number(date.slice(0, 4))] !== undefined
+    && !PARTIAL_CLOSURES[exchange]?.includes(date);
+}

package/src/market-data/quotes/contributions.ts

@@ -214,6 +214,10 @@ export function mergeQuoteContribution(
     tradingExchangeName: next.tradingExchangeName,
     // Whether the listing no longer trades is said with each observation: a symbol that trades again drops it.
     delisting: next.delisting,
+    // So is a pair's price being its bar's close, and why a stale one stands; a bar's close is no trade.
+    intradayBar: next.intradayBar,
+    staleReason: next.staleReason,
+    ...(next.intradayBar ? { lastTradePrice: next.lastTradePrice, lastTradeTime: next.lastTradeTime } : {}),
     regularClose: next.regularClose,
     regularCloseSessionDate: next.regularClose != null ? next.regularCloseSessionDate : undefined,
     regularChange: next.regularClose != null ? next.regularChange : undefined,
@@ -221,7 +225,7 @@ export function mergeQuoteContribution(
   };
 
   // What this observation's move is from, when not its previous close (a coin's
-  // 24 hours, Linear: GLO-1089), is said with each one: a quote back on its
+  // 24 hours), is said with each one: a quote back on its
   // previous close drops an earlier "24h", and one on 24 hours drops the
   // earlier close its move no longer runs from.
   if (next.changeBasis == null) {