gloomberb 0.19.1 → 0.19.2

package/src/plugins/builtin/ticker-detail/financials/ratios.ts

@@ -4,6 +4,7 @@ import { formatNumber, pickUnit } from "../../../../utils/format";
 import { pricePointIntegrity } from "../../../../utils/price-history-integrity";
 import { formatPerShareNumber } from "../../../../utils/reported-money";
 import { hasStatementGap } from "../../../../utils/statement-gaps";
+import { debtAndLeases, leaseBasis, type LeaseBasis } from "../../../../utils/lease-liabilities";
 import { cashAndShortTermInvestments, excludesCashRunway, formatRunwayMonths, SHORT_RUNWAY_HISTORY, monthlyOperatingBurn, QUARTER_MONTHS, reportsShortTermTotal, runwayMonths, YEAR_MONTHS } from "../../../../utils/cash-runway";
 import {
   buildPreviousStatementMap,
@@ -58,6 +59,8 @@ export interface RatioPeriod {
   price: RatioAmount;
   /** The filer reports cash and short-term investments as a total in some period on file (utils/cash-runway). */
   shortTermTotalOnFile?: boolean;
+  /** How net debt treats the lease liabilities the listing's balance sheets report; absent when none do. */
+  leaseBasis?: LeaseBasis;
 }
 
 interface RatioInputDef {
@@ -75,6 +78,13 @@ interface RatioInputDef {
   trailing?: boolean;
   /** A shorter name for quarterly columns, so the label, TTM and its unit fit the label column. */
   trailingLabel?: string;
+  /** Debt net of cash: where the listing reports lease liabilities, a row naming them follows it (withLeaseRow). */
+  netDebt?: boolean;
+  /**
+   * Not an operand: a line the input before it includes or leaves out, shown under it. Neither its value nor
+   * its gap enters the ratio.
+   */
+  memo?: boolean;
   value: (period: RatioPeriod) => RatioAmount;
 }
 
@@ -245,12 +255,41 @@ function marketCap(period: RatioPeriod): RatioAmount {
   return period.price * shares;
 }
 
+/**
+ * Total debt less cash and short-term investments, with the balance sheet's lease liabilities where the listing's
+ * are included (utils/lease-liabilities). A balance sheet without its lease line then has no net debt.
+ */
+function netDebt({ statement, leaseBasis: basis }: RatioPeriod): RatioAmount {
+  const cash = cashAndShortTerm(statement);
+  if (basis === "included") {
+    const lines = debtAndLeases(statement);
+    return lines === undefined || cash === undefined ? "not-reported" : lines.totalDebt + lines.leases - cash;
+  }
+  const debt = finite(statement.totalDebt);
+  return debt === undefined || cash === undefined ? "not-reported" : debt - cash;
+}
+
 function enterpriseValue(period: RatioPeriod): RatioAmount {
-  const debt = finite(period.statement.totalDebt);
-  const cash = cashAndShortTerm(period.statement);
-  if (debt === undefined || cash === undefined) return "not-reported";
+  const debt = netDebt(period);
+  if (isGap(debt)) return debt;
   const cap = marketCap(period);
-  return isGap(cap) ? cap : cap + debt - cash;
+  return isGap(cap) ? cap : cap + debt;
+}
+
+/** The lease liabilities net debt includes, or a US GAAP filer's operating leases it leaves out. */
+const LEASE_ROW_LABEL: Record<LeaseBasis, string> = { included: "incl. leases", excluded: "excl. op. leases" };
+
+/** The ratio with a row naming the listing's lease liabilities under its net debt, when it reports any. */
+function withLeaseRow(def: RatioDef, basis: LeaseBasis | undefined): RatioDef {
+  const at = def.inputs.findIndex((input) => input.netDebt);
+  if (!basis || at < 0) return def;
+  const row: RatioInputDef = {
+    label: LEASE_ROW_LABEL[basis],
+    format: "money",
+    memo: true,
+    value: ({ statement }) => reported(finite(statement.capitalLeaseObligations)),
+  };
+  return { ...def, inputs: [...def.inputs.slice(0, at + 1), row, ...def.inputs.slice(at + 1)] };
 }
 
 const DSO: RatioDef = {
@@ -378,15 +417,7 @@ export const RATIO_TABS: RatioTabDef[] = [
         label: "Net Debt / EBITDA",
         format: "multiple",
         inputs: [
-          {
-            label: "Net Debt",
-            format: "money",
-            value: ({ statement }) => {
-              const debt = finite(statement.totalDebt);
-              const cash = cashAndShortTerm(statement);
-              return debt === undefined || cash === undefined ? "not-reported" : debt - cash;
-            },
-          },
+          { label: "Net Debt", format: "money", netDebt: true, value: netDebt },
           trailingFlow("EBITDA", line("ebitda"), "÷"),
         ],
         compute: ([debt, ebitda]) => over(debt!, ebitda!),
@@ -517,7 +548,7 @@ export const RATIO_TABS: RatioTabDef[] = [
         label: "EV / EBITDA",
         format: "multiple",
         inputs: [
-          { label: "Enterprise Value", format: "money", value: enterpriseValue },
+          { label: "Enterprise Value", format: "money", netDebt: true, value: enterpriseValue },
           trailingFlow("EBITDA", line("ebitda"), "÷"),
         ],
         // A negative enterprise value makes the multiple meaningless too.
@@ -568,10 +599,11 @@ function inputAmount(input: RatioInputDef, period: RatioPeriod): RatioAmount {
 
 export function evaluateRatio(def: RatioDef, period: RatioPeriod): RatioCell {
   const inputs = def.inputs.map((input) => inputAmount(input, period));
-  const gap = GAP_ORDER.find((candidate) => inputs.includes(candidate));
+  const operands = inputs.filter((_, index) => !def.inputs[index]!.memo);
+  const gap = GAP_ORDER.find((candidate) => operands.includes(candidate));
   if (gap) return { value: gap, inputs };
-  const values = inputs.map((amount, index) => (
-    def.inputs[index]!.annualized && period.quarterly ? (amount as number) * QUARTERS_PER_YEAR : amount as number
+  const values = def.inputs.flatMap((input, index) => (
+    input.memo ? [] : [input.annualized && period.quarterly ? (inputs[index] as number) * QUARTERS_PER_YEAR : inputs[index] as number]
   ));
   const value = def.compute(values, period);
   return { value: isGap(value) || Number.isFinite(value) ? value : "not-meaningful", inputs };
@@ -702,6 +734,7 @@ export function ratioPeriods(
   onFile: { annual: readonly FinancialStatement[]; quarterly: readonly FinancialStatement[] } = { annual: [], quarterly: [] },
 ): RatioPeriod[] {
   const shortTermTotalOnFile = reportsShortTermTotal([...onFile.annual, ...onFile.quarterly, ...statements]);
+  const leases = leaseBasis([...onFile.annual, ...onFile.quarterly, ...statements]);
   return statements.map((statement) => {
     const quarterly = period === "quarterly" && statement.date !== "TTM";
     return {
@@ -711,6 +744,7 @@ export function ratioPeriods(
       ...(quarterly ? { trailing: trailingYear(statement, onFile.annual, onFile.quarterly) } : {}),
       price: price(statement),
       shortTermTotalOnFile,
+      ...(leases ? { leaseBasis: leases } : {}),
     };
   });
 }
@@ -758,11 +792,12 @@ export function buildRatioTableModel(
 ): RatioTableModel {
   const quarterly = periods.some((period) => period.quarterly);
   const totalOnFile = periods.some((period) => period.shortTermTotalOnFile);
+  const leases = periods.find((period) => period.leaseBasis)?.leaseBasis;
   const ratios = visibleRatios(tab, quarterly)
     .filter((def) => def.format !== "months" || !excludesCashRunway(profile))
     .map((def) => def.format === "months" && !totalOnFile
       ? { ...def, inputs: def.inputs.map((input, index) => index === 0 ? { ...input, label: "Cash" } : input) }
-      : def);
+      : withLeaseRow(def, leases));
   const cells = new Map(ratios.map((def) => [def.id, periods.map((period) => evaluateRatio(def, period))]));
   const inputs = ratios.flatMap((def) => def.inputs.map((input, index) => {
     const values = cells.get(def.id)!.map((cell) => cell.inputs[index]).filter((value) => typeof value === "number");

package/src/plugins/builtin/ticker-detail/headless.ts

@@ -1,4 +1,7 @@
-import { FINANCIAL_VINTAGE_NOTICE, filledPeriodsNote, stalePeriodNote, statementHistoryNotes } from "../../../utils/financial-statements";
+import {
+  FINANCIAL_VINTAGE_NOTICE, filledPeriodsNote, hasOlderStatements, reportsHalfYearly, stalePeriodNote, statementHistoryNotes,
+} from "../../../utils/financial-statements";
+import { canonicalExchange } from "../../../utils/exchanges";
 import { hasValidQuoteObservationTime } from "../../../market-data/quotes/freshness";
 import { EXTENDED_SESSION_LABELS, getQuoteSessionFields, quoteHeadlineTime, type ExtendedSession } from "../../../market-data/market/status";
 import type { HeadlessPaneColumn, HeadlessPaneDefinition, HeadlessPaneFreshness, HeadlessPaneOptionValues } from "../../../types/headless";
@@ -6,7 +9,8 @@ import type { TimeRange } from "../../../time-series/range";
 import { formatNumber, formatPercentRaw } from "../../../utils/format";
 import { formatMarketPrice, formatMarketPriceWithCurrency, formatPriceObservation, penceFigure, quoteFormatOptions, withCurrencyMinorDigits, type MarketFormatOptions } from "../../../market-data/market/format";
 import {
-  MISSING_VOLUME_TEXT, missingVolumeCount, missingVolumeNotice, pricePointValues, priceHistoryIntegrityNotice,
+  MISSING_VOLUME_TEXT, missingVolumeCount, missingVolumeNotice, pricePointValues, pricePointWickFlags, priceHistoryIntegrityNotice,
+  priceHistoryWickNotice,
 } from "../../../utils/price-history-integrity";
 import {
   buildFinancialTableModel, financialStatementCurrency, financialStatementDateNotice, financialStatementLimitations,
@@ -151,18 +155,23 @@ export const financialStatementsHeadless: HeadlessPaneDefinition<"rows"> = {
     const stale = table ? stalePeriodNote(financialStatementPeriods(table.statements, table.subTab)) : null;
     // Years filled from the listing's exchange, with the lines this table shows.
     const filled = table ? filledPeriodsNote(table.statements, financialSubTabFields(table.subTab)) : null;
+    const periodDates = dates.map(({ date }) => date);
+    const missing = rows.length ? null : await missingPeriodsError(ctx, symbol, financials, requestedPeriod, hasRequestedStatements, options.statement);
     return {
       rows, columns, unavailableSymbols: rows.length ? [] : [symbol],
-      ...(!hasRequestedStatements ? { errors: [`${symbol}: No ${requestedPeriod} financial statement coverage.`] } : {}),
+      ...(missing ? { errors: [missing] } : {}),
       // The report closes with how old its latest period is, how far back its periods go, and how to read further.
-      notes: [...stale ? [stale] : [], ...filled ? [filled] : [], ...offering ? [offering] : [], ...statementHistoryNotes(requestedPeriod, dates.map(({ date }) => date), symbol)],
+      notes: [...stale ? [stale] : [], ...filled ? [filled] : [], ...offering ? [offering] : [],
+        ...statementHistoryNotes(requestedPeriod, periodDates, symbol, await reportOlderStatements(ctx, symbol, requestedPeriod, periodDates))],
       metadata: {
         symbol, name: financials.quote?.name ?? symbol, currency: statementCurrency ?? null, unit: table?.unit ?? null, quoteCurrency: financials.quote?.currency ?? null,
         statement: table?.subTab.key ?? options.statement, statementLabel: table?.subTab.name ?? null,
         period: requestedPeriod, growthBasis: requestedPeriod === "quarterly" ? "QoQ" : "YoY", columns: dates,
         shareBasis: shareBases.size === 1 ? [...shareBases][0] ?? null : null,
         ...(receiptPeriods.length > 0 ? { adrRatio: financials.fundamentals?.adrRatio ?? financials.quote?.adrRatio ?? null } : {}),
-        notices: rows.length ? [FINANCIAL_VINTAGE_NOTICE, ...(shareBasisNotice ? [shareBasisNotice] : [])] : [],
+        // A quarter's change is against the quarter before it, which a reader of a table of quarters must be told.
+        notices: rows.length ? [FINANCIAL_VINTAGE_NOTICE, ...requestedPeriod === "quarterly" ? [QUARTERLY_GROWTH_NOTICE] : [],
+          ...(shareBasisNotice ? [shareBasisNotice] : [])] : [],
         limitations: financialStatementLimitations(financials),
         dateProvenance: financialStatementDateNotice(table?.statements ?? []),
       },
@@ -172,6 +181,44 @@ export const financialStatementsHeadless: HeadlessPaneDefinition<"rows"> = {
 
 const reportAmount = (amount: RatioAmount) => (typeof amount === "number" ? amount : null);
 
+/** What a table of quarters says its growth is measured against. */
+const QUARTERLY_GROWTH_NOTICE = "Growth is vs prior quarter.";
+
+type HeadlessContext = Parameters<typeof financialStatementsHeadless.load>[1];
+
+/** Whether GF, reading the listing's extended statement history, goes back further than the report (statementHistoryNotes). */
+function reportOlderStatements(ctx: HeadlessContext, symbol: string, period: "annual" | "quarterly", dates: readonly string[]) {
+  return hasOlderStatements(async () => {
+    const { symbol: bare, exchange } = await resolveHeadlessInstrument(ctx, symbol);
+    return ctx.marketData.getTickerFinancials(bare, exchange ?? "", { statementHistory: "extended" });
+  }, period, dates);
+}
+
+/**
+ * Why a statements report has no rows, and what to read instead: a listing
+ * with years but no quarters names its years, and says so of a company that
+ * reports half-yearly (Qantas on ASX). Null when it has years and quarters,
+ * whatever this table lacks.
+ */
+async function missingPeriodsError(
+  ctx: HeadlessContext,
+  symbol: string,
+  financials: Awaited<ReturnType<typeof loadHeadlessFinancials>>,
+  period: "annual" | "quarterly",
+  hasRequestedStatements: boolean,
+  statement: unknown,
+): Promise<string | null> {
+  const hasYears = financials.annualStatements.length > 0;
+  if (period === "annual" || !hasYears) return hasRequestedStatements ? null : `${symbol}: No ${period} financial statement coverage.`;
+  const exchange = await resolveHeadlessInstrument(ctx, symbol).then(({ exchange }) => canonicalExchange(exchange ?? ""))
+    .catch(logFailure("ticker-detail.headless", "Resolving the listing of a statements report failed", ""));
+  const halfYearly = reportsHalfYearly(exchange, financials.quarterlyStatements);
+  if (hasRequestedStatements && !halfYearly) return null;
+  const tab = typeof statement === "string" && statement && statement !== "income" ? ` --statement ${statement}` : "";
+  const years = `For its years: gloom fn FA ${symbol} --period annual${tab}`;
+  return halfYearly ? `${symbol} reports half-yearly, not quarterly. ${years}` : `${symbol}: No quarterly financial statement coverage. ${years}`;
+}
+
 /** The note that an offering filed after the latest balance sheet is not in its cash yet; a failed read leaves it out. */
 async function reportOfferingNote(
   ctx: Parameters<typeof financialStatementsHeadless.load>[1],
@@ -240,16 +287,18 @@ async function loadRatioReport(
   const runwayShown = liquidity && table.ratios.some((def) => def.format === "months"
     && table.cells.get(def.id)!.some((cell) => typeof cell.value === "number"));
   const offering = liquidity ? await reportOfferingNote(ctx, symbol, financials) : null;
+  const periodDates = dates.map(({ date }) => date);
+  const missing = rows.length ? null : await missingPeriodsError(ctx, symbol, financials, period, hasRequestedStatements, tab.key);
   return {
     rows, columns, unavailableSymbols: rows.length ? [] : [symbol],
-    ...(!hasRequestedStatements ? { errors: [`${symbol}: No ${period} financial statement coverage.`] } : {}),
+    ...(missing ? { errors: [missing] } : {}),
     ...(tab.key === "valuation" && hasRequestedStatements && !history?.length ? { complete: false } : {}),
     notes: [
       ...[stalePeriodNote(dates.map(({ periodEnd }) => ({ date: periodEnd, lead: true })))].filter((note): note is string => !!note),
       ...[filledPeriodsNote(table?.periods.map(({ statement }) => statement) ?? [])].filter((note): note is string => !!note),
       ...offering ? [offering] : [],
       ...runwayShown ? [runwayMethod(reportsShortTermTotal([...financials.quarterlyStatements, ...financials.annualStatements]))] : [],
-      ...statementHistoryNotes(period, dates.map(({ date }) => date), symbol),
+      ...statementHistoryNotes(period, periodDates, symbol, await reportOlderStatements(ctx, symbol, period, periodDates)),
     ],
     metadata: {
       symbol, name: financials.quote?.name ?? symbol, currency: statementCurrency ?? null,
@@ -453,7 +502,9 @@ export const historicalPricesHeadless: HeadlessPaneDefinition<"rows"> = {
     const drawdown = maxDrawdown(shown);
     const drawdownLine = drawdown ? maxDrawdownText(drawdown, { basis: `${historyBarSizeWord(size)} closes`, price: (value) => formatBarPrice(value, decimals),
       date: (value) => isDailyOrLongerBar(size) ? value.slice(0, 10) : formatUtcTime(value) }) : null;
-    const reportNotices = [drawdownLine, notice].filter((line): line is string => line != null);
+    // A wick left out of the range is said, though the bar's close still counts.
+    const wickNotice = priceHistoryWickNotice(points.filter((point) => pricePointWickFlags(point).length > 0).length);
+    const reportNotices = [drawdownLine, notice, wickNotice].filter((line): line is string => line != null);
     return {
       rows: shown,
       columns: historyColumns(size, marked, false, false, decimals),

package/src/plugins/builtin/treasury-auctions/cache.ts

@@ -1,4 +1,5 @@
-import { createPluginCache } from "../../../data/plugin-cache";
+import { createPluginCache, savedCopyForTransientFailure } from "../../../data/plugin-cache";
+import { servedFromSavedCopy } from "../../../data/saved-copies";
 import type { ConnectionHealthRegistry } from "../../../core/connection-health";
 import type { PluginPersistence } from "../../../types/plugin";
 import {
@@ -37,6 +38,8 @@ export interface TreasuryAuctionsResult {
   fetchedAt: number;
   /** True when the network failed and expired cache was served instead. */
   stale: boolean;
+  /** The refresh failed and the copy saved at this time (ms) answered instead. */
+  savedAt?: number;
   refreshError?: string;
 }
 
@@ -84,11 +87,18 @@ export async function loadTreasuryAuctions(
   window: AuctionHistoryWindow = AUCTION_HISTORY_DAYS,
 ): Promise<TreasuryAuctionsResult> {
   if (window === AUCTION_HISTORY_ALL) return loadAllTreasuryAuctions(force, loader);
-  const result = await cache.load(`recent:${window}`, walk(loader, () => auctionWindowQuery(window)), { force });
-  return {
+  // A saved board answers only for a failure asking again may get past; a refusal or an invalid page is the error.
+  const result = savedCopyForTransientFailure(await cache.load(`recent:${window}`, walk(loader, () => auctionWindowQuery(window)), { force }));
+  return answered({
     auctions: result.data, fetchedAt: result.fetchedAt, stale: result.stale,
+    ...(result.source === "stale-fallback" ? { savedAt: result.fetchedAt } : {}),
     ...(result.refreshError ? { refreshError: result.refreshError } : {}),
-  };
+  });
+}
+
+/** A board a saved copy answered: marked as one, so a command ends by saying when it was saved, not with its failure. */
+function answered(result: TreasuryAuctionsResult): TreasuryAuctionsResult {
+  return result.savedAt != null ? servedFromSavedCopy(result, result.savedAt) : result;
 }
 
 /**
@@ -100,16 +110,18 @@ export async function loadTreasuryAuctions(
 async function loadAllTreasuryAuctions(force: boolean, loader: AuctionLoader): Promise<TreasuryAuctionsResult> {
   const boundary = auctionArchiveBoundary();
   const [recent, archive] = await Promise.all([
-    cache.load(`since:${boundary}`, walk(loader, () => ({ from: boundary })), { force }),
+    cache.load(`since:${boundary}`, walk(loader, () => ({ from: boundary })), { force }).then(savedCopyForTransientFailure),
     archiveCache.load(`archive:${boundary}`, walk(loader, () => ({
       from: AUCTION_HISTORY_START, before: boundary, pageSize: AUCTION_ARCHIVE_PAGE_SIZE,
-    }))),
+    }))).then(savedCopyForTransientFailure),
   ]);
   const seen = new Set<string>();
   const auctions = [...recent.data, ...archive.data].filter((auction) => !seen.has(auction.id) && Boolean(seen.add(auction.id)));
   const refreshError = recent.refreshError ?? archive.refreshError;
-  return {
+  const savedAt = Math.min(...[recent, archive].map((part) => part.source === "stale-fallback" ? part.fetchedAt : Infinity));
+  return answered({
     auctions, fetchedAt: recent.fetchedAt, stale: recent.stale || archive.stale,
+    ...(Number.isFinite(savedAt) ? { savedAt } : {}),
     ...(refreshError ? { refreshError } : {}),
-  };
+  });
 }

package/src/plugins/builtin/treasury-auctions/client.ts

@@ -1,3 +1,4 @@
+import { ApiRequestError } from "../../../api-client/errors";
 import { createThrottledFetch } from "../../../utils/throttled-fetch";
 import type { TreasuryAuction, TreasuryAuctionRaw } from "./types";
 
@@ -222,9 +223,8 @@ export async function fetchTreasuryAuctions(
 ): Promise<TreasuryAuction[]> {
   return fetchAuctionPages(async (page) => {
     const response = await TREASURY_FETCH.fetch(buildAuctionsUrl(query, page));
-    if (!response.ok) {
-      throw new Error(`Treasury Fiscal Data request failed (${response.status})`);
-    }
+    // The status stays: an overloaded server is a failure a saved board may answer for, a refusal is not.
+    if (!response.ok) throw new ApiRequestError(`Treasury Fiscal Data request failed (${response.status})`, response.status);
     return response.json();
   });
 }

package/src/plugins/builtin/treasury-auctions/headless.ts

@@ -5,6 +5,7 @@ import type {
 import { formatCompact } from "../../../utils/format";
 import { AUCTION_HISTORY_ALL, AUCTION_HISTORY_START, fetchTreasuryAuctions, type AuctionHistoryWindow } from "./client";
 import { loadTreasuryAuctions, type TreasuryAuctionsResult } from "./cache";
+import { unansweredRefreshError } from "../../../data/saved-copies";
 import type { TreasuryAuction } from "./types";
 import { FIXED_INCOME_VIEW_STATE } from "../fixed-income/model";
 import {
@@ -156,7 +157,8 @@ function createTreasuryAuctionsHeadless(
       ];
       return {
         complete: !result.refreshError,
-        errors: result.refreshError ? [result.refreshError] : [],
+        // A saved copy answering the failed refresh ends the report by saying when it was saved instead.
+        errors: [unansweredRefreshError(result)].filter((error): error is string => !!error),
         notes,
         rows: auctions.map((auction) => ({
           ...auction,

package/src/plugins/builtin/treasury-auctions/pane.tsx

@@ -13,6 +13,8 @@ import {
   type DataTableRootKeyContext,
 } from "../../../components";
 import { loadingErrorFooterInfo, usePaneRefreshKey } from "../../../components/data-table/table-pane";
+import { savedCopyFooterInfo } from "../../../components/layout/pane/footer";
+import { STALE_SEGMENT } from "../../../components/layout/pane/status-footer";
 import { usePaneInstance } from "../../../state/app/context";
 import { colors } from "../../../theme/colors";
 import type { PaneProps } from "../../../types/plugin";
@@ -208,8 +210,10 @@ export function TreasuryAuctionsPane({ focused, width, height }: PaneProps) {
   const auctions = resource.data?.auctions ?? NO_AUCTIONS;
   const stale = resource.data?.stale ?? false;
   const fetchedAt = resource.data?.fetchedAt ?? null;
+  // A refresh that failed shows the auctions an earlier read saved, and says when that copy is from.
+  const savedAt = resource.data?.savedAt ?? null;
   // A cache that could not be refreshed arrives as a result, not a failure.
-  const error = resource.error ?? (resource.loading ? null : resource.data?.refreshError ?? null);
+  const error = resource.error ?? (resource.loading || savedAt != null ? null : resource.data?.refreshError ?? null);
   // Once auctions have loaded, a refresh runs without a loading state.
   const loading = resource.loading && !resource.data;
   const [filter, setFilter] = usePluginPaneState<AuctionFilter>("activeTab", "all");
@@ -302,8 +306,9 @@ export function TreasuryAuctionsPane({ focused, width, height }: PaneProps) {
 
   usePaneFooter(TREASURY_AUCTIONS_PANE_ID, () => {
     const info = loadingErrorFooterInfo(loading, error);
-    if (stale) info.push({ id: "stale", parts: [{ text: "stale cache", tone: "warning" }] });
-    if (fetchedAt) {
+    if (savedAt != null) info.push(...savedCopyFooterInfo([savedAt]));
+    else if (stale) info.push(STALE_SEGMENT);
+    if (fetchedAt && savedAt == null) {
       info.push({ id: "updated", parts: [{ text: formatRelativeAge(fetchedAt), tone: "muted" }] });
     }
     return {
@@ -323,6 +328,7 @@ export function TreasuryAuctionsPane({ focused, width, height }: PaneProps) {
     fetchedAt,
     focusSearch,
     loading,
+    savedAt,
     stale,
   ]);
 

package/src/plugins/builtin/volatility/client.ts

@@ -14,6 +14,7 @@ import { buildVolatilityData, buildVolatilityTermHistory, IMPLIED_CORRELATION_RO
   type VolatilitySeriesId, type VolatilitySeriesInput, type VolatilityTermHistory } from "./model";
 import { abortable, abortError } from "../../../utils/async-deadline";
 import { errorMessage } from "../../../utils/errors";
+import { savedCopyAt } from "../../../data/saved-copies";
 
 const VOLATILITY_LOAD_CONCURRENCY = 4;
 const VOLATILITY_HISTORY_LIMIT = 400;
@@ -22,6 +23,8 @@ export interface VolatilityLoadResult {
   /** The daily inputs the data was built from, so live index levels can be laid over them. */
   inputs: VolatilityInputs;
   stale: boolean;
+  /** The oldest copy a failed refresh left answering, by when it was saved (ms); its failure is not in `errors`. */
+  savedAt?: number;
   errors: string[];
   phase: "loading" | "partial" | "ready" | "error";
   loaded: number;
@@ -76,14 +79,16 @@ const legError = (legs: ReadonlyArray<{ error?: string | null } | undefined>) =>
  * The 3M/30D ratio's history as the board builds it: the board's own VIX and
  * VIX 3M daily closes (one year, the same request and cache), FRED's
  * republished closes from `start` on the dates those lack. When Cboe's closes
- * fail FRED stands in, a day behind, and the warning says so; a ratio read
- * from cached closes names whose. With neither publisher's pair it rejects
- * with both reasons rather than return an empty history.
+ * fail FRED stands in, a day behind, and the warning says so. A ratio read
+ * from closes a failed refresh left in place carries when they were saved
+ * (`savedAt`), which the chart dates as every pane does; other cached closes
+ * name whose. With neither publisher's pair it rejects with both reasons
+ * rather than return an empty history.
  */
 export async function loadVolatilityTermHistory(
   { start, signal }: { start?: Date; signal?: AbortSignal } = {},
   dependencies: VolatilityLoaderDependencies & { loadFredPoints?: typeof loadFredPoints } = termDependencies(),
-): Promise<{ term: VolatilityTermHistory; warning?: string }> {
+): Promise<{ term: VolatilityTermHistory; warning?: string; savedAt?: number }> {
   const loadFred = dependencies.loadFredPoints ?? loadFredPoints;
   const now = dependencies.now?.() ?? Date.now();
   const history: NonNullable<VolatilityInputs["history"]> = {};
@@ -101,7 +106,7 @@ export async function loadVolatilityTermHistory(
       try {
         const loaded = await loadFred(seriesId, start);
         fred[seriesId] = { observations: loaded.points, info: null, stale: loaded.points.length > 0 && loaded.stale,
-          error: loaded.refreshError ?? null };
+          error: loaded.refreshError ?? null, ...(loaded.savedAt != null && loaded.points.length ? { savedAt: loaded.savedAt } : {}) };
       } catch (error) {
         fred[seriesId] = { observations: [], info: null, error: errorMessage(error) };
       }
@@ -119,12 +124,14 @@ export async function loadVolatilityTermHistory(
   } else if (fredError && !term.ratioHistory.some((point) => point.publisher === "FRED")) {
     notes.push(`FRED closes unavailable (${fredError}); showing Cboe's from ${term.ratioHistory[0]!.date}.`);
   }
-  if (term.stale) {
+  const legs = term.publisher === "FRED" ? VOLATILITY_SERIES.map(({ seriesId }) => fred[seriesId]) : [history.vix, history.vix3m];
+  const savedAt = term.stale ? oldestSavedAt(legs) : undefined;
+  if (term.stale && savedAt == null) {
     const error = term.publisher === "FRED" ? fredError : cboeError;
     notes.push(error ? `Refresh failed (${error}); showing cached ${term.publisher} closes.`
       : `Showing cached ${term.publisher} closes; the source has not updated since.`);
   }
-  return notes.length ? { term, warning: notes.join(" ") } : { term };
+  return { term, ...(notes.length ? { warning: notes.join(" ") } : {}), ...(savedAt != null ? { savedAt } : {}) };
 }
 
 /** A CBOE daily close as a daily bar dated at the 16:15 New York settlement. */
@@ -141,23 +148,39 @@ function validateFredData(seriesId: VolatilitySeriesId, data: FredSeriesData): F
   }
   return data;
 }
-function fredInput(result: Pick<FredSeriesLoadResult, "data" | "stale" | "fetchedAt"> & { refreshError?: string }): VolatilitySeriesInput {
+function fredInput(result: Pick<FredSeriesLoadResult, "data" | "stale" | "fetchedAt"> & Partial<Pick<FredSeriesLoadResult, "source">>
+  & { refreshError?: string }): VolatilitySeriesInput {
+  const saved = result.source === "stale-fallback" && result.data.observations.length > 0;
   return { observations: result.data.observations, info: result.data.info, fetchedAt: result.fetchedAt,
     stale: result.data.observations.length > 0 && result.stale,
-    error: result.refreshError ?? (result.data.observations.length ? null : "Daily FRED observations unavailable") };
+    error: result.refreshError ?? (result.data.observations.length ? null : "Daily FRED observations unavailable"),
+    ...(saved ? { savedAt: result.fetchedAt } : {}) };
 }
+/**
+ * A history answered from the copy saved before its refetch failed is one only
+ * when the router says so (its saved-copy mark, which a command's answers
+ * carry): closes kept from an earlier answer, or a fresh answer with no data,
+ * say their error instead.
+ */
 function historyInput(entry: QueryEntry<PricePoint[]>, now: number): VolatilityHistoryInput {
   const history = resolveEntryValue(entry) ?? [];
+  const savedAt = history.length > 0 ? savedCopyAt(entry.history) : null;
   return { history, source: entry.source, fetchedAt: entry.fetchedAt,
-    stale: history.length > 0 && (!!entry.error || (entry.staleAt != null && entry.staleAt <= now)),
-    error: entry.error?.message ?? (history.length ? null : "Daily index history unavailable") };
+    stale: history.length > 0 && (savedAt != null || !!entry.error || (entry.staleAt != null && entry.staleAt <= now)),
+    error: entry.error?.message ?? (history.length ? null : "Daily index history unavailable"),
+    ...(savedAt != null ? { savedAt } : {}) };
+}
+/** The oldest of `inputs`' saved copies, by when each was saved. */
+function oldestSavedAt(inputs: ReadonlyArray<{ savedAt?: number | null } | undefined>): number | undefined {
+  const saved = inputs.flatMap((input) => input?.savedAt != null ? [input.savedAt] : []);
+  return saved.length ? Math.min(...saved) : undefined;
 }
 /** Seeds the first paint; the load that replaces each input settles its freshness, so cache age is not stale. */
 function cachedInputs(dependencies: VolatilityLoaderDependencies, now: number): VolatilityInputs {
   const inputs: VolatilityInputs = { history: {}, fred: {} };
   for (const definition of VOLATILITY_INDICES) {
     const entry = dependencies.getChartEntry?.(volatilityHistoryRequest(definition.symbol));
-    if (entry && resolveEntryValue(entry) != null) inputs.history![definition.id] = { ...historyInput(entry, now), stale: false };
+    if (entry && resolveEntryValue(entry) != null) inputs.history![definition.id] = { ...historyInput(entry, now), stale: false, savedAt: null };
   }
   for (const { seriesId } of VOLATILITY_SERIES) {
     const cached = getCachedFredSeries(requestFor(seriesId), { allowExpired: true });
@@ -176,12 +199,16 @@ function historyError(id: string, error: string): string {
 }
 function project(inputs: VolatilityInputs, loaded: number, total: number, pending: boolean): VolatilityLoadResult {
   const data = buildVolatilityData(inputs);
-  const errors = [...Object.entries(inputs.history ?? {}).flatMap(([id, value]) => value.error ? [historyError(id, value.error)] : []),
-    ...Object.entries(inputs.fred ?? {}).flatMap(([id, value]) => value.error ? [`${id}: ${value.error}`] : [])];
-  const stale = [...Object.values(inputs.history ?? {}), ...Object.values(inputs.fred ?? {})].some((value) => value.stale);
+  // A saved copy answering a failed refresh says when it was saved (`savedAt`) instead of the failure.
+  const errors = [...Object.entries(inputs.history ?? {}).flatMap(([id, value]) => value.error && value.savedAt == null ? [historyError(id, value.error)] : []),
+    ...Object.entries(inputs.fred ?? {}).flatMap(([id, value]) => value.error && value.savedAt == null ? [`${id}: ${value.error}`] : [])];
+  const all = [...Object.values(inputs.history ?? {}), ...Object.values(inputs.fred ?? {})];
+  const stale = all.some((value) => value.stale);
+  const savedAt = oldestSavedAt(all);
   const phase = pending ? hasValues(data) ? "partial" : "loading" : !hasValues(data) ? "error"
     : errors.length || stale || data.warnings.length || data.board.some((row) => row.status !== "available") ? "partial" : "ready";
-  return { data, inputs: { history: { ...inputs.history }, fred: { ...inputs.fred } }, stale, errors, phase, loaded, total };
+  return { data, inputs: { history: { ...inputs.history }, fred: { ...inputs.fred } }, stale, ...(savedAt != null ? { savedAt } : {}),
+    errors, phase, loaded, total };
 }
 export function getCachedVolatilityData(dependencies: VolatilityLoaderDependencies = createVolatilityDependencies()): VolatilityLoadResult | null {
   const inputs = cachedInputs(dependencies, dependencies.now?.() ?? Date.now());

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

@@ -2,6 +2,7 @@ import type { HeadlessBundleResult, HeadlessPaneContext, HeadlessPaneDefinition,
 import { createVolatilityDependencies, loadVolatilityData, type VolatilityLoadResult } from "./client";
 import { termStateLabel, type VolatilityData } from "./model";
 import { newestReportTime, oldestReportTime } from "../../../utils/utc-time";
+import { servedFromSavedCopy } from "../../../data/saved-copies";
 
 function formattedValue(value: unknown): string { return typeof value === "number" && Number.isFinite(value) ? value.toFixed(2) : "--"; }
 function formattedPercentile(value: unknown): string { return typeof value === "number" && Number.isFinite(value) ? value.toFixed(0) : "--"; }
@@ -60,6 +61,8 @@ export function createVolatilityHeadless(dependencies: VolatilityHeadlessDepende
     async load(args, context) {
       const result = await dependencies.load(args, context);
       context.signal.throwIfAborted();
+      // A saved copy answering a failed refresh ends the report with when it was saved.
+      const savedCopy = <T>(value: T) => result.savedAt != null ? servedFromSavedCopy(value, result.savedAt) : value;
       // Daily index closes, dated by the newest index on the board; a sparse index shows as the oldest.
       const boardDates = result.data.board.filter((row) => row.value != null).map((row) => row.date);
       const freshness = { source: "Cboe and FRED", status: "not-a-feed" as const, basis: "daily index closes", cadence: "daily" as const,
@@ -67,10 +70,10 @@ export function createVolatilityHeadless(dependencies: VolatilityHeadlessDepende
       return { ...projectVolatilityHeadless(result.data), freshness, errors: result.errors,
         complete: result.phase === "ready" && !result.stale && result.data.warnings.length === 0,
         unavailableSymbols: result.data.board.filter((row) => row.value == null).map((row) => row.symbol),
-        metadata: { stale: result.stale, phase: result.phase, loaded: result.loaded, total: result.total,
+        metadata: savedCopy({ stale: result.stale, phase: result.phase, loaded: result.loaded, total: result.total,
           data: result.data, unit: "index points", observations: "daily history or isolated index observation",
           percentile: "Midrank within last calendar year; at least 200 observations spanning 300 days",
-          vixFuturesAvailable: false, methodology: "docs/research-data.md#vix-curve-and-cross-asset-volatility-board" },
+          vixFuturesAvailable: false, methodology: "docs/research-data.md#vix-curve-and-cross-asset-volatility-board" }),
       };
     },
   };