gloomberb 0.18.4 → 0.18.5

package/src/cli/commands/market.ts

@@ -53,7 +53,9 @@ import {
 } from "../../plugins/builtin/research/analyst-model";
 import { getPublishedUsEquityCalendarYears, getPublishedUsEquitySession } from "../../market-data/published-us-sessions";
 import { isQuoteStaleForCurrentSession, noPrintsTodayText } from "../../market-data/quotes/freshness";
-import { isOptionsUnavailableError, listedOptionsAlternative, optionsUnavailableTitle } from "../../market-data/options-alternatives";
+import {
+  coinOptionsAlternativesText, isCoinWithoutOptions, isOptionsUnavailableError, listedOptionsAlternative, optionsUnavailableTitle,
+} from "../../market-data/options-alternatives";
 import {
   atReportTtmRate, cliFuturesContract, futuresContractMetrics, exportedDividendFundamentals, fundamentalsReportTables, loadDividendDistributions,
   loadReportBondFacts, renderFundamentalsReport, writesCurrencyCodes,
@@ -72,9 +74,15 @@ import {
   formatExpiryList,
   loadOptionModelInputs,
   loadOptionsChainOpenInterest,
+  chainCoinCurrency,
+  formatCoinPremiumCell,
   formatOptionDeltaCell,
+  formatOptionDollarCell,
+  formatOptionGammaCell,
   formatOptionIvCell,
   formatOptionQuoteCell,
+  isMarkedChain,
+  MARKED_OPTION_FIELDS,
   OPTION_MODEL_RATE,
   OPTION_VOLATILITY_FIELDS,
   OPTIONS_USAGE,
@@ -87,7 +95,7 @@ import {
 } from "./options-chain";
 import {
   expirationHint, expiredExpiryText, expiryIsoDate, isLiveOptionExpiry, liveDefaultExpiry, liveOptionExpiries, missingExpiryMessage,
-  OPTION_EXPIRATION_FORMAT, OPTION_EXPIRATION_PLACEHOLDER, withLiveExpiryList,
+  OPTION_EXPIRATION_FORMAT, OPTION_EXPIRATION_PLACEHOLDER, optionExpiryVenue, withLiveExpiryList,
 } from "../../utils/option-expiry";
 import { DATE_OPTION_EXAMPLES, isoDateOption, isoDateToday } from "../../utils/calendar-date";
 import { apiClient } from "../../api-client";
@@ -115,6 +123,7 @@ import {
   closedPeriodBarDay,
   formingPeriodBar,
   historyBarStatusNote,
+  venueTradingDay,
   historyCoverageWarning,
   historyFacts,
   historyFlagNote,
@@ -683,7 +692,7 @@ function changeBasisNotes(results: QuoteCliRecord[], now = Date.now()): string[]
 function withPreviousCloseDate(quote: Quote | null | undefined): (Quote & { previousCloseDate?: string | null }) | null {
   if (!quote) return null;
   const previousCloseDate = quotePreviousCloseDate(quote);
-  const entries = Object.entries(quote);
+  const entries = Object.entries(quote).filter(([key]) => key !== "previousCloseDate");
   const at = entries.findIndex(([key]) => key === "previousClose");
   entries.splice(at < 0 ? entries.length : at + 1, 0, ["previousCloseDate", previousCloseDate]);
   return Object.fromEntries(entries) as Quote & { previousCloseDate?: string | null };
@@ -1007,13 +1016,14 @@ async function runQuote(rawArgs: string[], ctx: Parameters<CliCommandDef["execut
       : listings.map((listing) => [listing, startTickerChangeLookup(market.dataProvider, listing.symbol, listing.exchange)] as const));
     // The service's quote of the moment, not each form's local copy from whenever it was last asked for:
     // BRK.B saved on NYSE, BRK-B and BRK.B:NYSE print one quote. A local copy answers only offline.
-    const results = await market.dataProvider.getQuotesBatch(targets, { forceRefresh: ctx.cliOptions.refresh, revalidate: true });
+    // Each row prints what its move is from (Chg Basis).
+    const results = await market.dataProvider.getQuotesBatch(targets, { forceRefresh: ctx.cliOptions.refresh, revalidate: true, datesChangeBasis: true });
     const listingOf = (result: QuoteBatchResult, index: number) => listings[targets.indexOf(result.target)] ?? listings[index]!;
     const asked = results.map(listingOf);
     const request = { command: commandName, noun: "quote" };
     const answers = await Promise.all(results.map((result, index) => {
       const listing = asked[index]!;
-      return answerQuote(result, listing, market, request, ctx.cliOptions.refresh, venues.get(listing) ?? null);
+      return answerQuote(result, listing, market, request, ctx.cliOptions.refresh, venues.get(listing) ?? null, { datesChangeBasis: true });
     }));
     const now = Date.now();
     const symbolChanges = await Promise.all(answers.map(async ({ result }, index) => {
@@ -1436,7 +1446,7 @@ async function loadListingHistory(
     // The status line says how far a bar still forming runs; the note is for the bars it does not name.
     gaps ?? [], historyJumpNote(data) ?? [], historyFlagNote(data) ?? [], historyMissingVolumeNote(data) ?? [],
     historyVenueVolumeNote(data) ?? [],
-    historyBarStatusNote(forming ? served : data) ?? [],
+    historyBarStatusNote(forming ? served : data, { tradingDay: venueTradingDay(venue, Date.now()) }) ?? [],
   ].flat();
   return {
     listing, identity, unit, data, resolution, interval, intraday, volume, freshness, notes,
@@ -1641,7 +1651,7 @@ async function runHistoryList(
       oldest: null,
     });
     // A saved copy is marked on the bars a symbol loaded, not on the rows drawn from them (loadListingHistory
-    // reads it there): the list ends "couldn't refresh; saved <time>" for the oldest copy among its symbols.
+    // reads it there): the list ends "couldn't refresh; saved copy from <time>" for the oldest copy among its symbols.
     const savedAt = served.flatMap((history) => history.freshness?.savedAt ?? []).sort()[0];
     const freshness = listFreshness && savedAt && !listFreshness.savedAt ? { ...listFreshness, savedAt } : listFreshness;
     const decimals = (row: Record<string, unknown>) => bySymbol.get(String(row.symbol))?.decimals ?? 2;
@@ -2642,6 +2652,8 @@ async function runOptions(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
     const fate = listingFateLoader(listing, market, quotePromise);
     const inputsPromise = loadOptionModelInputs(market.dataProvider, listing, quotePromise, refresh);
     const now = Date.now();
+    // Expiries close on the listing's clock: a coin's options (Deribit) settle at 08:00 UTC on any day.
+    const expiryVenue = optionExpiryVenue(symbol, exchange);
     const readChain = async (expiry: number | undefined) => {
       const cached = await market.dataProvider.getCachedQuery?.("getOptionsChain", [symbol, exchange, expiry, undefined])
         .load({ force: refresh });
@@ -2653,17 +2665,17 @@ async function runOptions(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
       };
     };
     // An expiry whose last session has closed has no chain to show: it says so, and names the nearest live one.
-    if (expirationDate != null && !isLiveOptionExpiry(expirationDate, now, exchange)) {
+    if (expirationDate != null && !isLiveOptionExpiry(expirationDate, now, expiryVenue)) {
       const listed = await readChain(undefined).then(({ chain }) => chain.expirationDates,
         logFailure("cli-market", "Read available option expirations failed", []));
       ctx.fail(`expiry ${expiryIsoDate(expirationDate)} for ${listing.key} `
-        + expiredExpiryText(expirationDate, listed, now, { exchange, flag: "expiration" }),
+        + expiredExpiryText(expirationDate, listed, now, { exchange: expiryVenue, flag: "expiration" }),
       `Run gloom options ${listing.key} to list the live expiries.`);
     }
     const { result, chain: read } = await loadForListing(listing, market, ctx, async () => {
       const first = await readChain(expirationDate);
       // A source can still default to the expiry that lapsed at Friday's close; the nearest live one is shown instead.
-      const live = expirationDate == null ? liveDefaultExpiry(first.chain, now, exchange) : undefined;
+      const live = expirationDate == null ? liveDefaultExpiry(first.chain, now, expiryVenue) : undefined;
       if (live === null) return { ...first, chain: { ...first.chain, calls: [], puts: [] } };
       if (live == null) return first;
       // The default's list stays the catalogue: a dated chain can list fewer expiries.
@@ -2672,6 +2684,8 @@ async function runOptions(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
         expirationDates: [...new Set([...first.chain.expirationDates, ...shown.chain.expirationDates])].sort((a, b) => a - b) } };
     }, undefined, { command: "options", noun: "options chain", fate }).catch((error: unknown) => {
       if (!isOptionsUnavailableError(error)) throw error;
+      // A coin other than BTC and ETH: say which coins have options, and the bitcoin-linked listings.
+      if (isCoinWithoutOptions(listing.key)) return ctx.fail(optionsUnavailableTitle(listing.key), coinOptionsAlternativesText("options"));
       // A future or commodity with no chain of its own: name the listed fund whose options stand in.
       const alternative = listedOptionsAlternative(listing.key);
       // A name read as a fund or an index asks about the company's stock it means, whose options are listed.
@@ -2681,13 +2695,13 @@ async function runOptions(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
           + ` Strategy payoffs: gloom fn OSA ${alternative.symbol}`
         : "Strategy payoffs on a listed underlying: gloom fn OSA <ticker>");
     });
-    const loaded = withLiveExpiryList(read, now, exchange);
+    const loaded = withLiveExpiryList(read, now, expiryVenue);
     const inputs = await inputsPromise;
     if (expirationDate != null && !chainHasExpiry(loaded, expirationDate)) {
       // An unlisted date comes back as an empty chain; its own list of expiries, else the default chain's, says what to pick.
       const listed = loaded.expirationDates.length > 0 ? loaded.expirationDates : await market.dataProvider
         .getOptionsChain(symbol, exchange, undefined, { cacheMode: "default" })
-        .then((fallback) => liveOptionExpiries(fallback.expirationDates, now, exchange),
+        .then((fallback) => liveOptionExpiries(fallback.expirationDates, now, expiryVenue),
           logFailure("cli-market", "Read available option expirations failed", []));
       const miss = missingExpiryMessage(listing.key, expirationDate, listed);
       ctx.fail(miss.message, miss.details);
@@ -2706,7 +2720,10 @@ async function runOptions(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
       : `Options refresh failed; showing the chain stored ${new Date(result.fetchedAt).toISOString()}`
         + (chain.asOf ? ` (last trade ${chain.asOf})` : "");
     const sessionWarning = refreshWarning ? null : priorSessionChainWarning(chain, identity.exchange, Date.now());
-    const modelWarning = inputs.spot == null && (chain.calls.length > 0 || chain.puts.length > 0)
+    // A venue that marks its contracts (Deribit) states IV and greeks without a quote.
+    const marked = isMarkedChain(chain);
+    const coin = chainCoinCurrency(chain);
+    const modelWarning = !marked && inputs.spot == null && (chain.calls.length > 0 || chain.puts.length > 0)
       ? `IV and delta need a current ${listing.key} quote; those columns are blank`
       : null;
     const listed = chain.expirationDates.length > 0 || chain.calls.length > 0 || chain.puts.length > 0;
@@ -2733,25 +2750,28 @@ async function runOptions(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
         // `iv` is annualised volatility and `delta` the option's change per 1.00 move in the underlying, both decimals.
         units: { iv: "annualized decimal", delta: "decimal per 1.00 move in the underlying" },
         // What each contract's `iv` and `impliedVolatility` are, so neither is read as the other.
-        fields: OPTION_VOLATILITY_FIELDS,
+        fields: marked ? MARKED_OPTION_FIELDS : OPTION_VOLATILITY_FIELDS,
         // What `iv` and `delta` on each contract are valued from; the provider's own impliedVolatility is left as sent.
-        model: {
-          spot: basisFields.spot, spotBasis: basisFields.spotBasis, spotAsOf: basisFields.spotAsOf,
-          valuationTime: modelSpot ? new Date(modelSpot.valuationTime).toISOString() : null,
-          dividendYield: inputs.dividendYield ?? null, rate: OPTION_MODEL_RATE,
-        },
+        model: marked
+          ? { venue: chain.venue ?? null, marks: "venue", rate: chain.rate ?? 0, basis: "the expiry's forward", coin }
+          : {
+            spot: basisFields.spot, spotBasis: basisFields.spotBasis, spotAsOf: basisFields.spotAsOf,
+            valuationTime: modelSpot ? new Date(modelSpot.valuationTime).toISOString() : null,
+            dividendYield: inputs.dividendYield ?? null, rate: OPTION_MODEL_RATE,
+          },
         openInterest: { asOf: basisFields.openInterestAsOf, listedAsOf: basis.openInterest?.listedDate ?? null,
           compared: basis.openInterest?.compared ?? 0, matched: basis.openInterest?.matched ?? 0 },
       },
       ...(warnings.length > 0 ? { warnings } : {}),
       freshness,
     }, {
-      heading: listingHeading(identity),
+      // Options a venue other than the US exchanges lists (Deribit's) are headed by that venue, not the coin's board.
+      heading: chain.venue ? `${cliStyles.bold(identity.name || identity.symbol)}${cliStyles.muted(`  ·  ${chain.venue}`)}` : listingHeading(identity),
       rows: (data: OptionsChain) => optionRows(data).map((row) => ({ ...row, ...basisFields })),
       // Choosing an expiry needs the list; once one is chosen the table is that expiry.
       summary: (data: OptionsChain) => expirationDate == null ? formatExpiryList(data.expirationDates) : "",
       empty: `No option contracts for ${listingTitle(identity)}.`,
-      ...(contractCount > 0 ? { footnote: optionsBasisFootnote(basis) } : {}),
+      ...(contractCount > 0 ? { footnote: optionsBasisFootnote(basis, chain) } : {}),
       exportIdentity: { symbolOrSeries: listing.key, currencyOrUnit: currency, interval: OPTIONS_EXPORT_INTERVAL },
       // Exports state each decimal's unit in its header and end every row with the spot and dates it is as of.
       columns: [
@@ -2770,8 +2790,34 @@ async function runOptions(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
         { key: "spotBasis", header: "Spot basis" },
         { key: "spotAsOf", header: "Spot as of" },
         { key: "openInterestAsOf", header: "OI as of" },
+        // A venue's marks and its coin prices (Deribit's BTC and ETH options).
+        ...(marked ? [
+          { key: "mark", header: "Mark (USD)" }, { key: "gamma", header: "Gamma (per 1.00)" },
+          { key: "vega", header: "Vega (USD per vol point)" }, { key: "theta", header: "Theta (USD per day)" },
+          { key: "forward", header: "Forward" }, { key: "expiresAt", header: "Settles" },
+        ] : []),
+        ...(coin ? [
+          { key: "coinBid", header: `Bid (${coin})` }, { key: "coinAsk", header: `Ask (${coin})` },
+          { key: "coinMark", header: `Mark (${coin})` }, { key: "coinLast", header: `Last (${coin})` },
+        ] : []),
       ],
-      textColumns: [
+      // A coin's options are quoted in the coin: its bid, ask and mark, then the mark in dollars and the venue's greeks.
+      textColumns: coin ? [
+        { key: "side", header: "Side" },
+        { key: "contract", header: "Contract", shrink: false },
+        { key: "strike", header: "Strike", align: "right" },
+        { key: "coinBid", header: `Bid ${coin}`, align: "right", format: formatCoinPremiumCell },
+        { key: "coinAsk", header: `Ask ${coin}`, align: "right", format: formatCoinPremiumCell },
+        { key: "coinMark", header: `Mark ${coin}`, align: "right", format: formatCoinPremiumCell },
+        { key: "mark", header: "Mark $", align: "right", format: formatOptionDollarCell },
+        { key: "iv", header: "IV", align: "right", format: formatOptionIvCell },
+        { key: "delta", header: "Delta", align: "right", format: formatOptionDeltaCell },
+        { key: "gamma", header: "Gamma", align: "right", format: formatOptionGammaCell, optional: true, dropPriority: 3 },
+        { key: "vega", header: "Vega $", align: "right", format: formatOptionDollarCell, optional: true, dropPriority: 2 },
+        { key: "theta", header: "Theta $", align: "right", format: formatOptionDollarCell, optional: true, dropPriority: 2 },
+        { key: "volume", header: "Vol", align: "right", format: formatCountCell, optional: true, dropPriority: 1 },
+        { key: "openInterest", header: "OI", align: "right", format: formatCountCell, optional: true, dropPriority: 1 },
+      ] : [
         { key: "side", header: "Side" },
         { key: "contract", header: "Contract", shrink: false },
         // The contract symbol already carries the date, so this goes first when the table is narrow.

package/src/cli/commands/options-chain.ts

@@ -13,8 +13,9 @@ import {
   chainOpenInterestAsOf, loadListedOpenInterest, openInterestAsOfLabel, type OpenInterestAsOf, statedOpenInterestAsOf,
 } from "../../plugins/builtin/options/open-interest-as-of";
 import { DEFAULT_OPTION_CALC_DRAFT } from "../../plugins/builtin/options-calculator/model";
-import { expiryIsoDate, OPTION_EXPIRATION_PLACEHOLDER, parseOptionExpiration } from "../../utils/option-expiry";
+import { expiryIsoDate, OPTION_EXPIRATION_PLACEHOLDER, parseOptionExpiration, settlementStampTime } from "../../utils/option-expiry";
 import { loadModelDividendYield } from "../../market-data/model-dividend-yield";
+import { formatUtcTime } from "../../utils/utc-time";
 
 export const OPTIONS_USAGE = `options <symbol> [--expiration <${OPTION_EXPIRATION_PLACEHOLDER}>]`;
 
@@ -68,6 +69,24 @@ interface OptionModelFigures {
 /** The risk-free rate every options valuation in the app assumes. */
 export const OPTION_MODEL_RATE = DEFAULT_OPTION_CALC_DRAFT.rate;
 
+/** The venue's own marks a chain carries (Deribit's), stated in its JSON metadata in place of OPTION_VOLATILITY_FIELDS. */
+export const MARKED_OPTION_FIELDS = {
+  iv: "The venue's mark implied volatility (decimal), one per contract. Delta and the other greeks under mark are the venue's too: "
+    + "Black-76 at the expiry's forward with no discounting, to its settlement.",
+  bid: "Prices in USD are the coin prices (coin) at the expiry's forward (mark.forward), the venue's own model price.",
+  mark: "price in USD; iv; delta and gamma per 1.00 move in the underlying; vega per volatility point and theta per calendar day, in USD.",
+} as const;
+
+/** Whether a venue marks the chain's contracts itself (Deribit): its IV and greeks are then used as they are. */
+export function isMarkedChain(chain: OptionsChain): boolean {
+  return [...chain.calls, ...chain.puts].some((contract) => contract.mark != null);
+}
+
+/** The coin a chain's premiums are quoted in (BTC), when a venue quotes them in one. */
+export function chainCoinCurrency(chain: OptionsChain): string | null {
+  return [...chain.calls, ...chain.puts].find((contract) => contract.coin)?.coin?.currency ?? null;
+}
+
 /** What each contract's two volatilities are, stated in the chain's JSON metadata so neither is read as the other. */
 export const OPTION_VOLATILITY_FIELDS = {
   iv: "Annualized volatility (decimal) solved from the quote midpoint, one per strike from its out-of-the-money side, at the "
@@ -189,10 +208,23 @@ export async function loadOptionsChainOpenInterest(symbol: string, chain: Option
 
 /**
  * The line under the chain: `Greeks at spot 89.79 (close Mon 12 Oct 20:00 UTC), dividend yield 2.34%, rate 4% · OI as of Fri 9 Oct`.
- * An open interest whose date cannot be established says why.
+ * An open interest whose date cannot be established says why. A chain its
+ * venue marks says whose marks they are: `Deribit marks: IV and greeks at
+ * each expiry's forward, rate 0%; $ is the BTC price at the forward · OI live, Thu 22 Oct 22:42 UTC`.
  */
-export function optionsBasisFootnote(basis: OptionsChainBasis): string {
+export function optionsBasisFootnote(basis: OptionsChainBasis, chain?: OptionsChain): string {
   const parts: string[] = [];
+  if (chain && isMarkedChain(chain)) {
+    const coin = chainCoinCurrency(chain);
+    parts.push(`${chain.venue ?? "Venue"} marks: IV and greeks at each expiry's forward, rate ${Number(((chain.rate ?? 0) * 100).toFixed(2))}%`
+      + (coin ? `; $ is the ${coin} price at the forward` : ""));
+    // Its expiries settle at a stated time (08:00 UTC), which the expiration stamps carry.
+    const settles = [...chain.calls, ...chain.puts].map((contract) => settlementStampTime(contract.expiration)).find(Boolean);
+    if (settles) parts.push(`expiries settle ${settles}`);
+    const asOf = chain.asOf ? Date.parse(chain.asOf) : Number.NaN;
+    parts.push(Number.isFinite(asOf) ? `OI live, ${formatUtcTime(new Date(asOf).toISOString())}` : openInterestAsOfLabel(basis.openInterest));
+    return parts.join(" · ");
+  }
   if (basis.spot) {
     parts.push(`Greeks at spot ${formatModelSpotPrice(basis.spot.price)} (${modelSpotLabel(basis.spot)}), `
       // An unknown yield is valued as none, and says so rather than read as a stated 0%.
@@ -236,10 +268,34 @@ export function optionRows(chain: OptionsChain) {
       iv: modeled.iv ?? null,
       delta: modeled.delta ?? null,
       expiration: expiryIsoDate(contract.expiration),
+      // A venue's marks and coin prices (Deribit), beside the dollar ones.
+      ...(contract.mark ? {
+        mark: contract.mark.price, gamma: contract.mark.gamma, vega: contract.mark.vega, theta: contract.mark.theta,
+        forward: contract.mark.forward, expiresAt: new Date(contract.expiration * 1000).toISOString(),
+      } : {}),
+      ...(contract.coin ? {
+        coinCurrency: contract.coin.currency, coinBid: contract.coin.bid, coinAsk: contract.coin.ask,
+        coinMark: contract.coin.mark, coinLast: contract.coin.last,
+      } : {}),
     };
   });
 }
 
+/** A premium in a coin, to the venue's tick (0.0001 BTC); a dash for none. */
+export function formatCoinPremiumCell(value: unknown): string {
+  return isFiniteNumber(value) && value > 0 ? value.toFixed(4) : "—";
+}
+
+/** A dollar greek or mark (vega, theta, mark) to cents; a dash for none. */
+export function formatOptionDollarCell(value: unknown): string {
+  return isFiniteNumber(value) ? value.toFixed(2) : "—";
+}
+
+/** Gamma per 1.00 move, tiny for a coin worth 80,000 dollars: to six places, as the venue shows it to five. */
+export function formatOptionGammaCell(value: unknown): string {
+  return isFiniteNumber(value) ? value.toFixed(6) : "—";
+}
+
 export function formatOptionQuoteCell(row: Record<string, unknown>, side: "bid" | "ask"): string {
   const quote = optionQuoteSide({ bid: Number(row.bid), ask: Number(row.ask) }, side);
   return quote == null ? "—" : String(quote);

package/src/cli/commands/overview.ts

@@ -3,6 +3,8 @@ import { apiClient } from "../../api-client";
 import { ApiRequestError } from "../../api-client/errors";
 import type { CliCommandDef } from "../../types/plugin";
 import { withCliServices, withMarketData } from "../context";
+import { CLI_ERROR_CODE, failWithFields } from "../errors";
+import type { CliResultColumn } from "../result";
 import { formatCompact } from "../../utils/format";
 import { DATE_OPTION_EXAMPLES, DATE_OPTION_FORMATS, dateOptionError, readCalendarDate } from "../../utils/calendar-date";
 import {
@@ -40,6 +42,7 @@ import {
   type ImpactFilter,
 } from "../../plugins/builtin/econ/calendar-model";
 import { hasNoReleaseTime, hasNoStatedTime } from "../../plugins/builtin/econ/types";
+import { econRowFigures } from "../../plugins/builtin/econ/figures";
 import { isoDate, rejectExtraArgs, requireArg, requireOneArg, takeFlag, takeOption } from "./command-utils";
 import { buildCorrelationSeries } from "../../plugins/builtin/correlation/matrix/model";
 import { alignDailyCloses, correlateDailyCloses } from "../../plugins/builtin/correlation/compute";
@@ -70,6 +73,7 @@ import {
   fredExportValue,
   fredHistoryNotes,
   fredInterval,
+  fredObservesDays,
   fredObservationsFromStart,
   fredProvenance,
   fredPublicationTime,
@@ -299,6 +303,54 @@ function publisherClock(localTime: unknown, timeZone: unknown): string {
 }
 const DAY_MS = 86_400_000;
 
+/** The calendar's columns up to the event: shared by the text table and the exports, which keep the raw values under them. */
+function econHeadColumns(viewerZone: string | null): CliResultColumn[] {
+  return [
+    // Text shows both halves of the event timestamp in UTC, never the host's zone; exports keep the source values.
+    { key: "date", header: "Date", format: (value) => utcDateTimePart(value, "date") },
+    // The weekday sits before the clock it is on: the UTC time's, or with --tz the viewer's.
+    ...viewerZone ? [] : [ECON_DAY_COLUMN],
+    // With --tz the viewer's clock has its own column, so the UTC time does not repeat it.
+    { key: "time", header: "Time", format: (value, row) => value === "All Day" ? "All day" : value === ""
+      ? "" : utcDateTimePart(row.date, "time", !viewerZone) },
+    ...viewerZone ? [ECON_DAY_COLUMN] : [],
+    // Only --tz fills it: the viewer's clock, its weekday in Day before it.
+    { key: "viewerTime", header: viewerZone ? timeZoneCity(viewerZone) : "Viewer", shrink: false,
+      format: (value) => typeof value === "string" && viewerZone ? value : "" },
+    // Only rows a publisher times itself fill it, so the feeds' calendar prints as before.
+    { key: "localTime", header: "Local", optional: true, dropPriority: 1, format: (value, row) => publisherClock(value, row.timeZone) },
+    { key: "country", header: "Country" },
+    { key: "impact", header: "Impact" },
+    { key: "event", header: "Event" },
+  ];
+}
+
+/**
+ * Actual, Forecast and Prior: as the text draws them (`30.3K`, `-4.1M bbl`) in the table, as
+ * numbers in the exports (30300, -4100000), where Unit and Scale say what they count and how they were drawn.
+ */
+function econFigureColumns(text: boolean): CliResultColumn[] {
+  return text
+    ? [{ key: "actualText", header: "Actual" }, { key: "forecastText", header: "Forecast" }, { key: "priorText", header: "Prior" }]
+    : [{ key: "actual", header: "Actual" }, { key: "forecast", header: "Forecast" }, { key: "prior", header: "Prior" }];
+}
+
+const ECON_PUBLISHER_COLUMN: CliResultColumn = {
+  key: "publisher", header: "Publisher", format: (value) => typeof value === "string" ? value : "",
+};
+
+/** What only the exports say about a row: how to read its figures, who publishes it and where, and the figures as drawn. */
+const econExportColumns: CliResultColumn[] = [
+  { key: "unit", header: "Unit" },
+  { key: "scale", header: "Scale" },
+  { key: "publisher", header: "Publisher" },
+  { key: "sourceUrl", header: "Link" },
+  // The figures as the calendar draws them, so a bound (`<1.25%`) that is no number keeps its text.
+  { key: "actualText", header: "actual_text" },
+  { key: "forecastText", header: "forecast_text" },
+  { key: "priorText", header: "prior_text" },
+];
+
 /**
  * What an empty calendar says. A window that starts after the last day listed
  * says where the listing stops, whatever the filters, rather than nothing.
@@ -357,6 +409,22 @@ function blankTimeNotes(rows: ReadonlyArray<{ event: string; country: string; ti
   return [...byNote].map(([note, events]) => `No time for ${events.join(", ")}: ${note.charAt(0).toLowerCase()}${note.slice(1)}.`);
 }
 
+/**
+ * A `--from` the stored calendar does not reach back to, which Gloom Cloud refuses
+ * with "The calendar reaches back 400 days": an input error naming the earliest
+ * day it takes, and `--json` carries it as `earliest`. Any other failure goes on as it was.
+ */
+function failBeforeCalendar(error: unknown, from: string, todayStart: number): never {
+  const days = error instanceof ApiRequestError && error.status === 422 ? /reaches back (\d+) days?/i.exec(error.message)?.[1] : undefined;
+  if (!days) throw error;
+  const earliest = isoDate(new Date(todayStart - Number(days) * DAY_MS)).slice(0, 10);
+  return failWithFields(
+    `--from ${from} is before the earliest day the calendar reaches back to, ${earliest}. Use --from ${earliest} or later.`,
+    CLI_ERROR_CODE,
+    { earliest, days: Number(days) },
+  );
+}
+
 async function runEcon(args: string[], ctx: Parameters<CliCommandDef["execute"]>[1]) {
   const rawArgs = [...args];
   const country = parseCountry(takeOption(rawArgs, "--country"), ctx);
@@ -372,7 +440,9 @@ async function runEcon(args: string[], ctx: Parameters<CliCommandDef["execute"]>
     const todayStart = Math.floor(Date.now() / DAY_MS) * DAY_MS;
     // An earlier day reads the stored calendar, which keeps past events after the week's listing drops them.
     // A server without it, a server error or no network lists the current calendar (cached when offline) instead.
-    const stored = fromOption != null && fromOption < isoDate(new Date(todayStart)) ? await fetchEconCalendarFrom(fromOption) : null;
+    const stored = fromOption != null && fromOption < isoDate(new Date(todayStart))
+      ? await fetchEconCalendarFrom(fromOption).catch((error: unknown) => failBeforeCalendar(error, fromOption, todayStart))
+      : null;
     const past = stored?.events ? stored : null;
     const unread = stored && !stored.events && stored.failure ? `The stored calendar could not be read (${stored.failure}); listing the current calendar` : null;
     const { data: events, fetchedAt, stale } = past ? { data: past.events, fetchedAt: Date.now(), stale: false } : await loadCalendar(ctx.cliOptions.refresh);
@@ -400,6 +470,8 @@ async function runEcon(args: string[], ctx: Parameters<CliCommandDef["execute"]>
       .map((event) => {
         // The viewer's clock (--tz) for a row with a time: its date and time there.
         const clock = viewerZone && !hasNoReleaseTime(event) ? zonedClock(event.date.getTime(), viewerZone) : null;
+        // The figures as numbers, scale multiplied out, with their unit and the scale they are drawn in; the text stays as drawn.
+        const figures = econRowFigures(event);
         return {
           date: isoDate(event.date),
           // The weekday on the viewer's clock (--tz), else the UTC day's; a row with no time is its day's.
@@ -409,9 +481,14 @@ async function runEcon(args: string[], ctx: Parameters<CliCommandDef["execute"]>
           country: eventCountry(event),
           impact: event.impact,
           event: event.event,
-          actual: event.actual ?? "",
-          forecast: event.forecast ?? "",
-          prior: event.prior ?? "",
+          actual: figures.actual,
+          forecast: figures.forecast,
+          prior: figures.prior,
+          unit: figures.unit,
+          scale: figures.scale,
+          actualText: event.actual ?? null,
+          forecastText: event.forecast ?? null,
+          priorText: event.prior ?? null,
           // The publisher's own clock, for rows Gloom Cloud adds from a bank's or a statistics office's calendar.
           localTime: event.localTime ?? null,
           timeZone: event.timeZone ?? null,
@@ -420,15 +497,19 @@ async function runEcon(args: string[], ctx: Parameters<CliCommandDef["execute"]>
           // Who publishes the figure (Freddie Mac for the 30-year mortgage rate), the period it covers and its page.
           publisher: event.source?.name ?? null,
           referencePeriod: event.referencePeriod ?? null,
-          source: event.source?.name ?? null,
+          // When the figure came out: the row's time once it has an actual (its day alone when it states no time), null before.
+          released: event.actual?.trim() ? (hasNoReleaseTime(event) ? isoDate(event.date).slice(0, 10) : isoDate(event.date)) : null,
           sourceUrl: event.source?.url ?? null,
+          // The same indicator from one release to the next; empty until Gloom Cloud names it.
+          indicatorId: event.indicatorId ?? null,
         };
       });
     // A filter of countries only, none of which has anything in the window, says so as its empty list.
     const allUnscheduled = unscheduled.length > 0 && unscheduled.length === country.split(",").length;
-    const footnote = [listedBefore, listedAfter, ...(rows.length > 0 ? blankTimeNotes(rows) : []),
+    const notes = [listedBefore, listedAfter, ...(rows.length > 0 ? blankTimeNotes(rows) : []),
       rows.length > 0 && unscheduled.length > 0 ? noScheduledReleasesMessage(unscheduled) : null]
-      .filter((note): note is string => !!note).join("\n");
+      .filter((note): note is string => !!note);
+    const footnote = notes.join("\n");
     ctx.printResult({
       data: rows,
       ...(unread ? { warnings: [unread] } : {}),
@@ -440,28 +521,21 @@ async function runEcon(args: string[], ctx: Parameters<CliCommandDef["execute"]>
       defaultLimit: 50,
       empty: allUnscheduled ? noScheduledReleasesMessage(unscheduled) : econEmptyMessage(from, listedThrough, listedAfter != null),
       ...(footnote ? { footnote } : {}),
-      columns: [
-        // Text shows both halves of the event timestamp in UTC, never the host's zone; exports keep the source values.
-        { key: "date", header: "Date", format: (value) => utcDateTimePart(value, "date") },
-        // The weekday sits before the clock it is on: the UTC time's, or with --tz the viewer's.
-        ...viewerZone ? [] : [ECON_DAY_COLUMN],
-        // With --tz the viewer's clock has its own column, so the UTC time does not repeat it.
-        { key: "time", header: "Time", format: (value, row) => value === "All Day" ? "All day" : value === ""
-          ? "" : utcDateTimePart(row.date, "time", !viewerZone) },
-        ...viewerZone ? [ECON_DAY_COLUMN] : [],
-        // Only --tz fills it: the viewer's clock, its weekday in Day before it.
-        { key: "viewerTime", header: viewerZone ? timeZoneCity(viewerZone) : "Viewer", shrink: false,
-          format: (value) => typeof value === "string" && viewerZone ? value : "" },
-        // Only rows a publisher times itself fill it, so the feeds' calendar prints as before.
-        { key: "localTime", header: "Local", optional: true, dropPriority: 1, format: (value, row) => publisherClock(value, row.timeZone) },
-        { key: "country", header: "Country" },
-        { key: "impact", header: "Impact" },
-        { key: "event", header: "Event" },
-        { key: "actual", header: "Actual" },
-        { key: "forecast", header: "Forecast" },
-        { key: "prior", header: "Prior" },
-        { key: "publisher", header: "Publisher", format: (value) => typeof value === "string" ? value : "" },
-      ],
+      // What the text says under the table, a script reads in the CSV's closing lines.
+      exportNotes: notes,
+      // `as_of` is the release: when a row's figure came out, blank for one that has none yet.
+      exportDated: true,
+      exportIdentity: (row) => ({
+        symbolOrSeries: typeof row.indicatorId === "string" ? row.indicatorId : null,
+        // A percent is `pct` here as in `fred` and `yield-curve`; `unit` keeps the `%` the calendar draws.
+        currencyOrUnit: row.unit === "%" ? "pct" : typeof row.unit === "string" ? row.unit : null,
+        asOf: typeof row.released === "string" ? row.released : null,
+        released: typeof row.released === "string" ? row.released : null,
+        period: typeof row.referencePeriod === "string" ? row.referencePeriod : null,
+      }),
+      // The exports add what a script needs to read a row; the text table keeps the columns it had.
+      columns: [...econHeadColumns(viewerZone), ...econFigureColumns(false), ...econExportColumns],
+      textColumns: [...econHeadColumns(viewerZone), ...econFigureColumns(true), ECON_PUBLISHER_COLUMN],
     });
   });
 }
@@ -545,12 +619,16 @@ async function runFred(rawArgs: string[], ctx: Parameters<CliCommandDef["execute
   if (mismatch) ctx.fail(mismatch);
   // Each row's change in the unit its value exports in, and the date it is from; a holiday's stays blank.
   const changes = horizon ? fredChanges(seriesId, data.observations, horizon) : null;
+  const releasedOf = (observation: { publisher?: string; publishedAt?: string; releasedOn?: string }) =>
+    observation.releasedOn ?? (observation.publisher?.trim() ? observation.publishedAt : undefined);
   // A value FRED does not list yet carries its publisher and when it published, in every export.
-  const exportRow = (observation: { date: string; value: number | null; publisher?: string; publishedAt?: string }) => ({
+  const exportRow = (observation: { date: string; value: number | null; publisher?: string; publishedAt?: string; releasedOn?: string }) => ({
     date: observation.date,
     value: fredExportValue(seriesId, observation.value),
     ...(changes ? { change: changes.get(observation.date)?.change ?? null, changeFrom: changes.get(observation.date)?.changeFrom ?? null } : {}),
     ...(observation.publisher?.trim() ? { publisher: observation.publisher.trim(), ...(observation.publishedAt ? { publishedAt: observation.publishedAt } : {}) } : {}),
+    // When the figure came out, where the data says: only a series' newest observation does. `date` is the period it covers.
+    ...releasedOf(observation) ? { released: releasedOf(observation) } : {},
   });
   // A --start before the series begins comes back padded with blank days: the rows start at its first observation.
   const rows = fredObservationsFromStart(data.observations, data.info?.observationStart)
@@ -570,6 +648,7 @@ async function runFred(rawArgs: string[], ctx: Parameters<CliCommandDef["execute
     ctx.fail(`No ${seriesId} observations on or after ${startDate}.`, fredEmptyAdvice(seriesId, latest));
   }
   const periodicity = periodicityOf(data.info?.frequency);
+  const observesDays = fredObservesDays(data.info?.frequency);
   const newestDate = rows.reduce<string | null>((newest, row) => (!newest || row.date > newest ? row.date : newest), null);
   // A newest value FRED does not list yet names its publisher, Treasury for a yield; FRED's own stay "FRED".
   const ahead = fredProvenance(data.observations.filter((observation) => observation.date === newestDate), seriesId);
@@ -598,7 +677,16 @@ async function runFred(rawArgs: string[], ctx: Parameters<CliCommandDef["execute
     dateKey: "date",
     empty: fredEmptyMessage(startDate, latest == null ? null : exportRow(latest)),
     ...(notes.length ? { footnote: notes.join("\n"), exportNotes: notes } : {}),
-    exportIdentity: { symbolOrSeries: seriesId, currencyOrUnit: unit, interval },
+    // `as_of` is the release. A figure with none stated is as of its own day when the series is known to observe
+    // days (a daily or weekly rate), and of nothing otherwise, never the first day of the period it covers.
+    exportDated: true,
+    exportIdentity: (row) => {
+      const released = typeof row.released === "string" ? row.released : null;
+      const date = typeof row.date === "string" ? row.date : null;
+      return { symbolOrSeries: seriesId, currencyOrUnit: unit, interval, asOf: released ?? (observesDays ? date : null), period: date, released };
+    },
+    // The release closes the row with the other dating columns, so it is not one of the observation's own.
+    columns: [...new Set(rows.flatMap((row) => Object.keys(row)))].filter((key) => key !== "released").map((key) => ({ key, header: key })),
     textColumns: [
       { key: "date", header: "Date" },
       isSpreadSeries(seriesId)

package/src/cli/commands/search.ts

@@ -25,6 +25,7 @@ import { formatMarketPriceWithCurrency, quoteFormatOptions } from "../../market-
 import { formerIssuerLine, startTickerChangeLookup, type TickerChangeLookup } from "../../tickers/ticker-changes";
 import { fail, failRetryable } from "../errors";
 import { isProviderBusy, SEARCH_BUSY_CODE, SEARCH_BUSY_MESSAGE } from "../../sources/provider-errors";
+import { isNetworkFailure } from "../../utils/network-failure";
 import type { MarketContext } from "../types";
 import type { CliCommandContext, GloomPlugin } from "../../types/plugin";
 import { indexRootTryLine } from "../index-roots";
@@ -137,6 +138,8 @@ export async function searchCandidatesForCli({
   } catch (error) {
     // Not "No matches found": a script or a reader would take that for a name nothing lists.
     if (isProviderBusy(error)) failRetryable(SEARCH_BUSY_MESSAGE, SEARCH_BUSY_CODE);
+    // Nor is no answer at all: the command fails as "couldn't reach", as any command offline does.
+    if (isNetworkFailure(error)) throw error;
     logFailure("cli.commands-search", "Search ticker candidates failed")(error);
     return [];
   }
@@ -204,9 +207,19 @@ function formerIssuerNote(candidate: TickerSearchCandidate): string | null {
   return formerIssuerLine(former.symbol, former, former.successor ?? { symbol: candidate.label, name: resolveSearchName(candidate) });
 }
 
-/** The merged companies' lines, once each, unless the symbol's own line already says it. */
+/**
+ * A row search found by the name its company had before it was renamed
+ * ("cassava" finds Filana Therapeutics' FLNA): says what it was called.
+ */
+function formerNameNote(candidate: TickerSearchCandidate): string | null {
+  const formerName = candidate.result?.formerName;
+  if (typeof formerName !== "string" || !formerName.trim()) return null;
+  return `${candidate.label} is ${resolveSearchName(candidate)}, formerly ${formerName.trim()}`;
+}
+
+/** The merged companies' and renamed companies' lines, once each, unless the symbol's own line already says it. */
 function formerIssuerNotes(candidates: readonly TickerSearchCandidate[], fate: SearchFate): string[] {
-  const notes = new Set(candidates.flatMap((candidate) => formerIssuerNote(candidate) ?? []));
+  const notes = new Set(candidates.flatMap((candidate) => formerIssuerNote(candidate) ?? formerNameNote(candidate) ?? []));
   return [...notes].filter((note) => !fate.notes.some((line) => line.split(" ")[0] === note.split(" ")[0]));
 }
 
@@ -366,6 +379,9 @@ function searchCandidateRows(candidates: TickerSearchCandidate[]) {
     saved: candidate.kind === "ticker",
     // The company that merged into this one, whose old name the query is.
     ...candidate.result?.formerIssuer ? { formerIssuer: candidate.result.formerIssuer } : {},
+    // The name a renamed company had, which the query is.
+    ...typeof candidate.result?.formerName === "string" && candidate.result.formerName.trim()
+      ? { formerName: candidate.result.formerName.trim() } : {},
   }));
 }