gloomberb 0.19.1 → 0.19.2

package/src/data/ticker-store.ts

@@ -1,27 +1,47 @@
 import type { Database } from "bun:sqlite";
+import { createSqliteAccess, type SqliteAccess } from "./sqlite/access";
 import { serializeJson } from "./sqlite/json";
-import { withSqliteBusyRetry } from "./sqlite/retry";
 
 export interface StoredTickerRecord {
   symbol: string;
   metadata: string;
 }
 
+/** A queued write's row (null metadata for a delete), one object per write. */
+interface PendingTicker {
+  metadata: string | null;
+}
+
 export class TickerStore {
-  constructor(private readonly db: Database) {}
+  /** Writes queued behind another program's lock, by symbol, read back until they land. */
+  private readonly pending = new Map<string, PendingTicker>();
+
+  constructor(
+    private readonly db: Database,
+    private readonly access: SqliteAccess = createSqliteAccess(db),
+  ) {}
 
   getAll(): StoredTickerRecord[] {
-    return withSqliteBusyRetry("load tickers", () => (
+    const rows = this.access.run("load tickers", () => (
       this.db
         .query<StoredTickerRecord, []>(
           "SELECT symbol, metadata FROM tickers ORDER BY symbol",
         )
         .all()
     ));
+    if (this.pending.size === 0) return rows;
+    const bySymbol = new Map(rows.map((row) => [row.symbol, row]));
+    for (const [symbol, { metadata }] of this.pending) {
+      if (metadata == null) bySymbol.delete(symbol);
+      else bySymbol.set(symbol, { symbol, metadata });
+    }
+    return [...bySymbol.values()].sort((a, b) => (a.symbol < b.symbol ? -1 : a.symbol > b.symbol ? 1 : 0));
   }
 
   get(symbol: string): string | null {
-    const row = withSqliteBusyRetry("load ticker", () => (
+    const pending = this.pending.get(symbol);
+    if (pending) return pending.metadata;
+    const row = this.access.run("load ticker", () => (
       this.db
         .query<{ metadata: string }, [string]>(
           "SELECT metadata FROM tickers WHERE symbol = ?",
@@ -32,34 +52,48 @@ export class TickerStore {
   }
 
   save(symbol: string, metadata: unknown): void {
-    withSqliteBusyRetry("save ticker", () => {
-      this.db
-        .query(
-          `INSERT OR REPLACE INTO tickers (symbol, metadata, updated_at)
-           VALUES (?, ?, ?)`,
-        )
-        .run(symbol, serializeJson(metadata), Date.now());
-    });
+    this.saveMany([{ symbol, metadata }]);
   }
 
   /** Saves every record in one transaction: one write for a whole import, not one per ticker. */
   saveMany(records: ReadonlyArray<{ symbol: string; metadata: unknown }>): void {
     if (records.length === 0) return;
-    withSqliteBusyRetry("save tickers", () => {
-      const statement = this.db.query(
-        `INSERT OR REPLACE INTO tickers (symbol, metadata, updated_at)
-         VALUES (?, ?, ?)`,
-      );
-      const now = Date.now();
-      this.db.transaction(() => {
-        for (const record of records) statement.run(record.symbol, serializeJson(record.metadata), now);
-      })();
-    });
+    const rows = records.map((record) => ({ symbol: record.symbol, metadata: serializeJson(record.metadata) }));
+    const now = Date.now();
+    this.write(
+      rows.length === 1 ? "save ticker" : "save tickers",
+      rows.map((row) => [row.symbol, { metadata: row.metadata }]),
+      () => {
+        const statement = this.db.query(
+          `INSERT OR REPLACE INTO tickers (symbol, metadata, updated_at)
+           VALUES (?, ?, ?)`,
+        );
+        this.db.transaction(() => {
+          for (const row of rows) statement.run(row.symbol, row.metadata, now);
+        })();
+      },
+    );
   }
 
   delete(symbol: string): void {
-    withSqliteBusyRetry("delete ticker", () => {
+    this.write("delete ticker", [[symbol, { metadata: null }]], () => {
       this.db.query("DELETE FROM tickers WHERE symbol = ?").run(symbol);
     });
   }
+
+  /**
+   * Runs `statement` through the write queue, reading `entries` back until it
+   * lands. A write of one row replaces a queued write of the same row.
+   */
+  private write(operationName: string, entries: Array<[string, PendingTicker]>, statement: () => void): void {
+    for (const [symbol, entry] of entries) this.pending.set(symbol, entry);
+    this.access.write(operationName, statement, {
+      ...(entries.length === 1 ? { key: `tickers\u0000${entries[0]![0]}` } : {}),
+      settled: () => {
+        for (const [symbol, entry] of entries) {
+          if (this.pending.get(symbol) === entry) this.pending.delete(symbol);
+        }
+      },
+    });
+  }
 }

package/src/market-data/realized-volatility.ts

@@ -3,6 +3,7 @@ import { barsPerYear } from "./bars-per-year";
 import {
   mergePriceHistoryIntegrity,
   pricePointIntegrity,
+  pricePointWicks,
   type PriceHistoryIntegrity,
 } from "../utils/price-history-integrity";
 
@@ -115,8 +116,9 @@ function observations(points: readonly PricePoint[]): Observation[] | null {
     time,
     close: positiveLog(point.close),
     open: positiveLog(point.open),
-    high: positiveLog(point.high),
-    low: positiveLog(point.low),
+    // A wick too far from the bar's body to have traded is missing, not a range.
+    high: positiveLog(pricePointWicks(point).high),
+    low: positiveLog(pricePointWicks(point).low),
     integrity: pricePointIntegrity(point),
   }));
 }

package/src/plugins/auto-update-node.ts

@@ -37,24 +37,28 @@ function readJson(path: string): Record<string, unknown> | null {
 }
 
 async function readCheckouts(): Promise<PluginCheckout[]> {
-  const { installedPluginDirectories, readPluginRemote } = await installer();
+  const { installedPluginDirectories, readPluginRemoteAsync } = await installer();
   const pluginsDir = getPluginsDir();
-  return installedPluginDirectories().map((directory) => {
+  const checkouts: PluginCheckout[] = [];
+  // One git at a time: starting a process holds the thread for a moment, and
+  // starting them all at once adds those moments up into one pause.
+  for (const directory of installedPluginDirectories()) {
     const dir = join(pluginsDir, directory);
     const pkg = readJson(join(dir, "package.json"));
     const dependencies = pkg?.dependencies;
-    return {
+    checkouts.push({
       directory,
       id: readPluginManifest(dir).id,
-      repo: existsSync(join(dir, ".git")) ? readPluginRemote(dir) : null,
+      repo: existsSync(join(dir, ".git")) ? await readPluginRemoteAsync(dir) : null,
       commit: readPluginCommit(dir),
       version: typeof pkg?.version === "string" ? pkg.version : null,
       linked: lstatSync(dir, { throwIfNoEntry: false })?.isSymbolicLink() === true,
       needsGloomberb: checkPluginCompatibility(dir)?.needsGloomberb ?? null,
       peers: installedPeerPlugins(dir, pluginsDir).map((peer) => peer.directory),
       hasDependencies: !!dependencies && typeof dependencies === "object" && Object.keys(dependencies).length > 0,
-    };
-  });
+    });
+  }
+  return checkouts;
 }
 
 function createNodeAutoUpdateDeps(manager: PluginManager): PluginAutoUpdateDeps {

package/src/plugins/builtin/central-bank-rates/series.ts

@@ -1,6 +1,6 @@
 import type { SeriesDefinition } from "../../../series/types";
 import { CENTRAL_BANKS, centralBankNames } from "../../../utils/central-banks";
-import { cachedSeriesWarning } from "../shared/series-warning";
+import { cachedSeriesNote } from "../shared/series-warning";
 import { loadCentralBankRates } from "./client";
 import { policySeriesAttribution } from "./model";
 
@@ -24,12 +24,11 @@ export const CENTRAL_BANK_SERIES: readonly SeriesDefinition[] = CENTRAL_BANKS.ma
     const resource = await loadCentralBankRates();
     const row = resource.payload.rows.find((entry) => entry.id === bank.id);
     if (!row) throw new Error(`${bank.place} is not on the board right now.`);
-    const warning = cachedSeriesWarning(resource);
     // Cited as CBR cites the row: the BIS or FRED series and the bank that sets the rate.
     const attribution = policySeriesAttribution(row);
     return {
       points: row.history.map((point) => ({ date: point.date, value: point.value })),
-      ...(warning ? { warning } : {}),
+      ...cachedSeriesNote(resource),
       ...(attribution ? { attribution } : {}),
     };
   },

package/src/plugins/builtin/chart-composer/cli-options.ts

@@ -11,6 +11,7 @@ import {
 } from "../../../time-series/spec";
 import type { ChartSeriesSpec, ChartSpec, SeriesPeriod } from "../../../time-series/types";
 import { yearToDateBaseDay } from "../../../market-data/market/year-to-date";
+import { readPriceWindow } from "../../../utils/price-window";
 
 const PRICE_CAPABILITIES = new Set(["price-chart", "intraday-price-chart", "price-comparison"]);
 
@@ -35,6 +36,13 @@ export function yearToDateWindow(spec: ChartSpec, now = Date.now()): { start: st
   return { start: starts.sort()[0] ?? `${Number(today.slice(0, 4)) - 1}-12-31`, end: today };
 }
 
+/** The shortest range whose history reaches back to `from`: 5Y for a window from 2022, ALL for one from 2019. */
+function rangeCovering(from: string, now = Date.now()): TimeRange {
+  const days = (now - Date.parse(`${from}T00:00:00Z`)) / 86_400_000;
+  const covering: Array<[TimeRange, number]> = [["1M", 31], ["3M", 92], ["6M", 183], ["1Y", 366], ["5Y", 5 * 366]];
+  return covering.find(([, span]) => days <= span)?.[0] ?? "ALL";
+}
+
 function chartResolution(options: HeadlessPaneOptionValues): ChartResolution | null {
   return parseChartResolution(options.chartResolution ?? options.resolution);
 }
@@ -77,6 +85,14 @@ export function applyChartComposerCapabilityOptions(
     };
   }
 
+  // --from and --to: those dates, each leg rebased at its first close in them, as YTD is from the prior year's last.
+  const window = capabilityId === "price-comparison"
+    ? readPriceWindow(typeof options.from === "string" ? options.from : undefined, typeof options.to === "string" ? options.to : undefined)
+    : null;
+  if (window) {
+    next = { ...next, viewport: { ...next.viewport, range: rangeCovering(window.from), dateWindow: { start: window.from, end: window.to } } };
+  }
+
   if (capabilityId === "price-chart" && options.extendedHours === true) {
     next = { ...next, viewport: { ...next.viewport, extendedHours: true } };
   }

package/src/plugins/builtin/chart-composer/headless-schema.ts

@@ -3,6 +3,7 @@ import { isSubMinuteInterval, subMinuteDataMessage } from "../../../cli/known-ga
 import { CHART_BAR_SIZE_PRESETS, parseChartBarSize } from "../../../time-series/resolution";
 import { FINANCIAL_PERIOD_OPTION, FINANCIAL_PERIOD_COUNT_OPTION, HISTORY_RANGE_VALUES, RETURN_RANGE_VALUES } from "../shared/headless-options";
 import { DATE_OPTION_EXAMPLES } from "../../../utils/calendar-date";
+import { PRICE_WINDOW_FROM_HELP, PRICE_WINDOW_TO_HELP } from "../../../utils/price-window";
 
 type PaneSchema = Pick<HeadlessPaneDefinition, "argument" | "options" | "discovery">;
 
@@ -138,6 +139,10 @@ export const paneSchemas = {
         ],
         defaultValue: "percent",
       },
+      // A window of dates, each leg rebased at its first close in it: --from 2019-12-31 compares since then.
+      { key: "from", type: "string", placeholder: "year|date", description: `${PRICE_WINDOW_FROM_HELP}; the returns are measured from its first shared close`,
+        example: "--from 2019-12-31", replaces: ["rangePreset"] },
+      { key: "to", type: "string", placeholder: "year|date", description: PRICE_WINDOW_TO_HELP },
       {
         key: "totalReturn",
         description: "Reinvest each cash distribution at its ex-date close, so the returns are total returns, not price returns.",

package/src/plugins/builtin/chart-composer/pane.tsx

@@ -20,6 +20,7 @@ import {
   type MultiSelectRowAction,
 } from "../../../components/ui";
 import { CompositeChart } from "../../../components/chart/composite";
+import { savedCopyFooterInfo } from "../../../components/layout/pane/footer";
 import { useChartViewReset, useChartViewResetListener } from "../../../components/chart/core/view-reset";
 import { formatCompositeDatasetDate } from "../../../components/chart/composite/format";
 import type { CompositeChartLevels, CompositeLevelEdit } from "../../../components/chart/composite/levels";
@@ -1116,9 +1117,12 @@ function ChartComposerSurface({
     }
     return newest > end ? formatCompositeDatasetDate(new Date(newest), end) : null;
   }, [activeRuntimeViewport, plottedSeries, spec, viewport]);
+  // A series a failed refresh left on a saved copy says when that copy was saved, as every pane does.
+  const savedAt = resolution.savedAt;
   usePaneFooter(footerId, () => ({
     info: [
       ...(delistingKey ? [{ id: "delisted", parts: [{ text: delistingKey, tone: "warning" as const }] }] : []),
+      ...savedCopyFooterInfo([savedAt]),
       ...(loading
         ? [{ id: "loading", parts: [{ text: "loading", tone: "muted" as const }] }]
         : pickingAnchor
@@ -1136,7 +1140,7 @@ function ChartComposerSurface({
       { id: "resolution", key: "b", label: "ars", title: "Bar Size", onPress: footerResolution },
       ...(anchorable ? [{ id: "vwap-anchor", key: "v", label: "wap anchor", title: "Anchor VWAP", onPress: footerAnchor }] : []),
     ],
-  }), [delistingKey, loading, pickingAnchor, newestBeyondView, footerSeries, openIndicators, indicatorsDisabled, openFormulas, formulasDisabled, footerResolution, anchorable, footerAnchor, trade]);
+  }), [delistingKey, savedAt, loading, pickingAnchor, newestBeyondView, footerSeries, openIndicators, indicatorsDisabled, openFormulas, formulasDisabled, footerResolution, anchorable, footerAnchor, trade]);
 
   // A fixed window (a GIP session) highlights no range, so the bar names it.
   const dateWindowLabel = useMemo(() => {

package/src/plugins/builtin/chart-composer/session-range.ts

@@ -4,6 +4,7 @@ import { cleanFloat32Price } from "../../../cli/history-rows";
 import { exportNumber } from "../../../cli/report-tables";
 import { publicTickerKey } from "../../../utils/exchanges";
 import { formatUtcTime } from "../../../utils/utc-time";
+import { pricePointWicks } from "../../../utils/price-history-integrity";
 
 interface SessionExtreme {
   price: number;
@@ -26,8 +27,10 @@ function sessionRange(points: readonly PricePoint[]): SessionRange | null {
   for (const point of points) {
     const at = point.date;
     if (!(at instanceof Date) || !Number.isFinite(at.getTime())) continue;
-    const pointLow = finitePositive(point.low) ?? finitePositive(point.close);
-    const pointHigh = finitePositive(point.high) ?? finitePositive(point.close);
+    // A wick too far from the bar's body to have traded is not a price the bars traded.
+    const wicks = pricePointWicks(point);
+    const pointLow = finitePositive(wicks.low) ?? finitePositive(point.close);
+    const pointHigh = finitePositive(wicks.high) ?? finitePositive(point.close);
     if (pointLow != null && (!low || pointLow < low.price)) low = { price: pointLow, at };
     if (pointHigh != null && (!high || pointHigh > high.price)) high = { price: pointHigh, at };
   }

package/src/plugins/builtin/commodity-balances/client.ts

@@ -1,4 +1,5 @@
 import { apiClient } from "../../../api-client";
+import { sourceDidNotAnswer } from "../../../api-client/errors";
 import type { PsdBoardPayload } from "../../../api-client/commodity-balances";
 import { unavailableOnServer } from "../shared/cloud-resource";
 import type { BalanceRow, PriceForecast } from "./model";
@@ -37,7 +38,9 @@ function readBoard(payload: PsdBoardPayload): CommodityBalances {
     || (payload.marketYear != null && !text(payload.marketYear))) {
     throw new Error("The server returned an invalid crop balance board");
   }
-  if (payload.status === "unavailable" || payload.rows.length === 0) throw new Error(CROPS_NOT_AVAILABLE);
+  // The server's source did not answer this time, which may pass; a board with no rows has none yet.
+  if (payload.status === "unavailable") throw sourceDidNotAnswer(CROPS_NOT_AVAILABLE);
+  if (payload.rows.length === 0) throw new Error(CROPS_NOT_AVAILABLE);
   return {
     rows: payload.rows,
     prices: payload.prices,

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

@@ -3,7 +3,10 @@ import type { CotBoardPayload, CotClass, CotClassSummary, CotContractPayload, Co
 import { createPluginCache } from "../../../data/plugin-cache";
 import { cachedCloudResource, loadCloudResource, unavailableOnServer } from "../shared/cloud-resource";
 import type { PricePoint } from "../../../types/financials";
-import { COT_CLASSES, cotPriceMapping } from "./model";
+import { COT_CLASSES, cotFrontPriceUnit, cotPriceMapping } from "./model";
+import { futuresPriceUnit, loadFuturesContractTerms, loadFuturesPriceUnit } from "../../../market-data/futures-contract";
+import { futuresBoardContract } from "../../../market-data/futures-board";
+import { settleWithin } from "../../../utils/async-deadline";
 
 export const cotBoardCache = createPluginCache<CotBoardPayload>({ kind: "cot-board", source: "gloom-cloud", schemaVersion: 1,
   policy: { staleMs: 15 * 60_000, expireMs: 8 * 24 * 60 * 60_000 } });
@@ -88,7 +91,12 @@ export async function fetchCotContract(contractCode: string, family: CotFamily,
   catch (error) { throw unavailable(error); }
 }
 export interface CotDetailData { payload: CotContractPayload; price: PricePoint[]; priceSymbol: string | null; priceAsOf: string | null; priceWarning: string | null }
-export async function loadCotDetail(contractCode: string, family: CotFamily, client: Pick<typeof apiClient, "getCloudCotContract" | "getCloudHistory"> = apiClient,
+/**
+ * A market's report and its front price. The price's unit is not waited for
+ * here: it joins the legend when it is known (loadCotPriceUnit).
+ */
+export async function loadCotDetail(contractCode: string, family: CotFamily,
+  client: Pick<typeof apiClient, "getCloudCotContract" | "getCloudHistory"> = apiClient,
   positions: CotPositions = "futures-only"): Promise<CotDetailData> {
   const payload = await fetchCotContract(contractCode, family, client, positions);
   const mapping = cotPriceMapping(contractCode);
@@ -109,3 +117,21 @@ export async function loadCotDetail(contractCode: string, family: CotFamily, cli
       priceWarning: result.stale ? "Front-price history is stale." : price.length ? null : "Front-price history unavailable." };
   } catch { return { payload, price: [], priceSymbol: mapping.priceSymbol, priceAsOf: null, priceWarning: "Front-price history unavailable. Positioning remains available." }; }
 }
+
+/** How long the front price's legend waits for the contract terms before it writes the catalog's unit. */
+const COT_PRICE_UNIT_WAIT_MS = 1_500;
+
+/**
+ * The unit a market's front price is written in, as its legend writes it
+ * after the price (cotFrontPriceUnit): `USD/gal` for heating oil. It is the
+ * contract terms' unit, else the futures catalog's where the terms fail or
+ * have not answered within `waitMs`; null for a market with no front price.
+ * The chart draws without it, so a slow answer never holds the detail up.
+ */
+export async function loadCotPriceUnit(contractCode: string, client: Pick<typeof apiClient, "getCloudFuturesContract"> = apiClient,
+  waitMs = COT_PRICE_UNIT_WAIT_MS): Promise<string | null> {
+  const symbol = cotPriceMapping(contractCode)?.priceSymbol;
+  if (!symbol) return null;
+  const terms = await settleWithin(loadFuturesPriceUnit(symbol, (key) => loadFuturesContractTerms(key, client)), waitMs);
+  return cotFrontPriceUnit(contractCode, terms ?? futuresPriceUnit(futuresBoardContract(symbol), null));
+}

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

@@ -1,7 +1,7 @@
 import type { CotClass, CotClassSummary, CotContractPayload, CotHistoryPoint } from "../../../api-client/cot";
 import type { HeadlessPaneColumn, HeadlessPaneDefinition } from "../../../types/plugin";
 import { fetchCotBoard, fetchCotContract } from "./client";
-import { COT_CLASSES, COT_FAMILIES, COT_MAJOR_CODES, COT_POSITIONS, COT_SCOPES, cotClass, cotContractCode, cotContractUnitText, cotFamily, cotInteger, cotMarketName, cotPositions, cotPositionsText, cotScope, cotUnknownMarketMessage } from "./model";
+import { COT_CLASSES, COT_FAMILIES, COT_MAJOR_CODES, COT_POSITIONS, COT_SCOPES, cotClass, cotContractCode, cotContractUnitText, cotFamily, cotInteger, cotMarketName, cotPositions, cotPositionsText, cotProxyFor, cotProxyNote, cotScope, cotUnknownMarketMessage } from "./model";
 import { COMMODITIES_VIEW_STATE } from "../commodities-energy/view-state";
 import { REPORT_ROWS } from "../shared/headless-options";
 
@@ -67,6 +67,7 @@ export const cotHeadless: HeadlessPaneDefinition<"bundle"> = {
     if (args.argument) {
       const code = cotContractCode(args.argument);
       if (!code) throw new Error(cotUnknownMarketMessage(args.argument));
+      const proxy = cotProxyFor(args.argument);
       const data = await fetchCotContract(code, family, ctx.apiClient, positions);
       const classes = data.positions.map((row) => row.id);
       const limit = args.options.limit == null ? null : Number(args.options.limit);
@@ -80,6 +81,8 @@ export const cotHeadless: HeadlessPaneDefinition<"bundle"> = {
           ...classes.map((id) => ({ key: `${camelClass(id)}Net`, header: `${data.positions.find((row) => row.id === id)?.label ?? id} net`, align: "right" as const, format: signed }))],
         rows: weeks.map((row) => ({ reportDate: row.reportDate, openInterest: row.openInterest,
           ...Object.fromEntries(row.positions.map((position) => [`${camelClass(position.id)}Net`, position.net])) })) }],
+      // "jet fuel" reads heating oil's positions, and says so.
+      ...(proxy ? { notes: [cotProxyNote(proxy)] } : {}),
       errors: data.gaps, metadata: { ...data, complete: data.status === "available" } };
     }
     const traderClass = cotClass(family, args.options.traderClass);

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

@@ -1,7 +1,7 @@
 import type { PluginModule } from "../plugin-module";
 import { cotBoardCache } from "./client";
 import { cotHeadless } from "./headless";
-import { COT_ROOT_OPTIONS, cotContractCode, cotContractCodeForTicker, cotRoot, cotUnknownMarketMessage } from "./model";
+import { COT_ROOT_OPTIONS, cotContractCode, cotContractCodeForTicker, cotProxyFor, cotRoot, cotUnknownMarketMessage } from "./model";
 import { CotPane } from "./pane";
 import { COT_SERIES } from "./series";
 
@@ -19,7 +19,9 @@ export const cotModule: PluginModule = {
       const input = options?.arg?.trim();
       const code = input ? cotContractCode(input) : cotContractCodeForTicker(context.activeTicker);
       if (input && !code) throw new Error(cotUnknownMarketMessage(input));
-      return { title: code ? `COT ${cotRoot(code) ?? code}` : "CFTC Positioning", params: code ? { code } : undefined,
+      // "jet fuel" opens heating oil, and the title says which market stands in.
+      const proxy = input ? cotProxyFor(input) : null;
+      return { title: code ? `COT ${cotRoot(code) ?? code}${proxy ? ` (${proxy.subject} proxy)` : ""}` : "CFTC Positioning", params: code ? { code } : undefined,
         settings: { report: options?.values?.report ?? "legacy" }, placement: "floating" as const };
     },
   }],

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

@@ -2,10 +2,14 @@ import type { CotClass, CotContractPayload, CotFamily, CotHistoryPoint, CotPosit
 import { staticSeries } from "../../../components/chart/static/series";
 import type { ResolvedSeries } from "../../../time-series/types";
 import type { PricePoint } from "../../../types/financials";
-import { formatPriceObservation } from "../../../market-data/market/format";
+import { formatMarketPriceWithCurrency, formatPriceObservation } from "../../../market-data/market/format";
+import { futuresPricePer } from "../../../market-data/futures-contract";
+import { unitCurrencyToken } from "../../../time-series/price-units";
 import { cleanFloat32Price } from "../../../cli/history-rows";
 import { cryptoPairCoin, isFuturesSymbol } from "../shared/crypto-pair";
-import { bestNameMatch, FUTURES_CONTRACTS, futuresBoardContract, futuresBoardContractForTicker, futuresContractByName, type FuturesContract } from "../../../market-data/futures-board";
+import {
+  bestNameMatch, FUTURES_CONTRACTS, futuresBoardContract, futuresBoardContractForTicker, futuresContractByCode, futuresContractByName, type FuturesContract,
+} from "../../../market-data/futures-board";
 
 export const COT_CLASSES: Record<CotFamily, Array<{ value: CotClass; label: string }>> = {
   legacy: [{ value: "noncommercial", label: "Noncommercial" }, { value: "commercial", label: "Commercial" }, { value: "nonreportable", label: "Nonreportable" }],
@@ -162,7 +166,35 @@ export function cotContractCode(value: unknown): string | null {
   if (alias) return alias;
   const market = typedMarket(value);
   if (market && "root" in market) return ROOTS[market.root]!.code;
-  return (market ? boardMarketCode(market.board) : null) ?? (market ? null : marketCode(input));
+  if (market) return boardMarketCode(market.board);
+  const proxy = proxyMarket(value);
+  const proxied = proxy ? futuresContractByCode(proxy.root) : null;
+  return (proxied ? boardMarketCode(proxied) : null) ?? marketCode(input);
+}
+/**
+ * Markets the CFTC does not report, opened as the one traders price and hedge
+ * them by: jet fuel (kerosene) as NY Harbor ULSD, heating oil (HO), which
+ * airlines' fuel hedges and analysts follow it with. Opened this way, the
+ * pane's title and the report say which market stands in.
+ */
+const PROXY_MARKETS: ReadonlyArray<{ names: readonly string[]; root: string; subject: string }> = [
+  { names: ["jet fuel", "jet fuels", "kerosene", "kerosine", "jet kerosene", "aviation fuel", "avtur"], root: "HO", subject: "jet fuel" },
+];
+function proxyMarket(value: string) {
+  const typed = value.trim().toLowerCase().replace(/[\s_-]+/g, " ");
+  return PROXY_MARKETS.find((proxy) => proxy.names.includes(typed)) ?? null;
+}
+/** What a typed name opens in place of a market the CFTC does not report ("jet fuel" opens HO), or null. */
+export function cotProxyFor(value: unknown): { subject: string; root: string } | null {
+  if (typeof value !== "string" || typedMarket(value) || rootAlias(value.trim().toUpperCase())) return null;
+  const proxy = proxyMarket(value);
+  return proxy ? { subject: proxy.subject, root: proxy.root } : null;
+}
+/** The line a report opened through a proxy says: "Jet fuel has no CFTC market: heating oil (NY Harbor ULSD, HO) is the usual proxy." */
+export function cotProxyNote(proxy: { subject: string; root: string }): string {
+  const subject = `${proxy.subject[0]!.toUpperCase()}${proxy.subject.slice(1)}`;
+  return `${subject} has no CFTC market: heating oil (NY Harbor ULSD, ${proxy.root}) is the usual proxy. Its price: gloom quote ${proxy.root}=F; `
+    + "US jet fuel stocks (EIA, weekly): gloom fn G CAP:doe:jet";
 }
 /** The markets the unknown-market hint names, by the code and the word a newcomer knows them by. */
 const SUGGESTED_MARKETS: ReadonlyArray<readonly [string, string]> = [
@@ -234,10 +266,27 @@ export function cotInteger(value: number | null, signed = false): string {
   return value == null ? "--" : `${signed && value > 0 ? "+" : ""}${value.toLocaleString("en-US", { maximumFractionDigits: 0 })}`;
 }
 
+/**
+ * The front price's unit as a quote of the future writes it after the price:
+ * `USD/gal` for heating oil ($4.6218/gal), `USD` for gold, from the
+ * contract's unit ("USD / gallon"). Null where the unit names no currency
+ * (index points, Treasury points) or is unknown: the price reads bare.
+ */
+export function cotFrontPriceUnit(code: string, contractUnit: string | null | undefined): string | null {
+  const currency = contractUnit ? unitCurrencyToken(contractUnit.split("/")[0] ?? "") : null;
+  if (!currency) return null;
+  const root = cotRoot(code) ?? undefined;
+  return `${currency}${futuresPricePer({ root, spec: { unit: contractUnit } } as Parameters<typeof futuresPricePer>[0], currency)}`;
+}
+
 /** Legend values stay exact: a compact 7.8K hides the futures price and -100K the net position. */
-export function cotLegendValue(value: number, series: Pick<ResolvedSeries, "id">): string {
+export function cotLegendValue(value: number, series: Pick<ResolvedSeries, "id"> & Partial<Pick<ResolvedSeries, "unit">>): string {
+  if (series.id !== "price") return cotInteger(value, true);
   // Drop the float32 tail of provider bars without rounding away a 1/128 Treasury tick.
-  return series.id === "price" ? formatPriceObservation(cleanFloat32Price(value)) : cotInteger(value, true);
+  const price = cleanFloat32Price(value);
+  // In its currency and per its quantity, as a quote of the future reads: $4.6218/gal.
+  const [currency, per] = [series.unit?.split("/")[0]?.trim(), series.unit?.includes("/") ? `/${series.unit.split("/")[1]}` : ""];
+  return currency ? `${formatMarketPriceWithCurrency(price, currency, { assetCategory: "FUT" })}${per}` : formatPriceObservation(price);
 }
 
 /**
@@ -263,7 +312,9 @@ export function cotNetPoints(history: readonly CotHistoryPoint[], traderClass: C
   }
   return points;
 }
-export function cotChartSeries(data: CotContractPayload, traderClass: CotClass, price: readonly PricePoint[], colors: { positive: string; warning: string }): ResolvedSeries[] {
+/** `priceUnit` is the front price's (cotFrontPriceUnit), which its legend value is written in. */
+export function cotChartSeries(data: CotContractPayload, traderClass: CotClass, price: readonly PricePoint[], colors: { positive: string; warning: string },
+  priceUnit: string | null = null): ResolvedSeries[] {
   const series: ResolvedSeries[] = [{
     ...staticSeries(cotNetPoints(data.history, traderClass), { id: "net", label: `${COT_CLASSES[data.reportFamily].find((row) => row.value === traderClass)?.label ?? traderClass} net`, color: colors.warning, calendarSpaced: true }),
     panelId: "net", unit: "contracts", unitGroup: "positions",
@@ -271,7 +322,7 @@ export function cotChartSeries(data: CotContractPayload, traderClass: CotClass,
   // Net positioning is the subject, so it leads the legend and the strip; the front price follows.
   if (price.length) series.push({
     ...staticSeries(price.map((row) => ({ date: row.date, observedAt: row.date, value: row.close })), { id: "price", label: "Front price", color: colors.positive, calendarSpaced: true }),
-    panelId: "price", unit: "", unitGroup: "price",
+    panelId: "price", unit: priceUnit ?? "", unitGroup: "price",
   });
   return series;
 }

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

@@ -12,7 +12,7 @@ import { Box } from "../../../ui";
 import { useAutoRefresh } from "../../../react/auto-refresh";
 import { compareSortValues, nextHeaderSort, type SortPreference } from "../../../utils/sort-values";
 import { useResearchCloudSession } from "../shared/research-cloud-session";
-import { cachedCotBoard, loadCotBoard, loadCotDetail } from "./client";
+import { cachedCotBoard, loadCotBoard, loadCotDetail, loadCotPriceUnit } from "./client";
 import { COT_CLASSES, COT_FAMILIES, COT_MAJOR_CODES, COT_POSITIONS, COT_SCOPES, cotChartSeries, cotClass, cotContractUnitText, cotFamily, cotInteger, cotLegendValue, cotMarketName, cotPositions, cotPositionsText, cotScope, type CotScope } from "./model";
 
 const BOARD_COLUMNS: DataTableColumn[] = [
@@ -159,10 +159,14 @@ function CotDetail({ width, height, focused, code, family, positions, traderClas
   const session = useResearchCloudSession();
   const loader = useCallback(() => loadCotDetail(code, family, undefined, positions), [code, family, positions, session.requestKey]);
   const resource = useAsyncResource(loader, { clearOnError: isAccessDenied });
+  // The front price's unit joins the legend once the contract terms answer, or
+  // the catalog's after a short wait: the chart draws without waiting for it.
+  const unitLoader = useCallback(() => loadCotPriceUnit(code), [code]);
+  const priceUnit = useAsyncResource(unitLoader).data ?? null;
   const data = resource.data;
   const payload = data?.payload;
   const current = payload?.positions.find((row) => row.id === traderClass);
-  const series = useMemo(() => data ? cotChartSeries(data.payload, traderClass, data.price, colors) : [], [data, traderClass, colors]);
+  const series = useMemo(() => data ? cotChartSeries(data.payload, traderClass, data.price, colors, priceUnit) : [], [data, traderClass, colors, priceUnit]);
   // The selected class row already carries the net and both ranks, and the
   // legend names the class it charts, so the detail opens on the chart. A rank
   // over a short history is a limitation, so it sits behind the warning.

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

@@ -1,8 +1,8 @@
 import { apiClient } from "../../../api-client";
+import { sourceDidNotAnswer } from "../../../api-client/errors";
 import type { CpiBoardPayload, CpiRow } from "../../../api-client/cpi";
-import { ApiRequestError } from "../../../api-client/errors";
 import { createPluginCache } from "../../../data/plugin-cache";
-import { cachedCloudResource, loadCloudResource } from "../shared/cloud-resource";
+import { cachedCloudResource, loadCloudResource, unavailableOnServer } from "../shared/cloud-resource";
 
 /** What the pane says while the server has no months to serve: before the backend ships, or before its first read. */
 export const CPI_NOT_AVAILABLE = "US consumer prices are not available yet.";
@@ -54,11 +54,12 @@ export async function fetchCpiBoard(client: Pick<typeof apiClient, "getCloudCpiB
   try {
     payload = await client.getCloudCpiBoard();
   } catch (error) {
-    if (error instanceof ApiRequestError && (error.status === 404 || error.status === 503)) throw new Error(CPI_NOT_AVAILABLE);
-    throw error;
+    throw unavailableOnServer(error, CPI_NOT_AVAILABLE, [404, 503]);
   }
   const board = validateCpiBoard(payload);
-  if (board.status === "unavailable" || !board.release.period || !board.rows.length) throw new Error(CPI_NOT_AVAILABLE);
+  // The server's source did not answer this time: a saved copy answers, as it does a 5xx.
+  if (board.status === "unavailable") throw sourceDidNotAnswer(CPI_NOT_AVAILABLE);
+  if (!board.release.period || !board.rows.length) throw new Error(CPI_NOT_AVAILABLE);
   return board;
 }
 

package/src/plugins/builtin/credit-boards/series.ts

@@ -1,6 +1,6 @@
 import type { CreditBoardPoint } from "../../../api-client/credit-boards";
 import type { SeriesDefinition, SeriesLoadResult } from "../../../series/types";
-import { cachedSeriesWarning } from "../shared/series-warning";
+import { cachedSeriesNote } from "../shared/series-warning";
 import { loadCdxBoard, loadSovrBoard } from "./client";
 
 /** The five on-the-run 5Y index contracts the CDX tab lists; IG and iTraxx quote spread, HY and EM price. */
@@ -27,14 +27,13 @@ function boardPoints(
   rows: ReadonlyArray<{ id: string; points: readonly CreditBoardPoint[] }>,
   id: string,
   label: string,
-  resource: { stale?: boolean; refreshError?: string | null },
+  resource: { stale?: boolean; refreshError?: string | null; savedAt?: number },
 ): SeriesLoadResult {
   const row = rows.find((entry) => entry.id === id);
   if (!row) throw new Error(`${label} is not on the board right now.`);
-  const warning = cachedSeriesWarning(resource);
   return {
     points: row.points.map((point) => ({ date: point.date, value: point.level })),
-    ...(warning ? { warning } : {}),
+    ...cachedSeriesNote(resource),
   };
 }