gloomberb 0.18.4 → 0.19.0

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

@@ -4,7 +4,7 @@ import type { DataProvider } from "../../types/data-provider";
 import type { CliListing } from "../listing-arg";
 import { cliStyles, cliTerminalWidth, wrapText } from "../../utils/cli-output";
 import { isFiniteNumber } from "../../utils/guards";
-import { calculateOptionGreeks, solveChainVolatilities } from "../../plugins/builtin/options/analytics";
+import { calculateOptionGreeks, ivSolvedNote, solveChainVolatilities } from "../../plugins/builtin/options/analytics";
 import { optionQuoteSide } from "../../plugins/builtin/options/market-reference";
 import {
   formatModelSpotPrice, modelSpotLabel, optionModelSpot, type OptionModelSpot,
@@ -13,11 +13,33 @@ 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";
+import { takeOption } from "./command-utils";
 
 export const OPTIONS_USAGE = `options <symbol> [--expiration <${OPTION_EXPIRATION_PLACEHOLDER}>]`;
 
+/** `--expiration` as `options` names it, and `--expiry` as `fn GEX` and `fn OPX` do. */
+const OPTIONS_EXPIRATION_FLAGS = ["--expiration", "--expiry"] as const;
+type OptionsExpirationFlag = (typeof OPTIONS_EXPIRATION_FLAGS)[number];
+
+/**
+ * Takes the expiry option out of `args`, under either spelling: its value,
+ * the flag as typed (for messages), whether it was given at all (a flag with
+ * no value is given), and whether both spellings were.
+ */
+export function takeExpirationOption(args: string[]): {
+  value: string | undefined;
+  flag: OptionsExpirationFlag;
+  given: boolean;
+  both: boolean;
+} {
+  const typed = OPTIONS_EXPIRATION_FLAGS.filter((flag) => args.some((arg) => arg === flag || arg.startsWith(`${flag}=`)));
+  const [expiration, expiry] = OPTIONS_EXPIRATION_FLAGS.map((flag) => takeOption(args, flag));
+  return { value: expiration ?? expiry, flag: typed.length === 1 ? typed[0]! : "--expiration", given: typed.length > 0, both: typed.length > 1 };
+}
+
 export { parseOptionExpiration };
 
 /** Whether the chain holds contracts of the requested expiry, matched by UTC calendar date as the chain stamps them. */
@@ -62,16 +84,39 @@ export interface OptionModelInputs {
 interface OptionModelFigures {
   /** Annualized volatility as a fraction, solved from the chain's quotes. */
   iv: number | null;
+  /** `iv` was read off the neighbouring strikes: this strike has no two-sided out-of-the-money quote to solve from. */
+  ivFilled?: boolean;
   delta: number | null;
 }
 
 /** 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.",
+  ivSource: "mark: iv is the venue's own, never solved or filled here.",
+  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 "
     + "spot, valuation time and rate in metadata.model. Delta here and dealer gamma (GEX) are valued with it.",
+  ivSource: "solved: iv comes from the strike's out-of-the-money quote midpoint. filled: that side has no two-sided quote, so iv is read off the "
+    + "nearest solved strikes (flat beyond the last one); it is no market's volatility, and delta is valued with it all the same.",
   impliedVolatility: "The data provider's own reported implied volatility, passed through unchanged. Delta does not use it; "
     + "GEX falls back to it only at a strike with no two-sided quote on either side.",
 } as const;
@@ -97,8 +142,9 @@ function optionModelFigures(chain: OptionsChain, inputs: OptionModelInputs): Map
       for (const contract of contracts) {
         const volatility = volatilities.byStrike.get(contract.strike);
         const delta = calculateOptionGreeks(contract, side, inputs.spot, inputs.dividendYield, volatilities)?.delta;
+        const iv = volatility != null && Number.isFinite(volatility) && volatility > 0 ? volatility : null;
         figures.set(contract, {
-          iv: volatility != null && Number.isFinite(volatility) && volatility > 0 ? volatility : null,
+          iv, ivFilled: iv != null && volatilities.filled.has(contract.strike),
           delta: delta != null && Number.isFinite(delta) ? delta : null,
         });
       }
@@ -148,7 +194,8 @@ export async function loadOptionModelInputs(
 /** The chain with each contract's modeled `iv` and `delta` added; every provider field is kept. */
 export function chainWithModelFigures(chain: OptionsChain, inputs: OptionModelInputs): OptionsChain {
   const figures = optionModelFigures(chain, inputs);
-  const add = (contract: OptionContract) => ({ ...contract, iv: figures.get(contract)?.iv ?? null, delta: figures.get(contract)?.delta ?? null });
+  const add = (contract: OptionContract) => ({ ...contract, iv: figures.get(contract)?.iv ?? null, ivFilled: figures.get(contract)?.ivFilled ?? false,
+    delta: figures.get(contract)?.delta ?? null });
   return { ...chain, calls: chain.calls.map(add), puts: chain.puts.map(add) };
 }
 
@@ -161,6 +208,13 @@ export interface OptionsChainBasis {
   spot: OptionModelSpot | null;
   dividendYield: number | null;
   openInterest: OpenInterestAsOf | null;
+  /** A strike's IV is filled from its neighbours (`chainHasFilledIv`), which the closing line says. */
+  ivFilled?: boolean;
+}
+
+/** Whether any contract's IV was read off the neighbouring strikes (see `ChainVolatilities.filled`). */
+export function chainHasFilledIv(chain: OptionsChain): boolean {
+  return [...chain.calls, ...chain.puts].some((contract) => (contract as OptionContract & OptionModelFigures).ivFilled === true);
 }
 
 /** The chain with `iv` and `delta` valued at the spot `optionModelSpot` picks for it, and that spot. */
@@ -188,16 +242,31 @@ 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.
+ * The line under the chain: `Greeks at spot 89.79 (close Mon 12 Oct 20:00 UTC), dividend yield 2.34%, rate 4% · IV solved from quote mids ·
+ * OI as of Fri 9 Oct`, with `, ~ filled from neighbouring strikes` after the IV when a strike has no quote to solve from.
+ * 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%.
       + `dividend yield ${basis.dividendYield == null ? "unknown (valued at 0%)" : `${Number((basis.dividendYield * 100).toFixed(2))}%`}, `
       + `rate ${Number((OPTION_MODEL_RATE * 100).toFixed(2))}%`);
+    parts.push(ivSolvedNote(basis.ivFilled === true));
   }
   const oi = basis.openInterest;
   parts.push(oi?.date ? openInterestAsOfLabel(oi)
@@ -234,20 +303,48 @@ export function optionRows(chain: OptionsChain) {
       volume: contract.volume,
       openInterest: contract.openInterest,
       iv: modeled.iv ?? null,
+      // Solved from the strike's quote, or filled from its neighbours when it has none to solve from; a venue's own mark is neither.
+      ivSource: modeled.iv == null ? null : contract.mark ? "mark" : modeled.ivFilled ? "filled" : "solved",
       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);
 }
 
