@gloom-sh/terminal 0.18.5 → 0.19.1

package/src/plugins/builtin/relative-rotation/model.ts

@@ -2,6 +2,7 @@ import { publishedWeekClose } from "../analytics/sharpe-cadence";
 import { historyStatistics } from "../../../components/chart/curve/model";
 import type { CloudPricePointPayload } from "../../../api-client/types";
 import { getSectorCollection } from "../sectors/sector-data";
+import { rotationQuadrant, rotationSeries, type RotationQuadrantName } from "../alerts/metric-model";
 import {
   canonicalExchange,
   normalizeSymbol,
@@ -11,6 +12,8 @@ import {
 const DAY = 86_400_000;
 const WEEK = 7 * DAY;
 export const ROTATION_LIMIT = 24;
+/** RRG's benchmark when none is chosen; RRG alerts default to it too. */
+export const DEFAULT_ROTATION_BENCHMARK = "SPY:NYSEARCA";
 export interface RotationInstrument {
   symbol: string;
   exchange: string;
@@ -46,8 +49,7 @@ export interface RotationRow {
   asOf: string | null;
   strength: number | null;
   momentum: number | null;
-  quadrant:
-    "Leading" | "Weakening" | "Lagging" | "Improving" | "Neutral" | null;
+  quadrant: RotationQuadrantName | null;
   strengthRank: RotationRank;
   momentumRank: RotationRank;
   relativeReturn13w: number | null;
@@ -149,21 +151,8 @@ function rotationRank(
     lastDate: stats.endDate,
   };
 }
-export function rotationQuadrant(
-  strength: number | null,
-  momentum: number | null,
-): RotationRow["quadrant"] {
-  if (strength == null || momentum == null) 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";
-}
+/** The weekly strength, momentum and quadrant math is the RRG alert's, shared with Gloom Cloud's delivery. */
+export { rotationQuadrant };
 export function buildRotation(
   benchmark: RotationHistory,
   instruments: RotationHistory[],
@@ -219,10 +208,12 @@ export function buildRotation(
   const benchmarkUsable = !!benchmark.currency && !!asOf;
   const rows = instruments.map((source): RotationRow => {
     const closes = rotationCloses(source.points, through);
+    // A benchmark with no usable weeks says so once in `gaps`; its rows are not to blame for it.
     const gaps = [
       source.error,
       source.stale ? "History is stale." : null,
-      source.currency !== benchmark.currency || !source.currency
+      benchmarkUsable &&
+      (source.currency !== benchmark.currency || !source.currency)
         ? "Price currency does not match the benchmark."
         : null,
     ].filter((x): x is string => !!x);
@@ -240,34 +231,16 @@ export function buildRotation(
         ? ratio
         : 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 mean =
-        (window as number[]).reduce((sum, value) => sum + value, 0) / 13;
-      return (100 * ratio) / mean;
-    });
+    const series = rotationSeries(ratios);
     const history = weeks.map((week, index): RotationPoint => {
-      const strength = strengths[index] ?? null,
-        previous = index >= 4 ? (strengths[index - 4] ?? null) : null;
-      const contiguous =
-        index >= 4 &&
-        strengths.slice(index - 4, index + 1).every((value) => value != null);
+      const { strength, momentum } = series[index]!;
       const priorRatio = index >= 13 ? (ratios[index - 13] ?? null) : null,
         ratio = ratios[index] ?? null;
       return {
         date: weekly.get(week)?.date ?? week,
         week,
         strength,
-        momentum:
-          strength != null && previous != null && contiguous
-            ? (100 * strength) / previous
-            : null,
+        momentum,
         relativeReturn13w:
           ratio != null &&
           priorRatio != null &&
@@ -284,7 +257,10 @@ export function buildRotation(
       Number.isFinite(latest.strength) &&
       latest.momentum != null &&
       Number.isFinite(latest.momentum);
-    if (!latest || latest.strength == null || latest.momentum == null)
+    if (
+      benchmarkUsable &&
+      (!latest || latest.strength == null || latest.momentum == null)
+    )
       gaps.push(
         "At least 17 contiguous matched weekly closes are required; a missing week breaks the trail.",
       );

package/src/plugins/builtin/relative-rotation/pane.tsx

@@ -36,6 +36,7 @@ import {
 import { useResearchCloudSession } from "../shared/research-cloud-session";
 import { cachedRotation, loadRotation } from "./client";
 import {
+  DEFAULT_ROTATION_BENCHMARK,
   ROTATION_LIMIT,
   rotationId,
   rotationTrailWeeks,
@@ -140,13 +141,13 @@ function RotationDetail({
 export function RelativeRotationPane(props: PaneProps) {
   const [scope] = usePaneSettingValue("scope", "sectors");
   const [symbols] = usePaneSettingValue("symbols", "");
-  const [benchmarkText] = usePaneSettingValue("benchmark", "SPY:NYSEARCA");
+  const [benchmarkText] = usePaneSettingValue("benchmark", DEFAULT_ROTATION_BENCHMARK);
   const [trailText] = usePaneSettingValue("trail", "6");
   const { collectionId } = usePaneCollection();
   const tickers = useTickers();
   const context = useMemo(() => {
     try {
-      const references = rotationInstruments(benchmarkText || "SPY:NYSEARCA");
+      const references = rotationInstruments(benchmarkText || DEFAULT_ROTATION_BENCHMARK);
       if (references.length !== 1)
         throw new Error("Choose one benchmark in pane settings.");
       const instruments =

package/src/plugins/builtin/research/corporate-actions-pane.tsx

@@ -446,6 +446,7 @@ export function CorporateActionsView({
   const financialCurrency = tickerFinancials?.financialCurrency;
   const trailingEps = tickerFinancials?.fundamentals?.eps;
   const trailingEpsCurrency = tickerFinancials?.fundamentals?.epsCurrency;
+  const trailingEpsSource = tickerFinancials?.fundamentals?.trailingEpsSource;
   const fundamentalsCurrency = tickerFinancials?.fundamentals?.financialCurrency;
   const marketCapCurrency = tickerFinancials?.fundamentals?.marketCapCurrency;
   const quoteCurrency = tickerFinancials?.quote?.currency;
@@ -453,10 +454,10 @@ export function CorporateActionsView({
     () => (quarterlyStatements || financialCurrency || trailingEps != null ? {
       quarterlyStatements: quarterlyStatements ?? [],
       financialCurrency,
-      fundamentals: { eps: trailingEps, epsCurrency: trailingEpsCurrency, financialCurrency: fundamentalsCurrency, marketCapCurrency },
+      fundamentals: { eps: trailingEps, epsCurrency: trailingEpsCurrency, financialCurrency: fundamentalsCurrency, marketCapCurrency, trailingEpsSource },
       quote: quoteCurrency ? { currency: quoteCurrency } : null,
     } : null),
-    [financialCurrency, fundamentalsCurrency, marketCapCurrency, quarterlyStatements, quoteCurrency, trailingEps, trailingEpsCurrency],
+    [financialCurrency, fundamentalsCurrency, marketCapCurrency, quarterlyStatements, quoteCurrency, trailingEps, trailingEpsCurrency, trailingEpsSource],
   );
   const actionsLoader = useCallback((nextSymbol: string, nextExchange: string, forceRefresh: boolean) => {
     if (!dataProvider?.getCorporateActions) throw new Error("Corporate actions source unavailable");

package/src/plugins/builtin/research/event-model.ts

@@ -15,7 +15,7 @@ import {
 } from "../../../utils/format";
 import { computeTTM } from "../ticker-detail/financials/aggregation";
 import { declaredDividends } from "../../../utils/declared-dividends";
-import { fundamentalsEpsCurrency } from "../../../utils/fundamentals";
+import { fundamentalsEpsCurrency, SERVED_TRAILING_EPS } from "../../../utils/fundamentals";
 import {
   earningsDateStatus,
   earningsDetail,
@@ -175,11 +175,11 @@ function estimateValue(pair: EstimatePair): string {
 }
 
 /**
- * What the TTM row reads: the statements for its four quarters and revenue, and the trailing EPS Gloom Cloud serves
- * with the fundamentals, the figure `ticker` prints as EPS (TTM).
+ * What the TTM row reads: the statements for its four quarters and revenue, and the trailing EPS of the fundamentals,
+ * the figure `ticker` prints as EPS (TTM) (the filed quarters' when they give one, see time-series/filed-trailing-eps).
  */
 export type EventFinancials = Pick<TickerFinancials, "quarterlyStatements" | "financialCurrency"> & {
-  fundamentals?: Pick<NonNullable<TickerFinancials["fundamentals"]>, "eps" | "epsCurrency" | "financialCurrency" | "marketCapCurrency"> | null;
+  fundamentals?: Pick<NonNullable<TickerFinancials["fundamentals"]>, "eps" | "epsCurrency" | "financialCurrency" | "marketCapCurrency" | "trailingEpsSource"> | null;
   /** The listing's currency, which says whether an unlabelled EPS can be in the statements' (fundamentalsCurrency). */
   quote?: Pick<NonNullable<TickerFinancials["quote"]>, "currency"> | null;
 };
@@ -204,9 +204,10 @@ function adjustedQuarterSum(
 }
 
 /**
- * The TTM row's EPS is the GAAP diluted trailing figure, the one `ticker` prints as EPS (TTM). Without it, the four
- * statement quarters' diluted EPS summed. The reported rows above it are often adjusted, so they are never added to
- * it: only when all four are adjusted does the detail also give their sum.
+ * The TTM row's EPS is the GAAP diluted trailing figure `ticker` prints as EPS (TTM): the last four filed quarters',
+ * or Gloom Cloud's trailing figure, named so, when they give none. Without either, the four statement quarters'
+ * diluted EPS summed. The reported rows above it are often adjusted, so they are never added to it: only when all
+ * four are adjusted does the detail also give their sum.
  */
 function ttmRow(
   quarterlyStatements: readonly FinancialStatement[],
@@ -226,7 +227,8 @@ function ttmRow(
     date: latest?.date ?? "",
     status: "TTM",
     period: "4 qtrs",
-    detail: [eps == null ? "statement sum" : served ? "GAAP diluted" : "GAAP diluted (statements)",
+    detail: [eps == null ? "statement sum" : !served ? "GAAP diluted (statements)"
+      : financials?.fundamentals?.trailingEpsSource === "served" ? `GAAP diluted (${SERVED_TRAILING_EPS})` : "GAAP diluted",
       adjusted == null ? null : `adj sum ${formatNumber(adjusted, 2)}`].filter(Boolean).join(", "),
     epsCurrency: served ? fundamentalsEpsCurrency(financials) : ttm.currency ?? financials?.financialCurrency,
     revenueCurrency: ttm.currency ?? financials?.financialCurrency,
@@ -420,7 +422,8 @@ export function buildEventRows(
       date: dividend.exDate,
       status: "Dividend",
       period: "-",
-      detail: dividend.payDate ? `Declared, payable ${dividend.payDate}` : "Declared",
+      // A one-off beside the regular payments says so: "Declared special, payable 2026-11-25".
+      detail: `Declared${dividend.special ? " special" : ""}${dividend.payDate ? `, payable ${dividend.payDate}` : ""}`,
       value: formatDistributionAmount(dividend.amount, data?.currency ?? currency),
       tone: "positive",
     });
@@ -478,9 +481,14 @@ export function eventSourceNotice(state: EventSourceState): EventSourceNotice |
   const unavailableSections = Object.entries(state.actions?.coverage ?? {})
     .filter(([section, status]) => status === "unavailable" && (state.variant !== "earnings-estimates" || section === "earnings"))
     .map(([section]) => section);
+  // Sections and estimates that a source failed to give share one line: "Unavailable: earnings, analyst estimates (the source did not answer)".
+  const estimatesCode = !!state.estimatesError && REASON_CODE.test(state.estimatesError.trim());
+  const sharedLine = !state.actionsError && unavailableSections.length > 0 && estimatesCode;
 
   if (state.actionsError) {
-    notices.push(`${actionsLabel} unavailable: ${state.actionsError}`);
+    notices.push(`${actionsLabel} unavailable: ${sourceErrorText(state.actionsError)}`);
+  } else if (sharedLine) {
+    notices.push(`Unavailable: ${unavailableSections.join(", ")}, analyst estimates (${sourceErrorText(state.estimatesError!)})`);
   } else if (unavailableSections.length > 0) {
     notices.push(`Unavailable: ${unavailableSections.join(", ")}`);
   } else if (state.actions && !(state.variant === "earnings-estimates"
@@ -495,7 +503,7 @@ export function eventSourceNotice(state: EventSourceState): EventSourceNotice |
   if (state.estimates?.stale) notices.push(`Analyst estimates stale${state.estimates.fetchedAt ? ` (fetched ${state.estimates.fetchedAt})` : ""}`);
 
   if (state.estimatesError) {
-    notices.push(`Analyst estimates unavailable: ${state.estimatesError}`);
+    if (!sharedLine) notices.push(`Analyst estimates unavailable: ${sourceErrorText(state.estimatesError)}`);
   } else if (state.estimates && !hasAnalystEstimates(state.estimates)) {
     notices.push(`No analyst estimates for ${state.symbol}`);
   }
@@ -507,8 +515,28 @@ export function eventSourceNotice(state: EventSourceState): EventSourceNotice |
   };
 }
 
+/** A data service's reason code (UPSTREAM_ERROR) rather than words. */
+const REASON_CODE = /^[A-Z][A-Z0-9_]+$/;
+
+/**
+ * A source's failure in words: a reason code reads as what happened
+ * ("UPSTREAM_ERROR" is "the source did not answer"); a sentence stands.
+ */
+export function sourceErrorText(error: string): string {
+  const text = error.trim();
+  if (!REASON_CODE.test(text)) return text;
+  switch (text) {
+    case "TIMEOUT": return "the source timed out";
+    case "NOT_FOUND":
+    case "NO_DATA": return "the source has none for this symbol";
+    case "RATE_LIMITED": return "the source is busy, try again shortly";
+    default: return "the source did not answer";
+  }
+}
+
 function hasCorporateActionRows(data: CorporateActionsData): boolean {
-  return data.dividends.length > 0 || data.splits.length > 0 || data.earnings.length > 0;
+  // A declared dividend is a row too: AIOK's $3.50 special with nothing paid yet.
+  return data.dividends.length > 0 || data.splits.length > 0 || data.earnings.length > 0 || declaredDividends(data).length > 0;
 }
 
 function hasAnalystEstimates(data: AnalystResearchData): boolean {

package/src/plugins/builtin/research/headless.ts

@@ -83,7 +83,7 @@ function projectEarningsEstimatesHeadless(
       returned: rows.length,
       truncated: rows.length < matching.length,
       coverageNote: notice?.text,
-      epsBasis: `${EPS_BASIS_NOTE} The TTM row's EPS is the GAAP diluted trailing figure ticker shows as EPS (TTM), or the four statement quarters' diluted EPS when none is served; reported quarters of different bases are never summed, and the row adds an adjusted sum only when all four quarters are adjusted.`,
+      epsBasis: `${EPS_BASIS_NOTE} The TTM row's EPS is the GAAP diluted trailing figure ticker shows as EPS (TTM): the last four filed quarters', or Gloom Cloud's TTM (named so) when they give none, or the four statement quarters' diluted EPS when neither is there; reported quarters of different bases are never summed, and the row adds an adjusted sum only when all four quarters are adjusted.`,
       dateNote: "Fiscal period dates are not announcement dates. Revenue is attached only to an identified statement period.",
       unmatchedReportedPeriods,
     },

package/src/plugins/builtin/research/index.tsx

@@ -6,6 +6,8 @@ import { CorporateActionsView } from "./corporate-actions-pane";
 import { EquityDiagnosticView } from "./equity-diagnostic-pane";
 import { RelativeValuationPane } from "./relative-valuation-pane";
 import { relativeValuationHeadless } from "./relative-valuation-headless";
+import { AUTO_PEERS_SETTING, relativeValuationTitle } from "./relative-valuation-peers";
+import { buildRelativeValuationSettingsDef, MAX_RELATIVE_VALUATION_TICKERS } from "./relative-valuation-settings";
 import { analystResearchHeadless } from "./analyst-headless";
 import { eventsHeadless } from "./events-headless";
 import { earningsEstimatesHeadless } from "./headless";
@@ -95,6 +97,7 @@ export const researchModule: PluginModule = {
       defaultMode: "floating",
       defaultFloatingSize: { width: 104, height: 24 },
       tableExport: true,
+      settings: buildRelativeValuationSettingsDef,
     },
     {
       id: "earnings-estimates",
@@ -168,14 +171,15 @@ export const researchModule: PluginModule = {
         try {
           symbols = options?.symbols?.length
             ? options.symbols
-            : parseTickerListInput(options?.arg ?? context.activeTicker ?? "", 12);
+            : parseTickerListInput(options?.arg ?? context.activeTicker ?? "", MAX_RELATIVE_VALUATION_TICKERS);
         } catch {
           return null;
         }
         return {
-          title: `RV ${formatTickerListInput(symbols)}`,
+          title: relativeValuationTitle(symbols, null),
           placement: "floating",
-          settings: { symbols, symbolsText: formatTickerListInput(symbols) },
+          // One ticker is compared with the peers `--peers` picks, which the pane finds once it opens.
+          settings: { symbols, symbolsText: formatTickerListInput(symbols), ...(symbols.length === 1 ? { [AUTO_PEERS_SETTING]: true } : {}) },
         };
       },
     },

package/src/plugins/builtin/research/relative-valuation-headless.ts

@@ -8,11 +8,10 @@ import {
   RELATIVE_VALUATION_STALE_FUNDAMENTALS_NOTICE, RELATIVE_VALUATION_STALE_QUOTE_NOTICE, relativeValuationValues, type RelativeValuationGapKey,
 } from "./relative-valuation-model";
 import { paneSchemas } from "./headless-schema";
-import { isRecord } from "../../../utils/guards";
-import { errorMessage } from "../../../utils/errors";
-import { notATickerSymbol } from "../../../sources/provider-errors";
 import { resolveCurrencyUnit } from "../../../utils/currency-units";
-import { pickPeers, peerMethodTitle, type PeerSelection } from "./relative-valuation-peers";
+import {
+  AUTO_PEERS_SETTING, findPeers, peerMethodTitle, peerSelectionOf, PEER_SELECTION_SETTING, relativeValuationTitle, type PeerSelection,
+} from "./relative-valuation-peers";
 import { extraColumns, extraColumnsBasis, loadExtraColumns, parseExtraColumns } from "./relative-valuation-columns";
 import { fundamentalsBasisParts } from "./relative-valuation-basis";
 import { conversionNote, convertMarketCaps, loadFxLegs } from "./relative-valuation-currency";
@@ -96,37 +95,21 @@ const VALUATION_COLUMNS: HeadlessPaneColumn[] = [
   ...([["fcfYield", "FCF Yield"], ["revenueGrowth", REVENUE_GROWTH_HEADER], ["operatingMargin", "TTM Op Margin"]] as const).map(([key, header]) => ({
     key, header, align: "right" as const,
     format: (value: unknown, row: Record<string, unknown>) => value == null ? gapText(row, key)
-      : key === "revenueGrowth" ? formatPercent(Number(value)) : formatLevelPercent(Number(value)),
+      : key === "revenueGrowth" ? formatPercent(Number(value))
+        // A margin of the latest fiscal year, where no trailing quarters were served, says which year.
+        : key === "operatingMargin" && typeof row.operatingMarginPeriod === "string"
+          ? `${formatLevelPercent(Number(value))} ${row.operatingMarginPeriod}` : formatLevelPercent(Number(value)),
   })),
 ];
 
-/** Peers `--peers` chose, as the expansion left them in the settings or the load picked them. */
-function peerSelectionOf(value: unknown, symbols: readonly string[]): PeerSelection | null {
-  if (!isRecord(value) || typeof value.subject !== "string" || !Array.isArray(value.peers)) return null;
-  const selection = value as unknown as PeerSelection;
-  const expected = [selection.subject, ...selection.peers];
-  return expected.length === symbols.length && expected.every((symbol, index) => symbol.toUpperCase() === symbols[index]?.toUpperCase())
-    ? selection : null;
-}
-
 /** The peers of the one symbol `--peers` was given; several symbols are already a peer list. */
 async function choosePeers(symbols: readonly string[], ctx: HeadlessPaneContext): Promise<PeerSelection> {
   if (symbols.length !== 1) {
     throw new Error(`--peers picks the peers of one symbol, such as RV ${symbols[0] ?? "DUOL"} --peers; with several symbols, leave it out.`);
   }
-  const subject = symbols[0]!;
-  const financials = await loadHeadlessFinancials(ctx, subject).catch((error: unknown) => {
-    ctx.signal.throwIfAborted();
-    // A word that is no ticker is said as `fn RV duolingo lrn` says it, which the CLI follows with the search to run.
-    if (notATickerSymbol(errorMessage(error))) throw error;
-    // Any other failure leaves the peers to what the symbol alone places (a curated core's member).
-    return null;
-  });
-  return pickPeers(subject, financials, ctx);
+  return findPeers(symbols[0]!, ctx);
 }
 
-const PEER_SELECTION_SETTING = "peerSelection";
-
 export const relativeValuationHeadless: HeadlessPaneDefinition<"rows"> = {
   ...paneSchemas["relative-valuation-pane"],
   // What Ask Gloom reads. The template's "across peers" never said this is where a list of holdings' P/E is.
@@ -146,9 +129,12 @@ export const relativeValuationHeadless: HeadlessPaneDefinition<"rows"> = {
     return {
       argument: [selection.subject, ...selection.peers].join(", "),
       settings: { [PEER_SELECTION_SETTING]: selection },
-      title: `RV ${selection.subject} + ${peerMethodTitle(selection, { automatic: true })}`,
+      title: relativeValuationTitle([], selection),
     };
   },
+  // The app adds the peers of a pane opened on one ticker; a capture draws the tickers given, as the report does,
+  // unless --peers widened them.
+  shotState: (args) => args.options.peers === true ? {} : { settings: { [AUTO_PEERS_SETTING]: false } },
   async load(args, ctx) {
     // --peers picked in advance (fn and shot) reads the same peers; any other caller picks them here.
     const preset = args.options.peers === true ? peerSelectionOf(ctx.settings?.[PEER_SELECTION_SETTING], args.symbols) : null;
@@ -226,6 +212,7 @@ export const relativeValuationHeadless: HeadlessPaneDefinition<"rows"> = {
           ...rows.flatMap((row) => row.evSalesUnavailable ? [`${row.symbol}: ${row.evSalesUnavailable}`] : []),
           ...rows.flatMap((row) => row.evSalesNote ? [`${row.symbol}: ${row.evSalesNote}`] : []),
           ...rows.flatMap((row) => row.marketCapNote ? [`${row.symbol}: ${row.marketCapNote}`] : []),
+          ...rows.flatMap((row) => row.marketCapWithheld ? [`${row.symbol}: ${row.marketCapWithheld}`] : []),
         ],
         multipleBasis: "Comparable P/E fields require a positive finite multiple over positive EPS, and evSales an enterprise value above zero; notMeaningful says why one is null, and reportedMultiples preserves the finite provider P/E values.",
         marketCapBasis: "Market caps retain their own currency and source. Fundamentals retrieval time is not a valuation date; quote timestamps do not date fallback caps.",

package/src/plugins/builtin/research/relative-valuation-model.ts

@@ -1,9 +1,10 @@
 import { formatCurrency } from "../../../utils/format";
 import { comparablePriceEarnings, notMeaningfulMultiples } from "../../../utils/price-earnings";
-import { marketCapBasisNote, viewMarketCapitalization } from "../../../utils/market-capitalization";
+import { marketCapBasisNote, viewMarketCapitalization, withheldMarketCap } from "../../../utils/market-capitalization";
 import { enterpriseValueNotMeaningful, enterpriseValueReconciliationNote, enterpriseValueWithdrawn, reportedEnterpriseValue } from "../../../utils/fundamentals";
 import { getExtendedSessionDisplay, getQuoteSessionFields } from "../../../market-data/market/status";
 import { atRegularSessionPrice, movePriceDerivedFigures, regularSessionValuationPrice } from "../../../market-data/quotes/regular-session-valuation";
+import { fiscalPeriodLabel, fiscalYearEndMonth } from "../../../utils/fiscal-period";
 import { latestFinancialPeriod, latestReportedPeriod } from "../../../utils/latest-financial-period";
 import type { Quote, TickerFinancials } from "../../../types/financials";
 
@@ -50,6 +51,25 @@ function fcfYieldGap(fundamentals: TickerFinancials["fundamentals"], capCurrency
 }
 export const RELATIVE_VALUATION_STALE_FUNDAMENTALS_NOTICE = "Fundamentals stale: retained values may be out of date";
 
+/**
+ * The operating margin of the latest fiscal year, for a row whose trailing
+ * twelve months are not whole (a quarter the source has not carried yet):
+ * that year's operating income over its revenue, named for the year ("FY25")
+ * so a cell never passes it off as trailing. Null when the latest year lacks
+ * either figure; an older year is never stood in for it.
+ */
+function fiscalYearOperatingMargin(annualStatements: TickerFinancials["annualStatements"] | undefined) {
+  const latest = latestFinancialPeriod(annualStatements, (row) => row.date);
+  if (!latest || !finiteNumber(latest.operatingIncome) || !finiteNumber(latest.totalRevenue) || latest.totalRevenue <= 0) return null;
+  const year = /^FY\d{2}(\d{2})$/.exec(fiscalPeriodLabel(latest.date, "annual", fiscalYearEndMonth(annualStatements ?? [])))?.[1];
+  return {
+    value: latest.operatingIncome / latest.totalRevenue,
+    // The fiscal year's own name; the calendar year of its end where the year cannot be named.
+    label: `FY${year ?? latest.date.slice(2, 4)}`,
+    periodEnd: latest.date.slice(0, 10),
+  };
+}
+
 /**
  * A peer's row. Last, its change and the extended print are the quote's
  * sessions as `quote` reads them (getQuoteSessionFields): after the close,
@@ -97,14 +117,17 @@ export function relativeValuationValues(snapshot: TickerFinancials | null) {
     && fundamentals.freeCashFlow != null && Number.isFinite(fundamentals.freeCashFlow) && capitalization.value > 0
     ? fundamentals.freeCashFlow / capitalization.value : null;
   const revenueGrowth = fundamentals?.revenueGrowth ?? fundamentals?.lastQuarterGrowth ?? null;
-  const operatingMargin = fundamentals?.operatingMargin ?? null;
+  const trailingOperatingMargin = fundamentals?.operatingMargin ?? null;
+  const fiscalYearMargin = trailingOperatingMargin == null ? fiscalYearOperatingMargin(financials?.annualStatements) : null;
+  const operatingMargin = trailingOperatingMargin ?? fiscalYearMargin?.value ?? null;
   const trailingPE = trailingNotMeaningful ? null : comparablePriceEarnings(reportedMultiples.trailingPE);
   const forwardPE = forwardNotMeaningful ? null : comparablePriceEarnings(reportedMultiples.forwardPE);
   // Every figure a row lacks says why, so an export's blank cell is never silent: N/M multiples say so themselves.
   const gaps: Partial<Record<RelativeValuationGapKey, string>> = {};
   if (session.price == null) gaps.price = quoteStale ? QUOTE_STALE : NOT_REPORTED;
   if (session.changePercent == null) gaps.changePercent = quoteStale ? QUOTE_STALE : NOT_REPORTED;
-  if (capitalization == null) gaps.marketCap = quoteStale && !fundamentals?.marketCap ? QUOTE_STALE : NOT_REPORTED;
+  const withheld = withheldMarketCap(fundamentals);
+  if (capitalization == null) gaps.marketCap = withheld?.gap ?? (quoteStale && !fundamentals?.marketCap ? QUOTE_STALE : NOT_REPORTED);
   if (trailingPE == null && !trailingNotMeaningful && reportedMultiples.trailingPE == null) gaps.trailingPE = NOT_REPORTED;
   if (forwardPE == null && !forwardNotMeaningful && reportedMultiples.forwardPE == null) gaps.forwardPE = NOT_REPORTED;
   if (evSales == null && !evSalesNotMeaningful) gaps.evSales = evSalesGap(fundamentals, quote?.currency, evSalesWithdrawn, enterpriseValueGap);
@@ -136,6 +159,8 @@ export function relativeValuationValues(snapshot: TickerFinancials | null) {
     marketCapProvenance: capitalization?.provenance ?? null,
     /** valuation's note when the cap is the share count times the price: the provider's figure it replaced. */
     marketCapNote: marketCapBasisNote(capitalization) ?? null,
+    /** Why Gloom Cloud withheld the cap (a receipt priced as ordinary shares), as `valuation` and EQS say it; null otherwise. */
+    marketCapWithheld: withheld?.note ?? null,
     trailingPE,
     forwardPE,
     reportedMultiples,
@@ -151,6 +176,9 @@ export function relativeValuationValues(snapshot: TickerFinancials | null) {
     fcfYield,
     revenueGrowth,
     operatingMargin,
+    /** The fiscal year the operating margin is of ("FY25") when no trailing figure was served; null when it is trailing twelve months. */
+    operatingMarginPeriod: fiscalYearMargin?.label ?? null,
+    operatingMarginPeriodEnd: fiscalYearMargin?.periodEnd ?? null,
     /** Why each missing figure is missing, in a few words the row draws in its place. */
     gaps,
   };