@gloom-sh/terminal 0.19.1 → 0.19.3

package/src/time-series/coin-session-close.ts

@@ -0,0 +1,211 @@
+import { hasRegularCloseHour, isAlwaysOpenExchange, regularSessionCloseOn, sessionCalendarTimeZone } from "../market-data/market/freshness";
+import { fetchHistoryResult } from "../sources/history-result";
+import type { DataProvider } from "../types/data-provider";
+import { isRoundTheClockCoin } from "../utils/crypto-pair";
+import { canonicalExchange, isUsListingExchange } from "../utils/exchanges";
+import { logFailure } from "../utils/log-failure";
+import { zonedDateTimeParts, zonedWallClockToUtcMs } from "../utils/zoned-date-time";
+import type { PriceComparison } from "./price-comparison";
+import type { ResolvedSeries } from "./types";
+
+const HOUR_MS = 60 * 60_000;
+const DAY_MS = 24 * HOUR_MS;
+/** How far back hourly bars are read for a comparison: Gloom Cloud keeps a coin's for a year. A longer span keeps UTC closes. */
+const HOURLY_REACH_MS = 370 * DAY_MS;
+
+/** The venue a compared leg trades on, as its sessions are read. */
+function legVenue(series: ResolvedSeries | undefined): string | undefined {
+  return series?.timeBasis?.exchange || series?.listing?.exchange || undefined;
+}
+
+/** A coin that trades round the clock, its daily bar the UTC day: BTC-USD on the crypto venue. */
+function isRoundTheClockLeg(series: ResolvedSeries | undefined): boolean {
+  if (!series) return false;
+  const venue = legVenue(series);
+  return (!!venue && isAlwaysOpenExchange(venue)) || isRoundTheClockCoin(series.listing?.symbol, series.listing?.exchange);
+}
+
+/**
+ * A leg whose venue closes each day at a known hour: a US fund, a London share. A venue whose close hour is not
+ * known has no close to measure a coin at: the coin keeps its UTC closes, and the notice names no close.
+ */
+function sessionVenueOf(series: ResolvedSeries | undefined): string | null {
+  const venue = legVenue(series);
+  return venue && !isRoundTheClockLeg(series) && !isAlwaysOpenExchange(venue) && sessionCalendarTimeZone(venue) && hasRegularCloseHour(venue)
+    ? venue : null;
+}
+
+/** `US` for a US listing's venue, else the venue's code, as the close a coin is measured against is named. */
+function sessionMarketName(venue: string): string {
+  return isUsListingExchange(venue) ? "US" : canonicalExchange(venue);
+}
+
+type HourlyRead = Awaited<ReturnType<typeof fetchHistoryResult>>;
+type HourlyProvider = Pick<DataProvider, "getDetailedPriceHistory" | "getDetailedPriceHistoryWithMetadata">;
+interface HourlyReads {
+  /** Recent reads by listing and span: a chart resolves again on every live quote, and asks for the same hours. */
+  spans: Map<string, { at: number; read: Promise<HourlyRead> }>;
+  /** Listings whose read failed, until when they are not asked again. */
+  failedUntil: Map<string, number>;
+}
+const hourlyReadsBySource = new WeakMap<HourlyProvider, HourlyReads>();
+const HOURLY_READ_LIMIT = 64;
+/** A span reaching the last hour is read again after this long; an older one is kept until it falls out. */
+const RECENT_READ_TTL_MS = 60_000;
+/** A listing whose hourly bars failed to load is not asked again for this long, so the failure is logged once in it. */
+const FAILED_READ_TTL_MS = 2 * 60_000;
+const logHourlyFailure = logFailure("time-series.coin-session-close", "Read a coin's hourly bars for a comparison failed", null);
+
+function hourlyBars(
+  provider: HourlyProvider,
+  symbol: string,
+  exchange: string,
+  start: number,
+  end: number,
+  now: number,
+): Promise<HourlyRead> {
+  let reads = hourlyReadsBySource.get(provider);
+  if (!reads) hourlyReadsBySource.set(provider, reads = { spans: new Map(), failedUntil: new Map() });
+  const listing = `${symbol}:${exchange}`;
+  if ((reads.failedUntil.get(listing) ?? 0) > now) return Promise.resolve(null);
+  // A span ending now is keyed by its minute, so a chart redrawn within it reads it once.
+  end = Math.ceil(end / 60_000) * 60_000;
+  const key = `${listing}:${start}:${end}`;
+  const cached = reads.spans.get(key);
+  if (cached && (end < now - HOUR_MS || now - cached.at < RECENT_READ_TTL_MS)) return cached.read;
+  const read = fetchHistoryResult(provider as DataProvider, symbol, exchange, { kind: "detail", start: new Date(start), end: new Date(end), interval: "1h" })
+    .then((result) => result ?? Promise.reject(new Error("no hourly bars")))
+    .catch((error: unknown) => {
+      // A failed read is asked again only after FAILED_READ_TTL_MS, and logged once for it.
+      reads!.failedUntil.set(listing, now + FAILED_READ_TTL_MS);
+      if (reads!.spans.get(key)?.read === read) reads!.spans.delete(key);
+      return logHourlyFailure(error);
+    });
+  reads.spans.delete(key);
+  reads.spans.set(key, { at: now, read });
+  if (reads.spans.size > HOURLY_READ_LIMIT) reads.spans.delete(reads.spans.keys().next().value!);
+  return read;
+}
+
+export interface SessionCloseTiming {
+  /** The venue whose close the coins are compared against: the first compared leg that trades in sessions. */
+  venue: string;
+  /** Coin legs measured at that venue's close on each of their days, from hourly bars. */
+  atSessionClose: ReadonlySet<string>;
+  /** Of those, the legs whose newest day's session has closed: their end is that close, not a price still moving. */
+  closedEnds: ReadonlySet<string>;
+}
+
+/** The venue's wall clock of `time` in its zone, to measure a day without a session at its usual close. */
+function wallClock(time: number, zone: string): { hour: number; minute: number } {
+  const { hour, minute } = zonedDateTimeParts(time, zone);
+  return { hour, minute };
+}
+
+/**
+ * A daily comparison of a coin with a listing that trades in sessions (IBIT
+ * against BTC-USD) compares the fund's close at 20:00 UTC with the coin's at
+ * 00:00 UTC, four hours later, which on a falling night is most of the gap.
+ * When the coin's hourly bars cover its whole span, every one of its daily
+ * points from the base to its end is replaced by its price at the session
+ * venue's close (the close of the hourly bar ending then; a day the venue
+ * does not trade, at the clock time of its last close), so both legs and
+ * the line between are measured at the same instants. A coin whose hourly
+ * bars miss any of those hours (they go back a year) keeps its UTC closes
+ * throughout, and the comparison names each close time instead
+ * (priceComparisonCloseTimes): the line and its total never mix the two.
+ *
+ * Null when the comparison has no such pair of legs; otherwise the venue and
+ * the series, with the coin legs that could be measured at its close.
+ */
+export async function coinLegsAtSessionClose(
+  comparison: PriceComparison | null,
+  series: readonly ResolvedSeries[],
+  provider: HourlyProvider,
+  now: number,
+): Promise<{ timing: SessionCloseTiming; series: ResolvedSeries[] } | null> {
+  if (comparison?.alignment !== "session-date" || !comparison.legs) return null;
+  const byId = new Map(series.map((entry) => [entry.id, entry]));
+  const compared = Object.keys(comparison.legs);
+  const venue = compared.map((id) => sessionVenueOf(byId.get(id))).find((entry): entry is string => !!entry);
+  const coins = compared.filter((id) => isRoundTheClockLeg(byId.get(id)) && byId.get(id)!.historyResolution === "1d");
+  const zone = venue ? sessionCalendarTimeZone(venue) : null;
+  if (!venue || !zone || coins.length === 0) return null;
+  const atSessionClose = new Set<string>();
+  const closedEnds = new Set<string>();
+  const next = [...series];
+  await Promise.all(coins.map(async (id) => {
+    const entry = byId.get(id)!;
+    const leg = comparison.legs![id]!;
+    const symbol = entry.listing?.symbol;
+    const baseClose = regularSessionCloseOn(venue, leg.baseDay);
+    // A coin's newest day still running is its latest price; measured at the close only once the venue has closed.
+    const endClose = regularSessionCloseOn(venue, leg.endDay);
+    const endTime = endClose !== null && endClose <= now ? endClose : leg.intraday ? null : endClose;
+    if (!symbol || baseClose === null || (endTime === null && !leg.intraday)) return;
+    // The instant each of the coin's days is measured at: the venue's close that day, or on a day it does not trade,
+    // the clock time of its last close before.
+    const instants = new Map<number, number>();
+    let clock = wallClock(baseClose, zone);
+    entry.points.forEach((point, index) => {
+      const day = point.date.toISOString().slice(0, 10);
+      if (day < leg.baseDay || day > leg.endDay) return;
+      if (day === leg.endDay && endTime === null) return;
+      const close = regularSessionCloseOn(venue, day);
+      if (close !== null) clock = wallClock(close, zone);
+      instants.set(index, close ?? zonedWallClockToUtcMs(zone, Number(day.slice(0, 4)), Number(day.slice(5, 7)), Number(day.slice(8, 10)),
+        clock.hour, clock.minute, 0));
+    });
+    const times = [...instants.values()];
+    const last = Math.max(baseClose, ...times);
+    if (last > now || last - baseClose > HOURLY_REACH_MS) return;
+    const read = await hourlyBars(provider, symbol, entry.listing?.exchange ?? "", baseClose - 2 * HOUR_MS, Math.min(now, last + HOUR_MS), now);
+    if (!read || read.resolution !== "1h") return;
+    // Each finished hourly bar's close by the time it closed; a bar still forming has no close yet.
+    const closes = new Map<number, number>();
+    for (const bar of read.points) {
+      const open = new Date(bar.date).getTime();
+      if (!bar.partial && Number.isFinite(open) && Number.isFinite(bar.close) && bar.close > 0) closes.set(open + HOUR_MS, bar.close);
+    }
+    // Every day or none: a line of closes at the venue's close with a few UTC closes between would be neither.
+    if (!closes.has(baseClose) || times.some((time) => !closes.has(time))) return;
+    const points = entry.points.map((point, index) => {
+      const price = instants.has(index) ? closes.get(instants.get(index)!)! : undefined;
+      return price === undefined ? point : { ...point, value: price, close: price, rawValue: price };
+    });
+    next[next.indexOf(entry)] = { ...entry, points };
+    atSessionClose.add(id);
+    if (endTime !== null) closedEnds.add(id);
+  }));
+  return { timing: { venue, atSessionClose, closedEnds }, series: next };
+}
+
+/**
+ * What a daily comparison of coins with listings that trade in sessions says
+ * of when each is measured: `BTC-USD at the US close` when its hourly bars
+ * put it there, else `BTC-USD to 00:00 UTC, 4 h after the US close`. Null
+ * when no coin is compared with such a listing.
+ */
+export function priceComparisonCloseTimes(
+  comparison: Pick<PriceComparison, "legs">,
+  series: readonly ResolvedSeries[],
+  labels: ReadonlyMap<string, string>,
+  atSessionClose: ReadonlySet<string> = new Set(),
+): string | null {
+  const byId = new Map(series.map((entry) => [entry.id, entry]));
+  const compared = Object.keys(comparison.legs ?? {});
+  const venue = compared.map((id) => sessionVenueOf(byId.get(id))).find((entry): entry is string => !!entry);
+  const coins = compared.filter((id) => isRoundTheClockLeg(byId.get(id)));
+  if (!venue || coins.length === 0) return null;
+  const market = sessionMarketName(venue);
+  const parts = coins.map((id) => {
+    const label = labels.get(id) ?? id;
+    if (atSessionClose.has(id)) return `${label} at the ${market} close`;
+    const leg = comparison.legs![id]!;
+    const sessionClose = leg.intraday ? null : regularSessionCloseOn(venue, leg.endDay);
+    const coinClose = Date.parse(`${leg.endDay}T00:00:00Z`) + DAY_MS;
+    const hours = sessionClose === null ? null : Math.round((coinClose - sessionClose) / HOUR_MS);
+    return hours !== null && hours > 0 ? `${label} to 00:00 UTC, ${hours} h after the ${market} close` : `${label} to 00:00 UTC`;
+  });
+  return parts.join("; ");
+}

