@gloom-sh/terminal 0.18.5 → 0.19.0

package/src/plugins/builtin/alerts/metric-command.ts

@@ -1,8 +1,9 @@
-import type { AlertMetric } from "./metric-model";
-import { validMetricRule } from "./metric-model";
+import type { AlertMetric, RotationQuadrant } from "./metric-model";
+import { ROTATION_QUADRANTS, validMetricRule } from "./metric-model";
 import { readAlertPrice } from "./price";
 import type { AlertCondition } from "./types";
 import type { WizardStep } from "../../../types/plugin";
+import { parsePublicTickerKey } from "../../../utils/exchanges";
 
 export interface MetricAlertInput { symbol: string; condition: AlertCondition; price: number; metric: AlertMetric }
 const direction = (s: string) => /^(above|over|>)$/i.test(s) ? "above" as const : /^(below|under|<)$/i.test(s) ? "below" as const : null;
@@ -11,10 +12,58 @@ function checked(input: MetricAlertInput): MetricAlertInput {
   if (!validMetricRule({ ...input, targetPrice: input.price })) throw new Error("Use a positive multiple, RSI from 0 to 100, and whole MA/RSI periods from 2 to 200 (fast MA shorter than slow MA).");
   return input;
 }
+// RRG's own default benchmark (relative-rotation/model.ts), kept here so the CLI does not load the RRG pane's model.
+const DEFAULT_ROTATION_BENCHMARK = "SPY:NYSEARCA";
+const RELATIVE_USAGE = "Relative strength alerts take the ratio of two listings or an RRG quadrant: alerts add XLK/SPY above 0.25, or alerts add XLE rrg leading [--benchmark SPY].";
+const QUADRANT_USAGE = "An RRG alert names the quadrant it enters: leading, weakening, lagging or improving, such as alerts add XLE rrg leading [--benchmark SPY].";
+/** A benchmark typed as SPY or SPY:NYSEARCA; its listing is confirmed when the alert is added. */
+function benchmarkListing(text: string): { benchmark: string; benchmarkExchange?: string } {
+  const parsed = parsePublicTickerKey(text.toUpperCase());
+  if (!/^[A-Z0-9.^=-]{1,20}$/.test(parsed.symbol)) throw new Error(`Not a benchmark listing: ${text}.`);
+  return { benchmark: parsed.symbol, ...(parsed.exchange ? { benchmarkExchange: parsed.exchange } : {}) };
+}
+const sameListing = (symbol: string, metric: { benchmark: string }) => parsePublicTickerKey(symbol).symbol === metric.benchmark;
+/**
+ * `XLK/SPY ratio above 0.25` and `XLE rrg leading [vs SPY]`; undefined for anything else. `XLK/SPY above 0.25`
+ * without the word is first a listing (BRK/B, EUR/USD), so `alerts add` reads it as a ratio only once it quotes nothing.
+ */
+function parseRelativeAlert(parts: readonly string[]): MetricAlertInput | undefined {
+  const [first = "", second = "", ...rest] = parts;
+  const kind = second.toLowerCase();
+  if (kind === "rrg") {
+    const [quadrant = "", vs, benchmark, ...extra] = rest;
+    if (first.includes("/")) throw new Error(`Name the benchmark of an RRG alert after it: alerts add ${first.split("/")[0]!.toUpperCase()} rrg ${quadrant.toLowerCase() || "leading"} --benchmark ${first.split("/")[1]!.toUpperCase()}.`);
+    if (!(ROTATION_QUADRANTS as readonly string[]).includes(quadrant.toLowerCase())) throw new Error(QUADRANT_USAGE);
+    if (vs !== undefined && (!/^(vs\.?|versus|against)$/i.test(vs) || !benchmark || extra.length > 0)) throw new Error(QUADRANT_USAGE);
+    const metric = { kind: "rrg" as const, quadrant: quadrant.toLowerCase() as RotationQuadrant, ...benchmarkListing(benchmark ?? DEFAULT_ROTATION_BENCHMARK) };
+    if (sameListing(first, metric)) throw new Error(`An RRG alert compares ${first.toUpperCase()} with another listing: alerts add ${first.toUpperCase()} rrg ${metric.quadrant} --benchmark SPY.`);
+    return checked({ symbol: first.toUpperCase(), condition: "crosses", price: 0, metric });
+  }
+  const pair = /^([^/]+)\/([^/]+)$/.exec(first);
+  if (pair && kind === "ratio") {
+    const [typed = "", level, ...extra] = rest;
+    const condition = direction(typed) ?? (/^(crosses|cross|x)$/i.test(typed) ? "crosses" as const : null);
+    const example = `alerts add ${first.toUpperCase()} above 0.25`;
+    if (!condition || level === undefined || extra.length > 0) throw new Error(`A ratio alert takes above, below or crosses and a ratio: ${example}.`);
+    const metric = { kind: "rs_ratio" as const, ...benchmarkListing(pair[2]!) };
+    if (sameListing(pair[1]!, metric)) throw new Error(`A ratio alert divides one listing by another: ${example}.`);
+    const price = readAlertPrice(level);
+    if (!(price > 0)) throw new Error(`A ratio alert takes a positive ratio: ${example}.`);
+    return checked({ symbol: pair[1]!.toUpperCase(), condition, price, metric });
+  }
+  // `XLE rs above 100`, `XLE vs SPY above 1`, `XLE relative strength leading`: a relative alert typed another way.
+  if (/^(rs|rsr|rs-?ratio|rs_ratio|rs-?momentum|rel|relative|rotation|quadrant|ratio|vs\.?|versus)$/i.test(kind)
+    && rest.some((word) => /^(above|below|over|under|crosses|cross|>|<|leading|weakening|lagging|improving|rrg)$/i.test(word))) {
+    throw new Error(RELATIVE_USAGE);
+  }
+  return undefined;
+}
 /** Parses both compact CLI notation and the words traders type, without swallowing malformed metrics as calendar events. */
 export function parseMetricAlert(input: string): MetricAlertInput | null {
   const words = input.trim().replace(/\s+/g, " ");
   const parts = words.split(" ");
+  const relative = parseRelativeAlert(parts);
+  if (relative) return relative;
   if (!/^(p\/?e|p\/?s|rsi(?:\(|$)|ma(?:\(|$)|\d+-day|closes?$)/i.test(parts[1] ?? "")) return null;
   const ratio = /^(\S+) (p\/?e|p\/?s) (above|below|over|under|>|<) (\S+)$/i.exec(words);
   if (ratio) return checked({ symbol: ratio[1]!.toUpperCase(), metric: { kind: ratio[2]!.toLowerCase().replace("/", "") as "pe" | "ps" }, condition: direction(ratio[3]!)!, price: readAlertPrice(ratio[4]!) });
@@ -27,8 +76,17 @@ export function parseMetricAlert(input: string): MetricAlertInput | null {
   if (close) return checked({ symbol: close[1]!.toUpperCase(), metric: { kind: "close_ma", period: Number(close[3]) }, condition: direction(close[2]!)!, price: 0 });
   throw new Error(USAGE);
 }
+export const benchmarkKey = (metric: { benchmark: string; benchmarkExchange?: string }) => `${metric.benchmark}${metric.benchmarkExchange ? `:${metric.benchmarkExchange}` : ""}`;
+/** A relative alert as `alerts add` takes it, for editing: `XLK/SPY ratio above 0.25`, `XLE rrg leading vs SPY`. */
+export function relativeAlertText(input: { symbol: string; condition: AlertCondition; targetPrice: number; metric?: AlertMetric }): string | null {
+  const m = input.metric;
+  if (m?.kind === "rs_ratio") return `${input.symbol}/${m.benchmark} ratio ${input.condition} ${input.targetPrice}`;
+  return m?.kind === "rrg" ? `${input.symbol} rrg ${m.quadrant} vs ${m.benchmark}` : null;
+}
 export function metricShortcut(input: MetricAlertInput): Record<string, string> {
   const m = input.metric;
+  if (m.kind === "rs_ratio") return { symbol: input.symbol, kind: m.kind, "rs_ratio:benchmark": benchmarkKey(m), "rs_ratio:condition": input.condition, "rs_ratio:target": String(input.price) };
+  if (m.kind === "rrg") return { symbol: input.symbol, kind: m.kind, "rrg:quadrant": m.quadrant, "rrg:benchmark": benchmarkKey(m) };
   return { symbol: input.symbol, kind: m.kind, [`${m.kind}:condition`]: m.kind === "ma_cross" ? m.direction : input.condition,
     [`${m.kind}:target`]: String(input.price), ...("period" in m ? { [`${m.kind}:period`]: String(m.period) } : {}),
     ...(m.kind === "ma_cross" ? { "ma_cross:slowPeriod": String(m.slowPeriod) } : {}) };
@@ -38,6 +96,11 @@ export function metricFormInput(values: Record<string, string>): MetricAlertInpu
   if (!kind || kind === "price") return null;
   const symbol = values.symbol?.trim().toUpperCase();
   if (!symbol) return null;
+  if (kind === "rs_ratio") {
+    const benchmark = values["rs_ratio:benchmark"]?.trim();
+    return benchmark ? parseMetricAlert(`${symbol}/${benchmark} ratio ${values["rs_ratio:condition"] ?? "above"} ${values["rs_ratio:target"] ?? ""}`) : null;
+  }
+  if (kind === "rrg") return parseMetricAlert(`${symbol} rrg ${values["rrg:quadrant"] ?? "leading"} vs ${values["rrg:benchmark"]?.trim() || DEFAULT_ROTATION_BENCHMARK}`);
   const condition = values[`${kind}:condition`] ?? "below";
   const window = values[`${kind}:period`] ?? (kind === "rsi" ? "14" : kind === "ma_cross" ? "50" : "200");
   const text = kind === "ma_cross" ? `${symbol} ma(${window}) crosses ${condition} ma(${values["ma_cross:slowPeriod"] ?? "200"})`
@@ -48,8 +111,18 @@ export function metricFormInput(values: Record<string, string>): MetricAlertInpu
 export const METRIC_CHOICES = [
   { value: "price", label: "Price" }, { value: "pe", label: "P/E (TTM)" }, { value: "ps", label: "P/S (TTM)" },
   { value: "rsi", label: "RSI" }, { value: "ma_cross", label: "MA crossover" }, { value: "close_ma", label: "Close vs MA" },
+  { value: "rs_ratio", label: "Ratio to benchmark" }, { value: "rrg", label: "RRG quadrant" },
+];
+const RELATIVE_FIELDS: WizardStep[] = [
+  { key: "rs_ratio:benchmark", label: "Divided by", type: "text", placeholder: "SPY", dependsOn: { key: "kind", value: "rs_ratio" } },
+  { key: "rs_ratio:condition", label: "Condition", type: "select", defaultValue: "above", dependsOn: { key: "kind", value: "rs_ratio" },
+    options: [{ label: "Above", value: "above" }, { label: "Below", value: "below" }, { label: "Crosses", value: "crosses" }] },
+  { key: "rs_ratio:target", label: "Ratio", type: "number", placeholder: "0.25", dependsOn: { key: "kind", value: "rs_ratio" } },
+  { key: "rrg:quadrant", label: "Enters", type: "select", defaultValue: "leading", dependsOn: { key: "kind", value: "rrg" },
+    options: ROTATION_QUADRANTS.map((value) => ({ label: `${value[0]!.toUpperCase()}${value.slice(1)}`, value })) },
+  { key: "rrg:benchmark", label: "Benchmark", type: "text", defaultValue: "SPY", placeholder: "SPY", dependsOn: { key: "kind", value: "rrg" } },
 ];
-export const metricWizardFields: WizardStep[] = METRIC_CHOICES.filter(x => x.value !== "price").flatMap(({ value: kind }) => {
+export const metricWizardFields: WizardStep[] = [...METRIC_CHOICES.filter(x => x.value !== "price" && x.value !== "rs_ratio" && x.value !== "rrg").flatMap(({ value: kind }) => {
   const dependsOn = { key: "kind", value: kind };
   return [
     ...(["rsi", "ma_cross", "close_ma"].includes(kind) ? [{ key: `${kind}:period`, label: kind === "ma_cross" ? "Fast MA (days)" : kind === "rsi" ? "RSI period" : "MA (days)", type: "number" as const, defaultValue: kind === "rsi" ? "14" : kind === "ma_cross" ? "50" : "200", dependsOn }] : []),
@@ -58,4 +131,4 @@ export const metricWizardFields: WizardStep[] = METRIC_CHOICES.filter(x => x.val
     ...(kind === "ma_cross" ? [{ key: "ma_cross:slowPeriod", label: "Slow MA (days)", type: "number" as const, defaultValue: "200", dependsOn }]
       : kind === "close_ma" ? [] : [{ key: `${kind}:target`, label: kind === "rsi" ? "RSI level" : "Target multiple", type: "number" as const, placeholder: kind === "rsi" ? "30" : kind === "pe" ? "25" : "8", dependsOn }]),
   ];
-});
+}), ...RELATIVE_FIELDS];

package/src/plugins/builtin/alerts/metric-data.ts

@@ -5,7 +5,9 @@ import { comparablePriceEarnings } from "../../../utils/price-earnings";
 import { canonicalExchange } from "../../../utils/exchanges";
 import { getPublishedUsEquitySession } from "../../../market-data/published-us-sessions";
 import { barSessionDay } from "../../../market-data/market/period-return";
-import { dailyMetricReading, latestSettledClose, DailyMetricCache, isDailyMetric, type MetricReading } from "./metric-model";
+import { finalDailyBars } from "../../../time-series/session-bar";
+import { getPricePointTimestamp } from "../../../utils/price-history";
+import { DAILY_CLOSE_SETTLE_MS, dailyMetricReading, latestSettledClose, DailyMetricCache, isDailyMetric, isRelativeMetric, type MetricReading } from "./metric-model";
 import type { AlertRule } from "./types";
 
 // Keep valuation fixtures in step with the delivery evaluator and the research panes.
@@ -21,12 +23,43 @@ export function valuationAlertValue(kind: "pe" | "ps", data: TickerFinancials):
   return Number.isFinite(value) && value > 0 ? value : null;
 }
 
-export function metricAvailabilityError(rule: AlertRule): string | null {
+const US_CALENDAR = "Daily technical alerts need a published US listing calendar; delivery is unavailable for this listing.";
+/** Why a rule's listings cannot be judged on settled closes: a benchmark is held to the same US calendar as the listing. */
+export function metricAvailabilityError(rule: AlertRule, now = Date.now()): string | null {
   if (!rule.metric || !isDailyMetric(rule.metric)) return null;
-  return getPublishedUsEquitySession(canonicalExchange(rule.exchange ?? ""), new Date().toISOString().slice(0, 10))
-    ? null : "Daily technical alerts need a published US listing calendar; delivery is unavailable for this listing.";
+  const today = new Date(now).toISOString().slice(0, 10);
+  if (!getPublishedUsEquitySession(canonicalExchange(rule.exchange ?? ""), today)) return US_CALENDAR;
+  return isRelativeMetric(rule.metric) && !getPublishedUsEquitySession(canonicalExchange(rule.metric.benchmarkExchange ?? ""), today)
+    ? `Relative strength alerts compare two US listings; ${rule.metric.benchmark} has no published US listing calendar here.` : null;
 }
 
+/**
+ * The first close a daily technical rule set at `now` is judged on, and when:
+ * the next session to close after it, read once the close has settled
+ * (DAILY_CLOSE_SETTLE_MS). `weekly` (an RRG quadrant) waits for the last
+ * session of that Monday-Friday week, its weekly close. Null when the listing
+ * has no published calendar.
+ */
+export function firstDailyCheck(exchange: string | undefined, now = Date.now(), weekly = false): { day: string; at: number } | null {
+  const venue = canonicalExchange(exchange ?? "");
+  let first: { day: string; close: number } | null = null;
+  for (let offset = 0; offset < 15; offset++) {
+    const time = now + offset * 86_400_000;
+    const day = new Date(time).toISOString().slice(0, 10);
+    // The weekly close is the last session before the weekend after the first close.
+    if (first && new Date(time).getUTCDay() === 6) break;
+    const session = getPublishedUsEquitySession(venue, day);
+    if (!session) return null;
+    if (session.kind !== "session" || session.close <= now) continue;
+    first = { day, close: session.close };
+    if (!weekly) break;
+  }
+  return first ? { day: first.day, at: first.close + DAILY_CLOSE_SETTLE_MS } : null;
+}
+
+/** The bar size the daily rules read, the one `history` and the charts ask for. */
+const DAILY_BARS = "1d";
+
 const dailyCaches = new WeakMap<AssetDataProvider, DailyMetricCache>();
 
 /** A pass shares each listing's reads; there is no second provider or quote subscription. */
@@ -48,23 +81,31 @@ export function metricReadings(provider: AssetDataProvider, now = Date.now()) {
     }
     const exchange = canonicalExchange(rule.exchange ?? "");
     const session = (day: string) => getPublishedUsEquitySession(exchange, day);
-    if (!session(new Date(now).toISOString().slice(0, 10))) throw new Error("Daily technical alerts need a published US listing calendar; delivery is unavailable for this listing.");
+    const unavailable = metricAvailabilityError(rule, now);
+    if (unavailable) throw new Error(unavailable);
     const latest = latestSettledClose(now, session);
     const ruleKey = JSON.stringify([rule.id, rule.armedAt ?? rule.createdAt, key, rule.condition, rule.targetPrice, m]);
     return daily.read(ruleKey, latest.day, now, async () => {
-      const load = async () => {
+      const load = async (symbol: string, venue: string) => {
         // An explicit end at the settled session avoids today's forming-bar quote read.
         const end = new Date(`${latest.day}T23:59:59Z`);
         const start = new Date(Date.parse(latest.day) - 366 * 86_400_000);
-        if (provider.getDetailedPriceHistoryWithMetadata) return (await provider.getDetailedPriceHistoryWithMetadata(rule.symbol, exchange, start, end, "1 day", { cacheMode: "current" })).points;
-        if (provider.getDetailedPriceHistory) return provider.getDetailedPriceHistory(rule.symbol, exchange, start, end, "1 day", { cacheMode: "current" });
+        if (provider.getDetailedPriceHistoryWithMetadata) return (await provider.getDetailedPriceHistoryWithMetadata(symbol, venue, start, end, DAILY_BARS, { cacheMode: "current" })).points;
+        if (provider.getDetailedPriceHistory) return provider.getDetailedPriceHistory(symbol, venue, start, end, DAILY_BARS, { cacheMode: "current" });
         throw new Error("Completed daily history is unavailable from this connection.");
       };
-      const request = history.get(key) ?? load();
-      history.set(key, request);
-      const points = await request;
-      const bars = points.filter(point => !point.partial).map(point => ({ date: barSessionDay(point.date.getTime(), exchange), close: point.close }));
-      return dailyMetricReading(rule, bars, now, session);
+      const completed = async (symbol: string, venue: string) => {
+        const listing = `${symbol}|${venue}`;
+        const request = history.get(listing) ?? load(symbol, venue);
+        history.set(listing, request);
+        // Final as `history` shows it: a close it prints without `partial` is one the rule may judge.
+        // Bars read back from the saved cache carry their dates as text.
+        return finalDailyBars(await request, { now, venue }).map(point => ({ date: barSessionDay(getPricePointTimestamp(point), venue), close: point.close }));
+      };
+      const bars = await completed(rule.symbol, exchange);
+      // RS ratios and RRG quadrants read the benchmark's own completed bars, never a quote.
+      const benchmark = isRelativeMetric(m) ? await completed(m.benchmark, canonicalExchange(m.benchmarkExchange ?? "")) : undefined;
+      return dailyMetricReading(rule, bars, now, session, benchmark);
     });
   };
 }

package/src/plugins/builtin/alerts/metric-model.ts

@@ -1,11 +1,19 @@
 // Keep this model identical to the delivery model; the parity fixture checks both copies.
 /** Synced separately from price rules so older clients cannot judge a ratio as a price. */
 export const METRIC_ALERTS_KEY = "metricAlerts";
+/** Relative strength has a list of its own too: a client that reads metricAlerts keeps none of it once it holds a measure it does not know. */
+export const RELATIVE_ALERTS_KEY = "relativeAlerts";
+export const ROTATION_QUADRANTS = ["leading", "weakening", "lagging", "improving"] as const;
+export type RotationQuadrant = typeof ROTATION_QUADRANTS[number];
 export type AlertMetric =
   | { kind: "pe" | "ps" }
   | { kind: "rsi"; period: number }
   | { kind: "close_ma"; period: number }
-  | { kind: "ma_cross"; period: number; slowPeriod: number; direction: "above" | "below" };
+  | { kind: "ma_cross"; period: number; slowPeriod: number; direction: "above" | "below" }
+  /** The listing's settled daily close divided by the benchmark's on the same session. */
+  | { kind: "rs_ratio"; benchmark: string; benchmarkExchange?: string }
+  /** The weekly RRG quadrant against the benchmark, entered on a published weekly close. */
+  | { kind: "rrg"; quadrant: RotationQuadrant; benchmark: string; benchmarkExchange?: string };
 export interface MetricReading {
   value: number;
   target: number;
@@ -25,6 +33,8 @@ export interface MetricRule {
 }
 const finite = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value);
 const period = (value: unknown): value is number => finite(value) && Number.isInteger(value) && value >= 2 && value <= 200;
+const listing = (value: unknown): value is string => typeof value === "string" && /^[A-Z0-9.^=-]{1,20}$/.test(value);
+const venue = (value: unknown) => value === undefined || (typeof value === "string" && /^[A-Z0-9._-]{1,24}$/.test(value));
 
 export function readAlertMetric(raw: unknown): AlertMetric | null {
   if (!raw || typeof raw !== "object") return null;
@@ -35,13 +45,26 @@ export function readAlertMetric(raw: unknown): AlertMetric | null {
     && (m.direction === "above" || m.direction === "below")) {
     return { kind: m.kind, period: m.period, slowPeriod: m.slowPeriod, direction: m.direction };
   }
+  if ((m.kind === "rs_ratio" || m.kind === "rrg") && listing(m.benchmark) && venue(m.benchmarkExchange)) {
+    const benchmark = { benchmark: m.benchmark, ...(m.benchmarkExchange ? { benchmarkExchange: m.benchmarkExchange as string } : {}) };
+    if (m.kind === "rs_ratio") return { kind: m.kind, ...benchmark };
+    if (ROTATION_QUADRANTS.includes(m.quadrant as RotationQuadrant)) return { kind: m.kind, quadrant: m.quadrant as RotationQuadrant, ...benchmark };
+  }
   return null;
 }
+export function isRelativeMetric(metric: AlertMetric): metric is Extract<AlertMetric, { benchmark: string }> {
+  return metric.kind === "rs_ratio" || metric.kind === "rrg";
+}
+/** The synced list a rule belongs in. */
+export function metricAlertsKey(metric: AlertMetric): string {
+  return isRelativeMetric(metric) ? RELATIVE_ALERTS_KEY : METRIC_ALERTS_KEY;
+}
 
 export function validMetricRule(rule: Pick<MetricRule, "metric" | "condition" | "targetPrice">): boolean {
   const m = readAlertMetric(rule.metric);
   if (!m || !finite(rule.targetPrice)) return false;
-  if (m.kind === "ma_cross") return rule.condition === "crosses" && rule.targetPrice === 0;
+  if (m.kind === "ma_cross" || m.kind === "rrg") return rule.condition === "crosses" && rule.targetPrice === 0;
+  if (m.kind === "rs_ratio") return ["above", "below", "crosses"].includes(rule.condition) && rule.targetPrice > 0;
   if (rule.condition !== "above" && rule.condition !== "below") return false;
   return m.kind === "close_ma" ? rule.targetPrice === 0
     : m.kind === "rsi" ? rule.targetPrice >= 0 && rule.targetPrice <= 100 : rule.targetPrice > 0;
@@ -51,18 +74,62 @@ export function metricName(metric: AlertMetric): string {
   if (metric.kind === "pe") return "P/E (TTM)";
   if (metric.kind === "ps") return "P/S (TTM)";
   if (metric.kind === "rsi") return `RSI(${metric.period})`;
+  if (metric.kind === "rs_ratio") return `Ratio to ${metric.benchmark}`;
+  if (metric.kind === "rrg") return `RRG vs ${metric.benchmark}`;
   return metric.kind === "ma_cross" ? `${metric.period}-day MA` : "Close";
 }
+const quadrantName = (quadrant: RotationQuadrant) => `${quadrant[0]!.toUpperCase()}${quadrant.slice(1)}`;
 export function metricDescription(rule: MetricRule & { symbol: string }): string {
   const m = rule.metric!;
+  const basis = closeBasis(m);
+  const suffix = basis ? ` · on ${basis}` : "";
+  if (m.kind === "rs_ratio") return `${rule.symbol} ratio to ${m.benchmark} ${rule.condition} ${rule.targetPrice}${suffix}`;
+  if (m.kind === "rrg") return `${rule.symbol} ${metricName(m)} enters ${quadrantName(m.quadrant)}${suffix}`;
   const target = m.kind === "ma_cross" ? `${m.slowPeriod}-day MA`
     : m.kind === "close_ma" ? `${m.period}-day MA` : String(rule.targetPrice);
   const condition = m.kind === "ma_cross" ? `crosses ${m.direction}` : rule.condition;
-  return `${rule.symbol} ${metricName(m)} ${condition} ${target}${isDailyMetric(m) ? " · on daily close" : ""}`;
+  return `${rule.symbol} ${metricName(m)} ${condition} ${target}${suffix}`;
 }
+/** Judged on settled closes only, never a forming session; RRG quadrants on weekly ones. */
 export function isDailyMetric(metric: AlertMetric): boolean {
   return metric.kind !== "pe" && metric.kind !== "ps";
 }
+export function closeBasis(metric: AlertMetric): "daily close" | "weekly close" | null {
+  return metric.kind === "rrg" ? "weekly close" : isDailyMetric(metric) ? "daily close" : null;
+}
+/** The reading as alerts state it: 31.2x, 0.2512, or Leading (strength 101.23, momentum 100.40) as RRG words them. */
+export function metricReadingText(metric: AlertMetric, reading: Pick<MetricReading, "value" | "target">): string {
+  if (metric.kind === "rrg") {
+    return `${rotationQuadrant(reading.value, reading.target) ?? "No quadrant"} (strength ${reading.value.toFixed(2)}, momentum ${reading.target.toFixed(2)})`;
+  }
+  return `${Number(reading.value.toFixed(4))}${metric.kind === "pe" || metric.kind === "ps" ? "x" : ""}`;
+}
+
+export type RotationQuadrantName = "Leading" | "Weakening" | "Lagging" | "Improving" | "Neutral";
+export function rotationQuadrant(strength: number | null | undefined, momentum: number | null | undefined): RotationQuadrantName | null {
+  if (strength == null || momentum == null || !finite(strength) || !finite(momentum)) return null;
+  if (Math.abs(strength - 100) < 1e-9 || Math.abs(momentum - 100) < 1e-9) return "Neutral";
+  return strength > 100 ? momentum > 100 ? "Leading" : "Weakening" : momentum > 100 ? "Improving" : "Lagging";
+}
+/**
+ * Weekly strength (RS-Ratio: 100 x the price ratio over its 13-week mean) and momentum (RS-Momentum: 100 x
+ * strength over strength four weeks earlier), as RRG plots them. A missing week breaks both until 13 and 17 contiguous weeks.
+ */
+export function rotationSeries(ratios: readonly (number | null)[]): { strength: number | null; momentum: number | null }[] {
+  const strengths = ratios.map((ratio, index) => {
+    const window = ratios.slice(Math.max(0, index - 12), index + 1);
+    if (ratio == null || window.length !== 13 || window.some((value) => value == null)) return null;
+    const average = (window as number[]).reduce((sum, value) => sum + value, 0) / 13;
+    return (100 * ratio) / average;
+  });
+  return strengths.map((strength, index) => {
+    const previous = index >= 4 ? (strengths[index - 4] ?? null) : null;
+    const contiguous = index >= 4 && strengths.slice(index - 4, index + 1).every((value) => value != null);
+    return { strength, momentum: strength != null && previous != null && contiguous ? (100 * strength) / previous : null };
+  });
+}
+/** Weeks a quadrant change needs: 17 for this week's momentum, and the week before it. */
+export const ROTATION_ALERT_WEEKS = 18;
 
 /** Wilder's initial average of N changes, then (previous * (N - 1) + change) / N. */
 function rsi(closes: readonly number[], window: number): number[] {
@@ -110,24 +177,96 @@ export class DailyMetricCache {
   }
 }
 
-export function dailyMetricReading(
-  rule: MetricRule,
-  bars: readonly { date: string; close: number }[],
-  now: number,
-  session: (day: string) => DailySession | null,
-): MetricReading {
-  const m = rule.metric!;
-  if (!isDailyMetric(m) || !("period" in m)) throw new Error("Expected a daily technical alert.");
-  const latest = latestSettledClose(now, session);
+type DailyBar = { date: string; close: number };
+function closesThrough(bars: readonly DailyBar[], through: string): Map<string, number> {
   const byDay = new Map<string, number>();
   for (const bar of bars) {
     const day = bar.date.slice(0, 10);
-    if (day > latest.day) continue;
+    if (day > through) continue;
     if (!/^\d{4}-\d{2}-\d{2}$/.test(day) || !finite(bar.close) || bar.close <= 0 || byDay.has(day)) {
       throw new Error("Daily history contains an invalid or duplicate bar.");
     }
     byDay.set(day, bar.close);
   }
+  return byDay;
+}
+const isoDay = (time: number) => new Date(time).toISOString().slice(0, 10);
+function sessionBefore(day: string, session: (day: string) => DailySession | null): string {
+  for (let offset = 1; offset < 15; offset++) {
+    const previous = isoDay(Date.parse(day) - offset * DAY);
+    const s = session(previous);
+    if (!s) throw new Error("Daily close calendar unavailable for part of the history.");
+    if (s.kind === "session") return previous;
+  }
+  throw new Error(`No session before ${day}.`);
+}
+/** The last session of each Monday-Friday week, oldest first, ending with the newest week whose close has settled. */
+export function settledWeekCloses(now: number, session: (day: string) => DailySession | null, count: number): { day: string; at: number }[] {
+  const latest = latestSettledClose(now, session);
+  const close = (friday: number) => {
+    for (let offset = 0; offset < 5; offset++) {
+      const day = isoDay(friday - offset * DAY);
+      const s = session(day);
+      if (!s) throw new Error("Daily close calendar unavailable for part of the history.");
+      if (s.kind === "session") return { day, at: s.close };
+    }
+    throw new Error(`No session in the week ending ${isoDay(friday)}.`);
+  };
+  const time = Date.parse(latest.day);
+  let friday = time + ((5 - new Date(time).getUTCDay() + 7) % 7) * DAY;
+  // A week whose last session is still ahead or forming has no weekly close yet.
+  if (close(friday).day !== latest.day) friday -= 7 * DAY;
+  return Array.from({ length: count }, (_, index) => close(friday - (count - 1 - index) * 7 * DAY));
+}
+
+/** Both listings' own closes on the same sessions; a session either lacks is never bridged from another day. */
+function relativeMetricReading(
+  rule: MetricRule,
+  m: Extract<AlertMetric, { benchmark: string }>,
+  bars: readonly DailyBar[],
+  benchmarkBars: readonly DailyBar[],
+  now: number,
+  session: (day: string) => DailySession | null,
+): MetricReading {
+  const latest = latestSettledClose(now, session);
+  const own = closesThrough(bars, latest.day), reference = closesThrough(benchmarkBars, latest.day);
+  const ratio = (day: string) => {
+    const close = own.get(day), base = reference.get(day);
+    if (close == null || base == null) {
+      if (day === latest.day) throw new Error(`Waiting for the ${latest.day} ${m.kind === "rrg" ? "weekly" : "daily"} close${close == null ? "" : ` of ${m.benchmark}`}.`);
+      throw new Error(`Daily history is missing ${day}${close == null ? "" : ` for ${m.benchmark}`}.`);
+    }
+    return close / base;
+  };
+  if (m.kind === "rs_ratio") {
+    const value = ratio(latest.day), previousValue = ratio(sessionBefore(latest.day, session));
+    return { value, target: rule.targetPrice, previousValue, previousTarget: rule.targetPrice, day: latest.day, at: latest.at };
+  }
+  const weeks = settledWeekCloses(now, session, ROTATION_ALERT_WEEKS);
+  const [before, last] = rotationSeries(weeks.map((week) => ratio(week.day))).slice(-2);
+  if (before?.strength == null || before.momentum == null || last?.strength == null || last.momentum == null) {
+    throw new Error(`Need ${ROTATION_ALERT_WEEKS} contiguous weekly closes.`);
+  }
+  const week = weeks.at(-1)!;
+  return { value: last.strength, target: last.momentum, previousValue: before.strength, previousTarget: before.momentum, day: week.day, at: week.at };
+}
+
+/** RS ratios and RRG quadrants take the benchmark's completed daily bars as well. */
+export function dailyMetricReading(
+  rule: MetricRule,
+  bars: readonly DailyBar[],
+  now: number,
+  session: (day: string) => DailySession | null,
+  benchmarkBars?: readonly DailyBar[],
+): MetricReading {
+  const m = rule.metric!;
+  if (m.kind === "rs_ratio" || m.kind === "rrg") {
+    if (!benchmarkBars) throw new Error(`Completed daily history for ${m.benchmark} is required.`);
+    return relativeMetricReading(rule, m, bars, benchmarkBars, now, session);
+  }
+  if (!isDailyMetric(m) || !("period" in m)) throw new Error("Expected a daily technical alert.");
+  const latest = latestSettledClose(now, session);
+  const byDay = closesThrough(bars, latest.day);
   const days = [...byDay.keys()].sort();
   if (days.at(-1) !== latest.day) throw new Error(`Waiting for the ${latest.day} daily close.`);
   const needed = m.kind === "close_ma" ? m.period : (m.kind === "ma_cross" ? m.slowPeriod : m.period) + 1;
@@ -165,9 +304,19 @@ export function metricTrigger(rule: MetricRule, reading: MetricReading): "above"
   if (isDailyMetric(rule.metric!)) {
     if (!reading.day || reading.day <= (rule.lastDailyClose ?? "") || reading.at <= (rule.armedAt ?? rule.createdAt ?? Infinity)) return null;
   }
+  const m = rule.metric!;
+  if (m.kind === "rrg") {
+    // Fires on entering the quadrant, not on a week already inside it.
+    const before = rotationQuadrant(reading.previousValue, reading.previousTarget)?.toLowerCase();
+    return before && before !== m.quadrant && rotationQuadrant(reading.value, reading.target)?.toLowerCase() === m.quadrant ? "up" : null;
+  }
   if (rule.condition === "above") return reading.value > reading.target ? "above" : null;
   if (rule.condition === "below") return reading.value < reading.target ? "below" : null;
-  const m = rule.metric!;
+  if (m.kind === "rs_ratio") {
+    if (!finite(reading.previousValue)) return null;
+    if (reading.previousValue <= reading.target && reading.value > reading.target) return "up";
+    return reading.previousValue >= reading.target && reading.value < reading.target ? "down" : null;
+  }
   if (m.kind !== "ma_cross" || !finite(reading.previousValue) || !finite(reading.previousTarget)) return null;
   if (m.direction === "above" && reading.previousValue <= reading.previousTarget && reading.value > reading.target) return "up";
   if (m.direction === "below" && reading.previousValue >= reading.previousTarget && reading.value < reading.target) return "down";

package/src/plugins/builtin/alerts/metric-parity-fixture.json

@@ -1,5 +1,5 @@
 {
-  "modelSha256": "2364694ef384760911a9190f6ebb12bb66442e63c98defd30e16fd0bb731afd4",
+  "modelSha256": "7672569b5c80bb737181cb6a85e72b07e659d706e1792e5a89e8d570ae0ec581",
   "valuations": [
     {
       "name": "regular",