-/** Implied volatility as a percent; a dash when it could not be solved, never 0.0%. */
-export function formatOptionIvCell(value: unknown): string {
-  return isFiniteNumber(value) && value > 0 ? `${(value * 100).toFixed(1)}%` : "—";
+/** Implied volatility as a percent; a dash when it could not be solved, never 0.0%, and a leading "~" when it was filled from neighbouring strikes. */
+export function formatOptionIvCell(value: unknown, row?: Record<string, unknown>): string {
+  if (!isFiniteNumber(value) || !(value > 0)) return "—";
+  const text = `${(value * 100).toFixed(1)}%`;
+  return row?.ivSource === "filled" ? `~${text}` : text;
 }
 
 /** Delta to two places, signed for puts; a dash when it could not be valued, and no "-0.00" for a far wing. */

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

@@ -281,6 +281,8 @@ export type LeapsRow = {
   // The fields below are on a row only when `--columns` asked for them.
   /** `iv`: the implied volatility the contract's delta is valued at, percent a year. */
   ivPercent?: number | null;
+  /** `iv`: `filled` when that strike has no two-sided out-of-the-money quote to solve from and its IV is read off the neighbouring strikes. */
+  ivSource?: "solved" | "filled" | null;
   /** `ivr`: the underlying's 30-day IV rank against its 52 weeks, 0 to 100, and the close it ranks. */
   ivRank?: number | null;
   ivRankAsOf?: string | null;
@@ -369,7 +371,10 @@ function screenLeapsChain(
       dataSource: chain.dataSource ?? null,
       delayMinutes: chain.delayMinutes ?? null,
     };
-    if (wants.has("iv")) row.ivPercent = contract.iv != null && Number.isFinite(contract.iv) ? round(contract.iv * 100, 2) : null;
+    if (wants.has("iv")) {
+      row.ivPercent = contract.iv != null && Number.isFinite(contract.iv) ? round(contract.iv * 100, 2) : null;
+      row.ivSource = row.ivPercent == null ? null : (contract as { ivFilled?: boolean }).ivFilled ? "filled" : "solved";
+    }
     // A two-sided quote passed the spread cap, so the midpoint is there.
     const mid = optionMid(contract)!;
     if (wants.has("cost")) row.costPerContract = round(mid * SHARES_PER_CONTRACT, 2);
@@ -694,7 +699,7 @@ const LEAPS_COLUMNS: CliResultColumn<LeapsRow>[] = [
 
 /** What each `--columns` name adds to the exports, after Extrinsic/yr %. */
 const EXTRA_EXPORT_COLUMNS: Record<LeapsExtraColumn, CliResultColumn<LeapsRow>[]> = {
-  iv: [{ key: "ivPercent", header: "IV %", align: "right", format: formatPercent }],
+  iv: [{ key: "ivPercent", header: "IV %", align: "right", format: formatPercent }, { key: "ivSource", header: "IV source" }],
   ivr: [{ key: "ivRank", header: "IV Rank", align: "right" }, { key: "ivRankAsOf", header: "IV Rank As Of" }],
   cost: [{ key: "costPerContract", header: "Cost/Contract (mid x 100)", align: "right" }],
   breakeven: [
@@ -717,7 +722,8 @@ const LEAPS_TEXT_COLUMNS: CliResultColumn<LeapsRow>[] = TEXT_COLUMN_KEYS.map((ke
 
 /** The text table's columns for a contract's own `--columns` figures; the underlying's go in a table of their own above. */
 const EXTRA_TEXT_COLUMNS: Partial<Record<LeapsExtraColumn, CliResultColumn<LeapsRow>[]>> = {
-  iv: [{ key: "ivPercent", header: "IV", align: "right", format: formatPercent }],
+  iv: [{ key: "ivPercent", header: "IV", align: "right", format: (value, row) => row.ivSource === "filled" && typeof value === "number" && Number.isFinite(value)
+    ? `~${value.toFixed(1)}%` : formatPercent(value) }],
   "carry-net": [{ key: "carryNetPerYearPercent", header: "Net/yr", align: "right", format: formatPercent }],
   cost: [{ key: "costPerContract", header: "Cost", align: "right", format: formatWhole }],
   breakeven: [

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 {
@@ -21,6 +23,7 @@ import {
   type MoverRankBasis,
 } from "../../plugins/builtin/market-movers/model";
 import { MOVER_CANDIDATES } from "../../plugins/builtin/market-movers/client";
+import { hasPartialFloat, meetsMinFloat, minFloatShares, normalizeMinFloat, PARTIAL_FLOAT_NOTE } from "../../plugins/builtin/market-movers/min-float";
 import { fetchEconCalendarFrom } from "../../plugins/builtin/econ/calendar-source";
 import { computedFredSeriesNote, seriesNotOnFred } from "../../sources/gloomberb-cloud/fred-series";
 import { EXTENDED_SESSION_LABELS, getQuoteSessionFields, type ExtendedSession } from "../../market-data/market/status";
@@ -39,7 +42,8 @@ import {
   type CountryFilter,
   type ImpactFilter,
 } from "../../plugins/builtin/econ/calendar-model";
-import { hasNoReleaseTime, hasNoStatedTime } from "../../plugins/builtin/econ/types";
+import { hasNoReleaseTime, hasNoStatedTime, type EconEvent } 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 +74,7 @@ import {
   fredExportValue,
   fredHistoryNotes,
   fredInterval,
+  fredObservesDays,
   fredObservationsFromStart,
   fredProvenance,
   fredPublicationTime,
@@ -137,7 +142,7 @@ const MOVER_LISTS: Record<string, ScreenerCategory | "trending"> = {
   "most-active": "most_actives",
   trending: "trending",
 };
-const MOVERS_USAGE = "movers [gainers|losers|active|trending] [--session regular|extended]";
+const MOVERS_USAGE = "movers [gainers|losers|active|trending] [--session regular|extended] [--min-float <shares>]";
 /** The most rows the movers list serves in one request. */
 const MOVER_REQUEST_CAP = 100;
 /** A one-shot list waits this long for its rows' average volumes and sizes, as `fn MOST` does. */
@@ -150,6 +155,16 @@ function moverRankBasis(value: string | undefined, ctx: Parameters<CliCommandDef
   return basis;
 }
 
+/** `--min-float` in shares, null for none; fails on a value that is not a share count. */
+function moverMinFloat(value: string | undefined, ctx: Parameters<CliCommandDef["execute"]>[1]): number | null {
+  if (value == null) return null;
+  try {
+    return minFloatShares(normalizeMinFloat(value));
+  } catch (error) {
+    ctx.fail(error instanceof Error ? error.message : String(error));
+  }
+}
+
 function screenerCategory(args: readonly string[], ctx: Parameters<CliCommandDef["execute"]>[1]): ScreenerCategory | "trending" {
   rejectExtraArgs(args, 1, { usage: MOVERS_USAGE, takes: "one list" }, ctx);
   const list = args[0]?.toLowerCase() ?? "gainers";
@@ -195,12 +210,14 @@ async function runMoverCommand(rawArgs: string[], ctx: Parameters<CliCommandDef[
   const args = [...rawArgs];
   const sessionOption = takeOption(args, "--session");
   const basis = moverRankBasis(sessionOption, ctx);
+  const minFloat = moverMinFloat(takeOption(args, "--min-float"), ctx);
   const category = screenerCategory(args, ctx);
   const limit = ctx.cliOptions.limit ?? 25;
   if (sessionOption != null && (category === "trending" || category === "most_actives")) {
     ctx.fail("--session ranks Gainers and Losers.", category === "trending"
       ? "Trending keeps its source's order." : "Most active ranks by volume.");
   }
+  if (minFloat != null && category === "trending") ctx.fail("--min-float filters Gainers, Losers and Most active.", "Trending carries no float.");
   if (category === "trending") {
     await withCliServices(ctx, async (services) => {
       const trending = await fetchTrending(limit, undefined, { forceRefresh: ctx.cliOptions.refresh });
@@ -216,8 +233,8 @@ async function runMoverCommand(rawArgs: string[], ctx: Parameters<CliCommandDef[
   }
 
   // After the close a price list keeps only the rows moving its way on the basis
-  // asked for, so it reads more candidates than it shows.
-  const count = category === "most_actives" ? limit : Math.min(MOVER_REQUEST_CAP, Math.max(limit, MOVER_CANDIDATES));
+  // asked for, and a minimum float drops rows, so they read more candidates than they show.
+  const count = category === "most_actives" && minFloat == null ? limit : Math.min(MOVER_REQUEST_CAP, Math.max(limit, MOVER_CANDIDATES));
   // With the saved session, as MOST reads it: a Pro account gets the real-time lists, anyone else the delayed ones.
   const movers = await withMarketData(ctx, () =>
     fetchPreferredMarketMovers(category, count, { forceRefresh: ctx.cliOptions.refresh, session: basis, metadataWaitMs: MOVER_METADATA_WAIT_MS }));
@@ -226,7 +243,7 @@ async function runMoverCommand(rawArgs: string[], ctx: Parameters<CliCommandDef[
   // the regular session's move (its close's after the close), or with
   // --session extended by the extended print's move from that close.
   const { quotes, rankedBy } = rankMoverQuotes(category, movers.quotes.map(moverRegularSession), basis);
-  const rows = quotes.slice(0, limit).map((quote) => {
+  const rows = quotes.filter((quote) => meetsMinFloat(quote.floatShares, minFloat)).slice(0, limit).map((quote) => {
     const { extended, ...row } = quote;
     return {
       ...row,
@@ -240,16 +257,18 @@ async function runMoverCommand(rawArgs: string[], ctx: Parameters<CliCommandDef[
   // As the MOST report reads it: real-time for a Pro account, delayed otherwise, each row dated by its own last price.
   ctx.printResult({
     data: rows,
-    metadata: { category, rankedBy },
+    metadata: { category, rankedBy, ...(minFloat != null ? { minFloat } : {}) },
     ...(fellBack ? { warnings: ["No pre-market or after-hours prints now, so the list is ranked by the regular-session move."] } : {}),
     freshness: rowsFreshness(rows, { status: movers.source === "cloud" ? "live" : "delayed" }, { stale: movers.stale }),
   }, {
     heading: `Ranked by ${MOVER_RANKING_LABELS[rankedBy]}`,
+    ...(minFloat != null && hasPartialFloat(rows) ? { footnote: PARTIAL_FLOAT_NOTE } : {}),
     columns: [
       ...MOVER_COLUMNS.slice(0, 4),
       ...EXTENDED_COLUMNS,
       { key: "volume", header: "Volume", align: "right", value: (row) => formatCompact(Number(row.volume)) },
       { ...MARKET_CAP_CELL, value: (row) => row.marketCap == null ? "" : formatCompact(Number(row.marketCap)) },
+      ...(minFloat != null ? [{ key: "floatShares", header: "Float", align: "right" as const, value: (row: Record<string, unknown>) => formatCompact(Number(row.floatShares)) }] : []),
     ],
   });
 }
@@ -299,6 +318,70 @@ 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" },
+  ];
+}
+
+/**
+ * The text table's columns up to the event. Plain output keeps every column a
+ * query has, so a column that is empty by construction has to be left out
+ * here, not hidden by the table: the viewer's clock only exists with --tz, and
+ * the publisher's own clock only on rows a bank or statistics office times
+ * itself. Exports keep both, so a script's header never moves.
+ */
+function econTextHeadColumns(viewerZone: string | null, publisherTimed: boolean): CliResultColumn[] {
+  return econHeadColumns(viewerZone).filter((column) => (
+    column.key === "viewerTime" ? !!viewerZone : column.key === "localTime" ? publisherTimed : true
+  ));
+}
+
+/**
+ * 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" },
+  // Which feed the forecast was read from and when, so a consensus can be told from another read of it.
+  { key: "consensusFeed", header: "consensus_feed" },
+  { key: "consensusReadAt", header: "consensus_read_at" },
+];
+
 /**
  * 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 +440,32 @@ 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)}.`);
 }
 
+/**
+ * Whether a row has come out: it has an actual, or it has no figure at all (a
+ * speech, a meeting, a holiday) and its time has passed. A row with a forecast
+ * or a prior and no actual is still to come, whatever its time.
+ */
+function cameOut(event: Pick<EconEvent, "actual" | "forecast" | "prior" | "date">, now: number): boolean {
+  if (event.actual?.trim()) return true;
+  return !event.forecast?.trim() && !event.prior?.trim() && event.date.getTime() <= now;
+}
+
+/**
+ * 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);
@@ -369,10 +478,13 @@ async function runEcon(args: string[], ctx: Parameters<CliCommandDef["execute"]>
   }
   rejectArgs(rawArgs, ECON_USAGE, ctx, "Filter with --country and --impact.");
   await withCliServices(ctx, async () => {
-    const todayStart = Math.floor(Date.now() / DAY_MS) * DAY_MS;
+    const now = Date.now();
+    const todayStart = Math.floor(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 +512,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 +523,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 +539,23 @@ 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, and for a row with no figures (a speech, a
+          // meeting) once its time has passed; its day alone when it states no time, null before.
+          released: cameOut(event, now) ? (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, as Gloom Cloud names it.
+          indicatorId: event.indicatorId ?? null,
+          // The feed the forecast was read from and when, for a row with a forecast.
+          consensusFeed: event.consensus?.source ?? null,
+          consensusReadAt: event.consensus?.readAt ?? 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 +567,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: [...econTextHeadColumns(viewerZone, rows.some((row) => !!publisherClock(row.localTime, row.timeZone))), ...econFigureColumns(true), ECON_PUBLISHER_COLUMN],
     });
   });
 }
@@ -545,12 +665,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 +694,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 +723,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)
@@ -738,8 +872,11 @@ export const overviewCliCommands: CliCommandDef[] = [
       options: [{
         flags: "--session <basis>",
         description: "Rank gainers and losers by the regular-session move (regular, the default) or by the pre-market or after-hours move from the close (extended)",
+      }, {
+        flags: "--min-float <shares>",
+        description: "Keep the gainers, losers or most active whose float (the one EQS serves) is at least this many shares, such as 10M or 500k; a row with no float is left out",
       }],
-      examples: ["movers", "movers losers --limit 10", "movers gainers --session extended", "movers trending"],
+      examples: ["movers", "movers losers --limit 10", "movers gainers --session extended", "movers gainers --min-float 10M", "movers trending"],
     },
     execute: runMoverCommand,
   },