gloomberb 0.18.4 → 0.19.0

package/src/plugins/builtin/equity-screener/pane.tsx

@@ -36,7 +36,7 @@ import {
 } from "../../../public/react";
 import { useDialog } from "../../../ui/dialog";
 import { useThemeColors } from "../../../theme/theme-context";
-import { priceColor } from "../../../theme/colors";
+import { priceColor, shownPriceColor } from "../../../theme/colors";
 import { apiClient } from "../../../api-client";
 import {
   NUMERIC_FIELDS,
@@ -54,6 +54,7 @@ import { useSampledValue } from "../../../state/hooks/live-ticker-financials";
 import { usePlanAccess } from "../../../api-client/plan-access";
 import { SignInWall } from "../cloud/auth-actions";
 import { CriterionEditor } from "./criterion-editor";
+import { SCREEN_IDEAS, screenIdea } from "./ideas";
 import { ScreenTickerCheck } from "./ticker-check";
 import {
   fetchSavedScreens,
@@ -70,7 +71,9 @@ import {
   formatScreenValue,
   metricDate,
   parseScreenDefinition,
+  pickerFields,
   resultFields,
+  screenMetricSetting,
   SIGN_COLORED,
   screenColumnLabel,
   screenCurrencyEmpty,
@@ -80,6 +83,7 @@ import {
   screenYtdBase,
 } from "./model";
 import { useScreenResults } from "./results";
+import { unmatchedCategoryText, unmatchedCategoryValues } from "./categories";
 import { overlayLiveScreenRows, screenExtendedMove, screenExtendedSessions, sortLiveScreenRows, type LiveScreenRow } from "./live";
 import { useLiveQuoteEntries } from "../../../state/hooks/quote-streaming";
 import { buildScreenerQuoteTargets } from "../../../market-data/quotes/screener-live-quotes";
@@ -92,6 +96,7 @@ const TABS = [
   { value: "results", label: "Results" },
   { value: "criteria", label: "Criteria" },
   { value: "saved", label: "Saved" },
+  { value: "ideas", label: "Ideas" },
 ];
 const errorText = (error: unknown) =>
   error instanceof Error ? error.message : "Request failed.";
@@ -115,8 +120,10 @@ export function resultColumns(
   asOf: boolean,
   extendedSessions: readonly ExtendedSession[] = [],
   ytdBase: string | null = null,
+  /** Other metrics `--metric` asked for, shown first after the focus metric. */
+  otherMetrics: readonly NumericField[] = [],
 ): DataTableColumn[] {
-  const [focus, ...others] = resultFields(definition, metric);
+  const [focus, ...others] = resultFields(definition, metric, otherMetrics);
   const metricColumn = (field: NumericField, form: "pane" | "compact"): DataTableColumn => {
     const label = screenColumnLabel(field, ytdBase, form);
     return { id: `m:${field}`, label, width: columnWidth(field, label), align: "right" };
@@ -222,9 +229,12 @@ export function EquityScreenerPane(props: PaneProps) {
     "definition",
     undefined,
   );
+  // A ready screen from Ideas (`--preset`), which opens on its own metric.
+  const [presetId] = usePaneSettingValue<string | undefined>("preset", undefined);
+  const preset = screenIdea(presetId);
   let initial: ScreenDefinition;
   try {
-    initial = seed ? parseScreenDefinition(JSON.parse(seed)) : DEFAULT_SCREEN;
+    initial = preset?.definition ?? (seed ? parseScreenDefinition(JSON.parse(seed)) : DEFAULT_SCREEN);
   } catch (error) {
     return (
       <PaneStatusBody subject="screen definition" error={errorText(error)} />
@@ -232,9 +242,10 @@ export function EquityScreenerPane(props: PaneProps) {
   }
   return (
     <EquityScreenView
-      key={`${seed ?? "default"}:${session.requestKey}`}
+      key={`${preset?.id ?? seed ?? "default"}:${session.requestKey}`}
       {...props}
       initial={initial}
+      initialMetric={preset?.metric ?? "marketCap"}
     />
   );
 }
@@ -243,7 +254,8 @@ function EquityScreenView({
   height,
   focused,
   initial,
-}: PaneProps & { initial: ScreenDefinition }) {
+  initialMetric,
+}: PaneProps & { initial: ScreenDefinition; initialMetric: NumericField }) {
   const colors = useThemeColors(),
     dialog = useDialog(),
     host = useRendererHost();
@@ -253,10 +265,12 @@ function EquityScreenView({
   const session = useResearchCloudSession(),
     access = usePlanAccess();
   const [definition, setDefinition] = usePluginPaneState("definition", initial);
-  const [metric, setMetric] = usePaneSettingValue<NumericField>(
+  const [metricSetting, setMetric] = usePaneSettingValue<string>(
     "metric",
-    "marketCap",
+    initialMetric,
   );
+  // `--metric trailingPE,dividendYieldPercent` leads with the first and adds the others as columns.
+  const [metric, ...otherMetrics] = screenMetricSetting(metricSetting, initialMetric);
   const [mode, setMode] = usePluginPaneState("mode", "results");
   const [selectedId, setSelectedId] = usePluginPaneState<string | null>(
     "selected",
@@ -271,6 +285,10 @@ function EquityScreenView({
   const [savedSelectedId, setSavedSelectedId] = usePluginPaneState<
     string | null
   >("savedSelected", null);
+  const [ideaSelectedId, setIdeaSelectedId] = usePluginPaneState(
+    "ideaSelected",
+    SCREEN_IDEAS[0]!.id,
+  );
   const [currentSavedId, setCurrentSavedId] = usePluginPaneState<string | null>(
     "currentSaved",
     null,
@@ -356,8 +374,10 @@ function EquityScreenView({
     !opened && !results.loading && !results.loadingMore && !!data?.nextCursor,
     results.loadMore,
   );
-  const metricFields =
-    fields.data?.fields.filter((field) => field.kind === "number") ?? [];
+  const metricFields = pickerFields(
+    fields.data?.fields.filter((field) => field.kind === "number") ?? [],
+    [metric],
+  );
   // AS OF earns its column only when some row's focus metric is stale; the
   // snapshot decides, so a live quote freshening a row does not reflow the table.
   const staleFocus = snapshotRows.some((row) => row.metrics[metric]?.state === "stale");
@@ -367,7 +387,11 @@ function EquityScreenView({
   const ytdBase = screenYtdBase(snapshotRows, data?.snapshot?.assembledAt);
   // A screen its currency emptied says so, not that no company matches.
   const currencyEmpty = data && data.rows.length === 0 ? screenCurrencyEmpty(data.definition, data.universe) : null;
-  const columns = resultColumns(width, definition, metric, staleFocus, extendedSessions, ytdBase);
+  // A criterion's name that matches nothing (`Utility`) says so with the names it was likely meant as.
+  const unmatchedNames = data && data.rows.length === 0
+    ? unmatchedCategoryValues(data.definition, data).map(unmatchedCategoryText).join(" ") || null
+    : null;
+  const columns = resultColumns(width, definition, metric, staleFocus, extendedSessions, ytdBase, otherMetrics);
   const apply = (next: ScreenDefinition) => {
     try {
       setDefinition(parseScreenDefinition(next));
@@ -494,7 +518,7 @@ function EquityScreenView({
   useAutoRefresh(results.updatedAt, results.load);
   const openQueryControl = () => queryControl.current?.open();
   const hints =
-    saveForm || editing !== null || check
+    saveForm || editing !== null || check || mode === "ideas"
       ? []
       : mode === "criteria"
         ? [
@@ -783,7 +807,7 @@ function EquityScreenView({
               editing !== null ? (
                 <CriterionEditor
                   key={editing}
-                  fields={fields.data.fields}
+                  fields={pickerFields(fields.data.fields, editingCriterion ? [editingCriterion.field] : [])}
                   value={editingCriterion ?? null}
                   focused={focused}
                   width={width}
@@ -863,6 +887,36 @@ function EquityScreenView({
           />
         ) : null}
       </PaneStatusBody>
+    ) : mode === "ideas" ? (
+      <DataTableView
+        columns={[
+          { id: "name", label: "SCREEN", width: 28, align: "left" },
+          { id: "criteria", label: "CRITERIA", width: 20, flexGrow: 1, align: "left" },
+        ]}
+        items={SCREEN_IDEAS}
+        focused={focused && !saveForm}
+        rootWidth={width}
+        rootHeight={bodyHeight}
+        getItemKey={(row) => row.id}
+        selection={{
+          kind: "id",
+          selectedId: ideaSelectedId,
+          getId: (row) => row.id,
+          onChange: setIdeaSelectedId,
+        }}
+        onActivate={(row) => {
+          setMetric(row.metric);
+          apply(row.definition);
+          setCurrentSavedId(null);
+          setMode("results");
+        }}
+        renderCell={(row, column) => ({
+          text: column.id === "name" ? row.name : row.definition.criteria.map(criterionText).join("; "),
+        })}
+        sortColumnId={null}
+        sortDirection="asc"
+        emptyStateTitle="No ideas."
+      />
     ) : mode === "saved" ? (
       !access.emailVerified ? (
         <SignInWall
@@ -987,7 +1041,7 @@ function EquityScreenView({
                 const move = screenExtendedMove(row, column.id.slice(EXTENDED_COLUMN_PREFIX.length) as ExtendedSession);
                 return move == null
                   ? { text: "--", color: colors.textDim }
-                  : { text: formatPercentRaw(move), color: priceColor(move, colors) };
+                  : { text: formatPercentRaw(move), color: shownPriceColor(move, 2, colors) };
               }
               const field = column.id.startsWith("m:")
                 ? (column.id.slice(2) as NumericField)
@@ -1042,8 +1096,9 @@ function EquityScreenView({
                 },
               });
             }}
-            emptyStateTitle={currencyEmpty?.title ?? "No equities match this screen."}
-            emptyStateHint={currencyEmpty ? `${currencyEmpty.detail} Choose ${currencyEmpty.base.currency} to screen in the base currency.` : undefined}
+            emptyStateTitle={(unmatchedNames ? null : currencyEmpty?.title) ?? "No equities match this screen."}
+            emptyStateHint={unmatchedNames
+              ?? (currencyEmpty ? `${currencyEmpty.detail} Choose ${currencyEmpty.base.currency} to screen in the base currency.` : undefined)}
           />
         </PaneStatusBody>
       </>

package/src/plugins/builtin/exposure/charts.tsx

@@ -4,7 +4,7 @@ import { Box, ChartSurface, Text, useUiCapabilities } from "../../../ui";
 import { useThemeColors } from "../../../theme/theme-context";
 import type { ChartVectorShape } from "../../../ui/host";
 import type { ExposureComponent } from "../../../api-client/exposure";
-import { basisLabel, rangeText, type ExposureRow } from "./model";
+import { basisLabel, hopsText, rangeText, type ExposureRow } from "./model";
 import { truncateToDisplayWidth } from "../../../utils/format";
 
 /** A disclosure-bound interval, not a probability band. Same numerical domain on both renderers. */
@@ -53,7 +53,7 @@ export function ExposurePathDiagram({ component, width, height }: { component: E
   const nodeWidth = Math.max(8, Math.floor((width - 2) / nodes.length));
   const vectors: ChartVectorShape[] = hops.map((hop, i) => ({ id: `${i}`, points: [{ x: (i + .5) / nodes.length, y: .5 }, { x: (i + 1.5) / nodes.length, y: .5 }], color: hop.pct === null ? colors.textDim : colors.warning, strokeWidth: 2, handles: true }));
   return <Box flexDirection="column" height={height} overflow="hidden">
-    <Box paddingX={1} height={1} flexShrink={0}><Text fg={colors.textDim}>{hops.length} hop{hops.length === 1 ? "" : "s"} · {component.classification}{component.exposurePct ? ` · ${rangeText(component.exposurePct)}` : ""}</Text></Box>
+    <Box paddingX={1} height={1} flexShrink={0}><Text fg={colors.textDim}>{hopsText(hops.length)} · {component.classification}{component.exposurePct ? ` · ${rangeText(component.exposurePct)}` : ""}</Text></Box>
     <Box flexDirection="row" height={1} flexShrink={0} paddingX={1}>{nodes.map((node, i) => <Box key={`${node.id}:${i}`} width={nodeWidth} alignItems="center"><ClippedText fg={colors.textBright} text={node.symbol ?? node.name} width={nodeWidth - 2} /></Box>)}</Box>
     <Box height={1} flexShrink={0} paddingX={1}>
       {desktop ? <ChartSurface width={width - 2} height={1} vectors={vectors} /> : <Text fg={colors.textDim}>{nodes.map((_, i) => i < hops.length ? "─".repeat(Math.max(1, nodeWidth - 2)) + "→ " : "").join("")}</Text>}

package/src/plugins/builtin/exposure/model.ts

@@ -1,4 +1,5 @@
 import type { ExposureBasis, ExposureComponent, ExposureExtensionObservation, ExposureHolding, ExposurePayload, ExposureRange, ExposureScenario } from "../../../api-client/exposure";
+import { quarterLabel } from "../shared/earnings-report";
 import { humanLabel } from "../shared/research-cells";
 
 export const TABS = [{ value: "table", label: "Table" }, { value: "drivers", label: "Drivers" }, { value: "paths", label: "Paths" }, { value: "portfolio", label: "Portfolio" }];
@@ -14,6 +15,17 @@ export const basisLabel = (basis: string | null) => basis?.replaceAll("_", " ")
 const pct = (value: number) => `${value.toFixed(1)}%`;
 export const rangeText = (range: ExposureRange | null) => !range ? "Unknown" : range.low === range.high ? pct(range.low) : `${range.low.toFixed(1)} to ${range.high.toFixed(1)}%`;
 export const fraction = (value: number) => pct(value * 100);
+/** "1 hop", "2 hops". */
+export const hopsText = (count: number) => `${count} hop${count === 1 ? "" : "s"}`;
+/**
+ * A reporting period as the tables word it. The server keys a quarter by its end date (`quarter:2026-07-31`), which
+ * reads as the month it ends in, Jul 2026, as the earnings events label a quarter; a date or a source's own words
+ * stay as they are.
+ */
+export function periodText(period: string): string {
+  const quarter = /^quarter:(\d{4}-\d{2}(?:-\d{2})?)$/.exec(period);
+  return quarter ? quarterLabel(quarter[1]) : period;
+}
 
 /** A weighted list is entirely explicit. Never silently fill missing weights or normalize shorts. */
 export function parseHoldings(text: string): ExposureHolding[] {
@@ -78,7 +90,7 @@ export function exposureCellText(row: ExposureRow, column: "label" | "basis" | "
     // What the number rests on, in words: disclosed by the company, estimated by a chain, or not visible.
     case "classification": return `${humanLabel(row.classification)}${row.incomplete && row.classification !== "unknown" ? " · partial" : ""}`;
     case "impact": return row.impact ? rangeText(row.impact) : "--";
-    case "period": return row.period ?? "--";
+    case "period": return row.period ? periodText(row.period) : "--";
     case "weight": return fraction(row.weight ?? 0);
   }
 }

package/src/plugins/builtin/exposure/pane.tsx

@@ -20,7 +20,7 @@ import { ExposurePathDiagram, ExposureRanges } from "./charts";
 import { fetchExposure, fetchScenarios, validateExposure } from "./client";
 import { ExposureEditor, type ExposureInputs } from "./editor";
 import { portfolioHoldings, watchlistHoldings } from "./holdings";
-import { basisLabel, DEFAULT_SCENARIO, exposureCellText, fraction, parseCustomScenario, parseHoldings, pathRows, portfolioRows, rangeText, tableRows, TABS, type ExposureRow } from "./model";
+import { basisLabel, DEFAULT_SCENARIO, exposureCellText, fraction, hopsText, parseCustomScenario, parseHoldings, pathRows, periodText, portfolioRows, rangeText, tableRows, TABS, type ExposureRow } from "./model";
 import { useExposureEvidence } from "./evidence";
 import { driverRows, driverScope, driverUnits, driverValue } from "./drivers";
 
@@ -29,7 +29,7 @@ function EvidenceItem({ item }: { item: ExposureEvidence }) {
   const host = useRendererHost();
   return <Box flexDirection="column" paddingY={1}>
     <KeyValueRow labelWidth={20} label="Evidence" value={`${item.tier} · ${item.asOf ?? "undated"}`} detail={item.confidence === null ? undefined : `${Math.round(item.confidence * 100)}% confidence`} />
-    <KeyValueRow labelWidth={20} label="Period / units" value={`${item.period ?? "unknown"} · ${item.units}${item.currency ? ` ${item.currency}` : ""}`} />
+    <KeyValueRow labelWidth={20} label="Period / units" value={`${item.period ? periodText(item.period) : "unknown"} · ${item.units}${item.currency ? ` ${item.currency}` : ""}`} />
     {item.revision ? <KeyValueRow labelWidth={20} label="Revision" value={item.revision} /> : null}
     {item.quote ? <Text fg={colors.textBright}>{item.quote}</Text> : <Text fg={colors.textDim}>{item.tier === "user" ? "User-supplied assumption" : "Structured observation; no verbatim quote"}</Text>}
     {item.url ? <ActionRow label="Open primary evidence" onPress={() => void host.openExternal(item.url!)} /> : null}
@@ -49,7 +49,7 @@ function ExposureDetail({ row, data, width }: { row: ExposureRow | null; data: E
       {Object.entries(row.driver.dimensions ?? {}).map(([key, value]) => <KeyValueRow key={key} labelWidth={20} label={humanLabel(key)} value={value} />)}
       {row.driver.evidence.map(item => <EvidenceItem key={item.id} item={item} />)}
     </> : row ? <>
-      <KeyValueRow labelWidth={20} label="Basis / period" value={`${basisLabel(row.basis)} · ${row.period ?? "unknown"}`} />
+      <KeyValueRow labelWidth={20} label="Basis / period" value={`${basisLabel(row.basis)} · ${row.period ? periodText(row.period) : "unknown"}`} />
       <KeyValueRow labelWidth={20} label={row.concentration ? "Gross exposure" : "Exposure"} value={rangeText(row.exposure)} detail={`${row.classification}${row.incomplete ? " · incomplete bound" : ""}`} />
       <KeyValueRow labelWidth={20} label={row.concentration ? "Signed exposure" : "Operating stress"} value={rangeText(row.impact)} detail={row.concentration ? "NAV-weighted operating exposure; not a scenario change" : "Estimated change in the stated denominator"} />
       {row.components.map(component => <Box key={component.id} flexDirection="column" paddingY={1}>
@@ -249,7 +249,7 @@ export function ExposurePane({ width, height, focused }: PaneProps) {
   const query = <QueryBar width={width} filters={[
     { id: "scenario", label: "Scenario", value: scenarioId, options: [...(library.data ?? [DEFAULT_SCENARIO]).map(s => ({ value: s.id ?? (snapshot ? "captured" : "custom"), label: s.label })), { value: "custom", label: "Custom" }].filter((s, i, all) => all.findIndex(v => v.value === s.value) === i), onChange: (value: string) => { if (value === "custom") setEditing(true); else setScenarioId(value); } },
     ...(tab === "portfolio" ? [{ id: "group", label: "View", value: view, options: [{ value: "stress", label: "Stress" }, { value: "country", label: "Country" }, { value: "supplier", label: "Supplier" }, { value: "customer", label: "Customer" }], onChange: setView }] : []),
-  ]} meta={tab === "drivers" ? "Company disclosures" : tab === "portfolio" ? "NAV-weighted operating exposure" : `${data?.depth ?? inputs.depth} hops`} />;
+  ]} meta={tab === "drivers" ? "Company disclosures" : tab === "portfolio" ? "NAV-weighted operating exposure" : hopsText(data?.depth ?? inputs.depth)} />;
   if (!data && isCloudSessionRequired(resource.error) && !editing) return <SignInWall placement="exposure-signin" action="analyze exposures" needsVerification={session.needsVerification} />;
   return <Box width={width} height={height} flexDirection="column">
     {strip}

package/src/plugins/builtin/fixed-income/pane.tsx

@@ -51,7 +51,8 @@ const SECTION_VIEWS: Record<FixedIncomeSection, { defaultView: string; views: Vi
     defaultView: "documents",
     views: [
       { value: "documents", label: "Documents", paneType: "credit-documents", component: ResearchCreditDocumentsPane },
-      { value: "maturities", label: "Maturities", paneType: "debt-maturities", component: ResearchDebtMaturitiesPane },
+      // CRDOC's own Maturities tab is the contractual calendar-year wall; this is the filed fiscal-bucket schedule.
+      { value: "maturities", label: "Debt Schedule", paneType: "debt-maturities", component: ResearchDebtMaturitiesPane },
     ],
   },
   bonds: {

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

@@ -274,6 +274,7 @@ export function FuturesPane({ focused, width, height }: PaneProps) {
     noQuotes,
     status.latestTs,
     status.loading,
+    status.savedAt,
     status.stale,
     status.unavailable,
   ]);

package/src/plugins/builtin/futures/model.ts

@@ -5,6 +5,7 @@ import type { BoardQuoteMap } from "../shared/use-quote-board";
 import { FUTURES_SECTOR_ORDER, type FuturesContract, type FuturesSector } from "../../../market-data/futures-board";
 import { futuresPriceUnit } from "../../../market-data/futures-contract";
 import { contractMonthLabel } from "../../../utils/contract-month";
+import { quoteDotMarketState } from "../../../market-data/market/status";
 import type { FuturesReturnHorizon } from "./returns";
 import type { FuturesTermsMap } from "./use-board-terms";
 import type { FrontReturnsMap } from "./use-front-returns";
@@ -169,7 +170,7 @@ function getSortValue(
     case "unit":
       return futuresUnitLabel(contract, terms?.get(contract.symbol)?.terms);
     case "status":
-      return quote?.marketState === "REGULAR" ? 0 : 1;
+      return quoteDotMarketState(quote) === "REGULAR" ? 0 : 1;
     case "code":
       return contract.code;
     case "name":

package/src/plugins/builtin/futures/table.tsx

@@ -1,5 +1,5 @@
 import type { DataTableCell, DataTableColumn } from "../../../components";
-import { colors, priceColor } from "../../../theme/colors";
+import { colors, shownPriceColor } from "../../../theme/colors";
 import type { Quote } from "../../../types/financials";
 import { TextAttributes } from "../../../ui";
 import { formatCompact, formatNumber, formatPercentRaw } from "../../../utils/format";
@@ -253,7 +253,7 @@ export function renderFuturesCell(
       if (isBoardRowLoading(state) || returns?.loading) return { text: "…", color: colors.textDim };
       const value = returns?.values[FUTURES_RETURN_COLUMNS[column.id]!];
       if (value == null || !Number.isFinite(value)) return { text: "—", color: colors.textDim };
-      return { text: formatPercentRaw(value), color: priceColor(value) };
+      return { text: formatPercentRaw(value), color: shownPriceColor(value, 2) };
     }
     case "prevClose":
       if (isBoardRowLoading(state)) return { text: "…", color: colors.textDim };

package/src/plugins/builtin/futures/use-board-terms.ts

@@ -1,12 +1,15 @@
 import { useEffect, useMemo, useState } from "react";
+import { ApiRequestError } from "../../../api-client/errors";
 import type { FuturesContractTermsPayload } from "../../../api-client/futures-curve";
 import type { FuturesContract } from "../../../market-data/futures-board";
+import { createTtlCache } from "../../../data/ttl-cache";
 import { loadFuturesContractTerms } from "../../../market-data/futures-contract";
+import { logFailure } from "../../../utils/log-failure";
 
 interface FuturesTermsState {
   /** The row's terms are still being asked for. */
   loading: boolean;
-  /** Null when the server has no terms for the symbol, or could not answer. */
+  /** Null while they are being asked for, when the server has none for the symbol, or when the read failed. */
   terms: FuturesContractTermsPayload | null;
 }
 
@@ -14,32 +17,35 @@ export type FuturesTermsMap = ReadonlyMap<string, FuturesTermsState>;
 
 /** The terms change with a roll, and a roll is decided once a day. */
 const TERMS_TTL_MS = 30 * 60_000;
+/**
+ * A read that failed is asked again after this: one blip leaves a row without
+ * its terms for a minute, not for the TTL, and a service that is down is asked
+ * once a minute, not once a tick.
+ */
+const TERMS_RETRY_MS = 60_000;
 /** Forty-odd rows open at once; a few requests at a time keep the board's quotes first. */
 const TERMS_CONCURRENCY = 4;
 
-interface CachedTerms {
-  at: number;
-  /** Null when the server has no terms for the symbol, or could not answer. */
-  terms: FuturesContractTermsPayload | null;
-}
-
-const termsCache = new Map<string, CachedTerms>();
-const inFlight = new Map<string, Promise<void>>();
+/**
+ * Null when the server has no terms for the symbol, which is an answer and is
+ * kept like any other. A read that fails is not kept as one: it rejects, and
+ * the cache holds the rejection for `TERMS_RETRY_MS`.
+ */
+const termsCache = createTtlCache<FuturesContractTermsPayload | null>({ ttlMs: TERMS_TTL_MS, rejectionMs: TERMS_RETRY_MS });
 
-function fresh(symbol: string, now: number): CachedTerms | undefined {
-  const cached = termsCache.get(symbol);
-  return cached && now - cached.at < TERMS_TTL_MS ? cached : undefined;
+async function readTerms(symbol: string): Promise<FuturesContractTermsPayload | null> {
+  try {
+    return await loadFuturesContractTerms(symbol);
+  } catch (error) {
+    if (error instanceof ApiRequestError && error.status === 404) return null;
+    throw error;
+  }
 }
 
-function loadTerms(symbol: string): Promise<void> {
-  const pending = inFlight.get(symbol);
-  if (pending) return pending;
-  const request = loadFuturesContractTerms(symbol)
-    .then((terms) => { termsCache.set(symbol, { at: Date.now(), terms }); })
-    .catch(() => { termsCache.set(symbol, { at: Date.now(), terms: null }); })
-    .finally(() => { inFlight.delete(symbol); });
-  inFlight.set(symbol, request);
-  return request;
+/** Whether the row has an answer; false when the read failed. */
+function loadTerms(symbol: string): Promise<boolean> {
+  return termsCache.load(symbol, () => readTerms(symbol))
+    .then(() => true, logFailure("futures", "Read a futures row's contract terms failed", false));
 }
 
 /**
@@ -51,32 +57,40 @@ function loadTerms(symbol: string): Promise<void> {
 export function useFuturesBoardTerms(contracts: readonly FuturesContract[], enabled: boolean): FuturesTermsMap {
   const symbolKey = contracts.map((contract) => contract.symbol).join(",");
   const [version, setVersion] = useState(0);
+  // Bumped once the retry delay has passed after a failed read, to ask again.
+  const [retry, setRetry] = useState(0);
 
   useEffect(() => {
     if (!enabled || !symbolKey) return;
-    const now = Date.now();
-    const queue = symbolKey.split(",").filter((symbol) => !fresh(symbol, now));
+    const queue = symbolKey.split(",").filter((symbol) => termsCache.peek(symbol) === undefined);
     if (queue.length === 0) return;
     let cancelled = false;
+    let failed = false;
+    let retryTimer: ReturnType<typeof setTimeout> | undefined;
     const worker = async () => {
       for (let symbol = queue.shift(); symbol; symbol = queue.shift()) {
-        await loadTerms(symbol);
+        if (!await loadTerms(symbol)) failed = true;
         if (!cancelled) setVersion((current) => current + 1);
       }
     };
-    void Promise.all(Array.from({ length: Math.min(TERMS_CONCURRENCY, queue.length) }, worker));
+    void Promise.all(Array.from({ length: Math.min(TERMS_CONCURRENCY, queue.length) }, worker)).then(() => {
+      if (failed && !cancelled) retryTimer = setTimeout(() => setRetry((current) => current + 1), TERMS_RETRY_MS);
+    });
     return () => {
       cancelled = true;
       queue.length = 0;
+      clearTimeout(retryTimer);
     };
-  }, [enabled, symbolKey]);
+  }, [enabled, symbolKey, retry]);
 
   return useMemo(() => {
     const result = new Map<string, FuturesTermsState>();
     if (!enabled) return result;
     for (const symbol of symbolKey ? symbolKey.split(",") : []) {
-      const cached = termsCache.get(symbol);
-      result.set(symbol, { loading: !cached, terms: cached?.terms ?? null });
+      // A row keeps the terms it had past their TTL until the next load lands, and
+      // one whose read failed draws without them rather than waiting on a retry.
+      const terms = termsCache.peek(symbol, { stale: true });
+      result.set(symbol, { loading: terms === undefined && !termsCache.failed(symbol), terms: terms ?? null });
     }
     return result;
     // `version` re-reads the cache as loads land.

package/src/plugins/builtin/futures/use-front-returns.ts

@@ -1,6 +1,9 @@
 import { useEffect, useMemo, useState } from "react";
+import { createTtlCache } from "../../../data/ttl-cache";
 import type { DataProvider } from "../../../types/data-provider";
+import { isNoSourceAnswer } from "../../../sources/provider-errors";
 import type { PricePoint } from "../../../types/financials";
+import { logFailure } from "../../../utils/log-failure";
 import type { BoardQuoteMap } from "../shared/use-quote-board";
 import type { FuturesContract } from "../../../market-data/futures-board";
 import {
@@ -24,32 +27,33 @@ export type FrontReturnsMap = ReadonlyMap<string, FrontReturnsState>;
  * for half an hour; the live quote moves the returns in between.
  */
 const HISTORY_TTL_MS = 30 * 60_000;
+/**
+ * A read that failed is asked again after this: one blip leaves a row without
+ * returns for a minute, not for the TTL, and a service that is down is asked
+ * once a minute, not once a tick.
+ */
+const HISTORY_RETRY_MS = 60_000;
 /** Forty-odd contracts open at once; a few requests at a time keep the board's quotes first. */
 const HISTORY_CONCURRENCY = 4;
 
-interface CachedHistory {
-  at: number;
-  /** Null when the contract has no history to read (delisted, unknown). */
-  points: readonly PricePoint[] | null;
-}
-
-const historyCache = new Map<string, CachedHistory>();
-const inFlight = new Map<string, Promise<void>>();
+/**
+ * Null when the source has no history for the contract (delisted, unknown),
+ * which is an answer and is kept like any other. A read that fails is not kept
+ * as one: it rejects, and the cache holds the rejection for `HISTORY_RETRY_MS`.
+ */
+const historyCache = createTtlCache<readonly PricePoint[] | null>({ ttlMs: HISTORY_TTL_MS, rejectionMs: HISTORY_RETRY_MS });
 
-function freshHistory(symbol: string, now: number): CachedHistory | undefined {
-  const cached = historyCache.get(symbol);
-  return cached && now - cached.at < HISTORY_TTL_MS ? cached : undefined;
+function readHistory(provider: DataProvider, symbol: string): Promise<readonly PricePoint[] | null> {
+  return provider.getPriceHistory(symbol, "", "1Y").then((points) => points.length > 0 ? points : null, (error: unknown) => {
+    if (isNoSourceAnswer(error)) return null;
+    throw error;
+  });
 }
 
-function loadHistory(provider: DataProvider, symbol: string): Promise<void> {
-  const pending = inFlight.get(symbol);
-  if (pending) return pending;
-  const request = provider.getPriceHistory(symbol, "", "1Y")
-    .then((points) => { historyCache.set(symbol, { at: Date.now(), points: points.length > 0 ? points : null }); })
-    .catch(() => { historyCache.set(symbol, { at: Date.now(), points: null }); })
-    .finally(() => { inFlight.delete(symbol); });
-  inFlight.set(symbol, request);
-  return request;
+/** Whether the contract has an answer; false when the read failed. */
+function loadHistory(provider: DataProvider, symbol: string): Promise<boolean> {
+  return historyCache.load(symbol, () => readHistory(provider, symbol))
+    .then(() => true, logFailure("futures", "Read a futures contract's history failed", false));
 }
 
 /**
@@ -73,27 +77,33 @@ export function useFrontContractReturns(
     return [symbol, list ? list.split(",") : []] as const;
   })), [candidateKey]);
   const [version, setVersion] = useState(0);
+  // Bumped once the retry delay has passed after a failed read, to ask again.
+  const [retry, setRetry] = useState(0);
   // A board left open overnight reloads once the day turns.
   const today = new Date().toISOString().slice(0, 10);
 
   useEffect(() => {
     if (!enabled || !provider) return;
-    const now = Date.now();
-    const queue = [...new Set([...candidates.values()].flat())].filter((symbol) => !freshHistory(symbol, now));
+    const queue = [...new Set([...candidates.values()].flat())].filter((symbol) => historyCache.peek(symbol) === undefined);
     if (queue.length === 0) return;
     let cancelled = false;
+    let failed = false;
+    let retryTimer: ReturnType<typeof setTimeout> | undefined;
     const worker = async () => {
       for (let symbol = queue.shift(); symbol; symbol = queue.shift()) {
-        await loadHistory(provider, symbol);
+        if (!await loadHistory(provider, symbol)) failed = true;
         if (!cancelled) setVersion((current) => current + 1);
       }
     };
-    void Promise.all(Array.from({ length: Math.min(HISTORY_CONCURRENCY, queue.length) }, worker));
+    void Promise.all(Array.from({ length: Math.min(HISTORY_CONCURRENCY, queue.length) }, worker)).then(() => {
+      if (failed && !cancelled) retryTimer = setTimeout(() => setRetry((current) => current + 1), HISTORY_RETRY_MS);
+    });
     return () => {
       cancelled = true;
       queue.length = 0;
+      clearTimeout(retryTimer);
     };
-  }, [candidates, enabled, provider, today]);
+  }, [candidates, enabled, provider, today, retry]);
 
   return useMemo(() => {
     const result = new Map<string, FrontReturnsState>();
@@ -101,12 +111,14 @@ export function useFrontContractReturns(
     for (const contract of contracts) {
       const quote = quotes.get(contract.symbol)?.quote;
       const symbols = candidates.get(contract.symbol) ?? [];
-      const loaded = symbols.map((symbol) => ({ symbol, cached: historyCache.get(symbol) }));
-      if (loaded.some((entry) => !entry.cached)) {
+      // A contract keeps the history it had past its TTL until the next load lands,
+      // and one whose read failed counts as having none rather than waiting on a retry.
+      const loaded = symbols.map((symbol) => ({ symbol, history: historyCache.peek(symbol, { stale: true }), failed: historyCache.failed(symbol) }));
+      if (loaded.some((entry) => entry.history === undefined && !entry.failed)) {
         result.set(contract.symbol, { loading: true, values: NO_FUTURES_RETURNS });
         continue;
       }
-      const available = loaded.flatMap((entry) => entry.cached?.points ? [{ symbol: entry.symbol, history: entry.cached.points }] : []);
+      const available = loaded.flatMap((entry) => entry.history ? [{ symbol: entry.symbol, history: entry.history }] : []);
       const front = pickFrontContract(available, quote?.price);
       const history = available.find((entry) => entry.symbol === front)?.history;
       result.set(contract.symbol, {
@@ -118,3 +130,8 @@ export function useFrontContractReturns(
     // `version` re-reads the history cache as loads land.
   }, [candidates, contracts, enabled, quotes, version]);
 }
+
+/** Forgets every cached contract's history (tests). */
+export function resetFrontContractReturns(): void {
+  historyCache.clear();
+}