package/src/time-series/live-bars.ts

@@ -54,6 +54,8 @@ interface HistoryAnchor {
   /** Identity of the loaded version of the history's newest bar. */
   key: string;
   time: number;
+  /** The session's open, from a quote whose session is the whole bar (quoteSessionRange). */
+  open: number | null;
   /** Live extremes and close observed while this bar is still forming. */
   high: number | null;
   low: number | null;
@@ -211,6 +213,7 @@ export class LiveBarAccumulator {
     this.anchor = {
       key,
       time: latestTime,
+      open: forming ? previous?.open ?? null : null,
       high: carried?.high ?? null,
       low: carried?.low ?? null,
       close: carried?.close ?? null,
@@ -316,6 +319,7 @@ export class LiveBarAccumulator {
       return;
     }
     if (!forming && this.inBar(time, anchor.time, options, exchange)) {
+      if (range?.open !== undefined) anchor.open = range.open;
       anchor.high = Math.max(anchor.high ?? price, price, range?.high ?? price);
       anchor.low = Math.min(anchor.low ?? price, price, range?.low ?? price);
       anchor.close = price;
@@ -364,8 +368,15 @@ export class LiveBarAccumulator {
     const anchor = this.anchor!;
     if (anchor.point?.source === latest && anchor.point.version === this.version) return anchor.point.value;
     let value = latest;
-    // A later quote cannot establish which reported OHLC field was wrong.
-    if (!pricePointIntegrity(latest)) {
+    if (pricePointIntegrity(latest)) {
+      // A later quote cannot establish which reported OHLC field was wrong, unless it names the bar's whole session:
+      // its open, range, price and count are the bar (mergeQuoteIntoLatestBar).
+      if (anchor.open !== null && anchor.close !== null) {
+        const close = anchor.close;
+        value = { ...latest, open: anchor.open, high: Math.max(anchor.high ?? close, anchor.open, close),
+          low: Math.min(anchor.low ?? close, anchor.open, close), close, ...this.cumulative !== null ? { volume: this.cumulative } : {} };
+      }
+    } else {
       let volume = latest.volume;
       const end = anchor.volumeEnd ?? this.cumulative;
       if (isFiniteNumber(volume) && end !== null && anchor.volumeBase !== null) {

package/src/time-series/live-quotes.ts

@@ -3,7 +3,7 @@ import { canonicalTimeSeriesFieldId, isMarketFieldId } from "./field-catalog";
 import type { QuoteSubscriptionTarget } from "../types/data-provider";
 import type { Quote } from "../types/financials";
 import type { ChartSeriesSpec, ChartSpec, SecuritySeriesSource } from "./types";
-import { activeStudyInputSeriesIds } from "./studies";
+import { activeStudyInputSeriesIds } from "./studies/resolve";
 import { valuationSeriesUsesLiveQuote } from "./fundamentals";
 import { hasValidQuoteObservationTime } from "../market-data/quotes/freshness";
 import type { InstrumentRef } from "../market-data/request-types";

package/src/time-series/market.ts

@@ -1,5 +1,5 @@
 import type { PricePoint, TickerFinancials } from "../types/financials";
-import { pricePointIntegrity, pricePointValues, priceHistoryIntegrityNotice, mergePriceHistoryIntegrity, type PriceHistoryIntegrity } from "../utils/price-history-integrity";
+import { pricePointIntegrity, pricePointValues, pricePointWicks, priceHistoryIntegrityNotice, mergePriceHistoryIntegrity, type PriceHistoryIntegrity } from "../utils/price-history-integrity";
 import { canonicalTimeSeriesFieldId, isFundamentalFieldId, isMarketFieldId } from "./field-catalog";
 import { extractFundamentalSeries } from "./fundamentals";
 import type { ChartSeriesPriceHistoryIntegrity, ResolvedSeries, SecuritySeriesSource, SeriesPeriod, TimeSeriesPoint } from "./types";
@@ -73,8 +73,10 @@ function aggregatePriceHistory(
   for (const point of sorted) {
     const key = periodKey(point.date, period);
     const open = isFiniteNumber(point.open) ? point.open : point.close;
-    const high = isFiniteNumber(point.high) ? point.high : point.close;
-    const low = isFiniteNumber(point.low) ? point.low : point.close;
+    // A wick too far from its bar's body to have traded does not set the week's or month's range.
+    const wicks = pricePointWicks(point);
+    const high = isFiniteNumber(wicks.high) ? wicks.high : isFiniteNumber(point.high) ? Math.max(open, point.close) : point.close;
+    const low = isFiniteNumber(wicks.low) ? wicks.low : isFiniteNumber(point.low) ? Math.min(open, point.close) : point.close;
     const current = buckets.get(key);
     if (!current) {
       buckets.set(key, {

package/src/time-series/official-close.ts

@@ -0,0 +1,159 @@
+import type { PricePoint, Quote } from "../types/financials";
+import { latestRegularSessionClose, regularSessionCloseOn, sessionCalendarTimeZone } from "../market-data/market/freshness";
+import { quoteTradingDay } from "../market-data/quotes/day-range";
+import { hasLikelyQuoteUnitMismatch } from "../utils/currency-units";
+import { canonicalExchange, isUsListingExchange } from "../utils/exchanges";
+import { zonedDateKey } from "../utils/zoned-date-time";
+
+/** What the footer of an intraday total says while a session has closed but its closing print is not in yet. */
+export const CLOSING_PRINT_PENDING_TEXT = "closing print not in yet";
+
+/** A close this far from the session's last trade is another listing's or another unit's, never its auction print. */
+const MAX_CLOSE_MOVE = 0.25;
+
+function barTime(point: Pick<PricePoint, "date">): number {
+  return new Date(point.date as Date | string | number).getTime();
+}
+
+const positive = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value) && value > 0;
+
+/** Whether `close` can be the close of a session whose last trade was `lastTrade`. */
+function nearLastTrade(close: number, lastTrade: number | null): boolean {
+  return lastTrade === null || !positive(lastTrade) || Math.abs(close / lastTrade - 1) <= MAX_CLOSE_MOVE;
+}
+
+/** The newest regular session that has closed, when the bars hold it, and its last trade there. */
+export interface ClosedSession {
+  /** The session's local date. */
+  date: string;
+  /** The close of its last regular bar: the last trade before the closing auction. */
+  lastTrade: number;
+}
+
+/** When each local date's session closed, read once per date. */
+function sessionCloses(venue: string | undefined) {
+  const closes = new Map<string, number | null>();
+  return (date: string) => {
+    if (!closes.has(date)) closes.set(date, regularSessionCloseOn(venue, date));
+    return closes.get(date)!;
+  };
+}
+
+/** Each closed session's last regular bar, by the session's local date (a later bar is after-hours). */
+function lastRegularBars(points: readonly PricePoint[], venue: string | undefined, now: number): Map<string, number> {
+  const zone = sessionCalendarTimeZone(venue);
+  const latest = latestRegularSessionClose(venue, now);
+  const last = new Map<string, number>();
+  if (!zone || !latest) return last;
+  const closeOn = sessionCloses(venue);
+  points.forEach((point, index) => {
+    const time = barTime(point);
+    if (!Number.isFinite(time)) return;
+    const date = zonedDateKey(time, zone);
+    if (date > latest.date) return;
+    const close = closeOn(date);
+    if (close === null || time >= close) return;
+    last.set(date, index);
+  });
+  return last;
+}
+
+/**
+ * The newest regular session that has closed by `now` (the venue's calendar),
+ * when the bars hold a regular bar of it: the session whose official close a
+ * quote is read for. Null while the venue trades past its last session's
+ * bars, for venues without sessions, and when the bars end earlier.
+ */
+export function newestClosedSession(points: readonly PricePoint[], options: { venue: string | undefined; now: number }): ClosedSession | null {
+  const latest = latestRegularSessionClose(options.venue, options.now);
+  if (!latest) return null;
+  const index = lastRegularBars(points, options.venue, options.now).get(latest.date);
+  return index === undefined ? null : { date: latest.date, lastTrade: points[index]!.close };
+}
+
+/** What the newest closed session's last bar ends on: a close, the note that its print is to come, or nothing to change. */
+export type NewestSessionClose = { close: number } | { pending: true } | null;
+
+/**
+ * The close the newest closed session ends on, for its last regular bar
+ * (`session`, from newestClosedSession). In order:
+ *
+ * 1. The quote's official close of that session (`regularClose`, dated by
+ *    `regularCloseSessionDate` or the quote's trading day).
+ * 2. Right after a US close (POST) without it, the note that the print is to
+ *    come: the quote's price then is the last trade before the auction.
+ * 3. Otherwise (the venue closed, the next pre-market, a listing that
+ *    publishes no closing print) the session's finished daily bar, then the
+ *    quote's own close: its price once closed, its previous close in the
+ *    next pre-market.
+ *
+ * Every figure from the quote must be the bars' listing (same venue, same
+ * currency where both are known), in the bars' units, and within 25% of the
+ * session's last trade; one that is not is not used. A quote of the session
+ * still trading, or none, leaves the daily bar's close or nothing.
+ */
+export function newestSessionClose(
+  quote: Quote | null | undefined,
+  session: ClosedSession & {
+    venue: string | undefined;
+    /** The listing's currency, where known. */
+    currency?: string | null;
+    /** The session's finished daily bar's close, where one was read. */
+    dailyClose?: number | null;
+  },
+): NewestSessionClose {
+  const daily = positive(session.dailyClose) && nearLastTrade(session.dailyClose, session.lastTrade) ? { close: session.dailyClose } : null;
+  if (!quote || quote.marketState === "REGULAR") return daily;
+  const quoteVenue = quote.listingExchangeName || quote.exchangeName;
+  if (quoteVenue && session.venue && canonicalExchange(quoteVenue) !== canonicalExchange(session.venue)) return daily;
+  if (session.currency && quote.currency && session.currency !== quote.currency) return daily;
+  const usable = (value: number | undefined): value is number => positive(value)
+    && !hasLikelyQuoteUnitMismatch({ currency: quote.currency, price: session.lastTrade }, { currency: quote.currency, price: value })
+    && nearLastTrade(value, session.lastTrade);
+  const official = positive(quote.regularClose) && (quote.regularCloseSessionDate ?? quoteTradingDay(quote)) === session.date
+    ? quote.regularClose : undefined;
+  if (official !== undefined) return usable(official) ? { close: official } : daily;
+  if (quote.marketState === "POST" && isUsListingExchange(canonicalExchange(session.venue))) return { pending: true };
+  if (daily) return daily;
+  if (quote.marketState === "PRE" || quote.marketState === "PREPRE") {
+    const previous = quote.previousClose;
+    return (!quote.previousCloseDate || quote.previousCloseDate === session.date) && usable(previous) ? { close: previous } : null;
+  }
+  return quoteTradingDay(quote) === session.date && usable(quote.price) ? { close: quote.price } : null;
+}
+
+/**
+ * Intraday bars of a listing that trades in sessions, each closed session's
+ * last regular bar closing on that session's official close (`closes`, by
+ * the venue's local date) instead of the last trade before the closing
+ * auction: an hourly 19:30 UTC bar of a thin ETF ends on a 19:38 trade at
+ * 12.31 while the 20:00 closing print is 12.19, which every total measured
+ * from the bars then misses. The bar's high and low widen to take the close.
+ * A close more than 25% off the bar's own is another unit's, and not taken.
+ *
+ * A session still trading, bars after its close (after-hours) and venues
+ * without sessions are left as served; the points array is the same one when
+ * nothing changed.
+ */
+export function withOfficialCloses(
+  points: PricePoint[],
+  closes: ReadonlyMap<string, number>,
+  options: { venue: string | undefined; now: number },
+): PricePoint[] {
+  if (points.length === 0 || closes.size === 0) return points;
+  let changed = false;
+  const next = points.slice();
+  for (const [date, index] of lastRegularBars(points, options.venue, options.now)) {
+    const close = closes.get(date);
+    const bar = next[index]!;
+    if (!positive(close) || bar.close === close || !nearLastTrade(close, bar.close)) continue;
+    next[index] = {
+      ...bar,
+      close,
+      ...(positive(bar.high) ? { high: Math.max(bar.high, close) } : {}),
+      ...(positive(bar.low) ? { low: Math.min(bar.low, close) } : {}),
+    };
+    changed = true;
+  }
+  return changed ? next : points;
+}

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

@@ -1,9 +1,10 @@
 import { scalarPointValue } from "./alignment";
 import { getTimeSeriesField } from "./field-catalog";
 import type { ChartSpec, ResolvedSeries, TimeSeriesPoint } from "./types";
-import { chartBarSizeSource, type ManualChartResolution } from "./resolution";
+import { CHART_RESOLUTION_STEP_MS, chartBarSizeSource, getChartResolutionLabel, isIntradayResolution, type ManualChartResolution } from "./resolution";
 import type { TimeRange } from "./range";
 import { zonedDateTimeParts } from "../utils/zoned-date-time";
+import { priceComparisonCloseTimes } from "./coin-session-close";
 import { barLastSession } from "../market-data/market/bar-period";
 import {
   barCloseDay, isIntradayDailyBar, isReturnPeriod, LATEST_INTRADAY_TEXT, periodBaseDay, periodBaseIndex, periodDayText,
@@ -52,6 +53,10 @@ export interface PriceComparisonOptions {
    */
   preset?: TimeRange | null;
   now?: number;
+  /** Coin legs whose daily closes were taken at the session venue's close (coinLegsAtSessionClose). */
+  atSessionClose?: ReadonlySet<string>;
+  /** Of those, the legs whose newest day ends at a session close that has passed: not a price still moving. */
+  closedEnds?: ReadonlySet<string>;
 }
 
 export function observationDate(time: number, series: Pick<ResolvedSeries, "timeBasis">): string {
@@ -63,7 +68,24 @@ export function observationDate(time: number, series: Pick<ResolvedSeries, "time
   return `${year}-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
 }
 
-/** Date-only research windows select local sessions; runtime timestamps remain exact. */
+/**
+ * The day the weekly or monthly bar holding `date` is dated by: its week's
+ * Monday or its month's 1st, as `history --from` keeps the week or month its
+ * first date falls in. A daily bar is its own day.
+ */
+function windowBarStart(date: string, resolution: "1d" | "1wk" | "1mo"): string {
+  if (resolution === "1mo") return `${date.slice(0, 7)}-01`;
+  if (resolution === "1d") return date;
+  const day = Date.parse(`${date}T00:00:00Z`);
+  return new Date(day - ((new Date(day).getUTCDay() + 6) % 7) * 86_400_000).toISOString().slice(0, 10);
+}
+
+/**
+ * Date-only research windows select local sessions; runtime timestamps remain
+ * exact. Weekly and monthly bars keep the bar the window starts in: a window
+ * from 2019-12-31 in monthly bars starts with December 2019's, whose close is
+ * that day's, so a comparison is measured from it.
+ */
 export function priceObservationWindowFilter(
   series: ResolvedSeries,
   bounds: { start: number | null; end: number | null },
@@ -74,11 +96,12 @@ export function priceObservationWindowFilter(
   const calendarWindow = calendarBars && dateWindow
     && /^\d{4}-\d{2}-\d{2}$/.test(dateWindow.start)
     && /^\d{4}-\d{2}-\d{2}$/.test(dateWindow.end) ? dateWindow : null;
+  const start = calendarWindow ? windowBarStart(calendarWindow.start, resolution as "1d" | "1wk" | "1mo") : null;
   return (time) => {
     if (!Number.isFinite(time)) return false;
     const key = calendarWindow ? observationDate(time, series) : null;
     return key !== null
-      ? key >= calendarWindow!.start && key <= calendarWindow!.end
+      ? key >= start! && key <= calendarWindow!.end
       : (bounds.start === null || time >= bounds.start) && (bounds.end === null || time <= bounds.end);
   };
 }
@@ -138,6 +161,28 @@ export function totalReturnLevelsNotice(spec: ChartSpec, series: readonly Resolv
     priceOnly.length ? ` Price only for ${priceOnly.join(", ")}: distribution history unavailable.` : ""}`;
 }
 
+/**
+ * The bar size intraday legs are matched in: the chart's, or when it has none
+ * the coarsest the legs were served in. Null when neither is intraday.
+ */
+function intradayBucketMs(resolution: ManualChartResolution | "auto", series: ReadonlyArray<ResolvedSeries | undefined>): number | null {
+  const sizes = [resolution, ...series.map((entry) => entry?.historyResolution)]
+    .filter((size): size is ManualChartResolution => !!size && size !== "auto" && size in CHART_RESOLUTION_STEP_MS && isIntradayResolution(size as ManualChartResolution));
+  if (resolution !== "auto" && sizes[0] === resolution) return CHART_RESOLUTION_STEP_MS[resolution];
+  return sizes.length ? Math.max(...sizes.map((size) => CHART_RESOLUTION_STEP_MS[size])) : null;
+}
+
+/** `1H` for an hour's bucket, as the chart names its bar size. */
+function barLabel(bucketMs: number): string {
+  const size = (Object.keys(CHART_RESOLUTION_STEP_MS) as ManualChartResolution[]).find((key) => CHART_RESOLUTION_STEP_MS[key] === bucketMs);
+  return size ? getChartResolutionLabel(size) : `${Math.round(bucketMs / 60_000)}m`;
+}
+
+/** `IBIT and BTC-USD`, `A, B and C`. */
+function listLabels(labels: readonly string[]): string {
+  return labels.length <= 1 ? labels.join("") : `${labels.slice(0, -1).join(", ")} and ${labels.at(-1)}`;
+}
+
 interface ComparedLeg {
   id: string;
   label: string;
@@ -185,6 +230,9 @@ export function resolvePriceComparison(
   const dropped: NonNullable<PriceComparison["dropped"]> = [];
   const reported = new Set<string>();
   const legs: ComparedLeg[] = [];
+  // Intraday bars compare by the bar of the chart's size they open in: a fund's 13:30 bar and a coin's 13:00 bar are
+  // one hourly bar, so the fund's last bar of the day (19:30, closing at 20:00) meets the coin's bar closing then.
+  const bucketMs = calendarBars ? null : intradayBucketMs(resolution, seriesIds.map((id) => byId.get(id)!));
   for (const id of seriesIds) {
     const entry = byId.get(id)!;
     const inWindow = priceObservationWindowFilter(entry, bounds, resolution, dateWindow);
@@ -193,7 +241,7 @@ export function resolvePriceComparison(
     for (const point of entry.points) {
       const time = point.date.getTime();
       if (!Number.isFinite(time) || scalarPointValue(point) === null) continue;
-      const key = calendarBars ? observationDate(time, entry) : String(time);
+      const key = calendarBars ? observationDate(time, entry) : String(bucketMs ? Math.floor(time / bucketMs) * bucketMs : time);
       points.set(key, point);
       if (inWindow(time)) window.add(key);
     }
@@ -219,7 +267,16 @@ export function resolvePriceComparison(
     return legs.length ? keys(legs[0]!).filter((key) => sets.every((set) => set.has(key))) : [];
   };
   const sharedWindow = shared((leg) => leg.window);
-  const sharedStart = sharedWindow.find((key) => legs.every((leg) => nonzero(leg, key)));
+  // Authored dates (`--from 2026-10-19`) measure from the close before the first date, as RETURN does: the last
+  // date the legs share before it. Weekly and monthly bars keep the bar the window starts in.
+  const authoredFrom = !preset && dateWindow && /^\d{4}-\d{2}-\d{2}$/.test(dateWindow.start) && (resolution === "1d" || !calendarBars)
+    ? dateWindow.start : null;
+  const firstInWindow = authoredFrom ? legs.map((leg) => leg.window[0]!).sort(order)[0] : undefined;
+  const authoredBase = authoredFrom && firstInWindow !== undefined
+    ? shared((leg) => leg.keys).filter((key) => (calendarBars ? key < authoredFrom : order(key, firstInWindow) < 0)
+      && legs.every((leg) => nonzero(leg, key))).at(-1)
+    : undefined;
+  const sharedStart = authoredBase ?? sharedWindow.find((key) => legs.every((leg) => nonzero(leg, key)));
   // The period is measured back from the chart's newest observation, by its session day.
   const anchor = period && legs.length
     ? legs.map((leg) => calendarBars ? sessionDay(leg.window.at(-1)!) : dayOf(leg, leg.window.at(-1)!)).sort().at(-1)!
@@ -256,7 +313,14 @@ export function resolvePriceComparison(
   const droppedText = dropped.length
     ? ` Left out: ${dropped.map((entry) => reported.has(entry.seriesId) ? entry.label : `${entry.label} (${entry.reason})`).join("; ")}.`
     : "";
-  if (!compared.length) return { seriesIds, start: null, end: null, notice: unavailable, ...(dropped.length ? { dropped } : {}) };
+  if (!compared.length) {
+    // Intraday legs that never trade in the same bar: said, with the bar size that compares them.
+    const apart = !calendarBars && legs.length >= 2 && sharedWindow.length === 0 && legs.every((leg) => leg.window.length >= 2);
+    const notice = apart
+      ? `${basis} Comparison unavailable: ${listLabels(legs.map((leg) => leg.label))} share no ${bucketMs ? `${barLabel(bucketMs)} ` : ""}bar times in this range; daily bars (1D) compare them.`
+      : unavailable;
+    return { seriesIds, start: null, end: null, notice, ...(dropped.length ? { dropped } : {}) };
+  }
   const sourceBounds = Object.fromEntries(compared.map(({ leg, start, end }) => [leg.id, {
     start: leg.points.get(start)!.date.getTime(),
     end: leg.points.get(end)!.date.getTime(),
@@ -266,7 +330,7 @@ export function resolvePriceComparison(
     const endDay = calendarBars ? sessionDay(end) : dayOf(leg, end);
     // A daily bar of the session still trading, or a week or month running through it.
     return [leg.id, { baseDay: calendarBars ? sessionDay(start) : dayOf(leg, start), endDay,
-      intraday: calendarBars && isIntradayDailyBar(endDay, legVenue(leg.entry), now) }];
+      intraday: calendarBars && !options.closedEnds?.has(leg.id) && isIntradayDailyBar(endDay, legVenue(leg.entry), now) }];
   }));
   const span = calendarBars
     ? (() => {
@@ -274,7 +338,10 @@ export function resolvePriceComparison(
       const to = legsText(compared.map(({ leg }) => ({ label: leg.label, text: legDays[leg.id]!.intraday
         ? `${periodDayText(legDays[leg.id]!.endDay, currentYear)}, ${LATEST_INTRADAY_TEXT}`
         : `${periodDayText(legDays[leg.id]!.endDay, currentYear)} close` })));
-      return `From ${from} to ${to}; market session times may differ.`;
+      // A coin beside a listing that closes each day says when it is measured: at that close, or at 00:00 UTC.
+      const timing = priceComparisonCloseTimes({ legs: legDays }, compared.map(({ leg }) => leg.entry),
+        new Map(compared.map(({ leg }) => [leg.id, leg.label])), options.atSessionClose);
+      return `From ${from} to ${to}; ${timing ?? "market session times may differ"}.`;
     })()
     : baseDay && sharedBase !== undefined
       ? `From ${periodDayText(legDays[compared[0]!.leg.id]!.baseDay, currentYear)} close to ${displayDate(Math.max(...Object.values(sourceBounds).map((range) => range.end)))}.`