gloomberb 0.17.0 → 0.17.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gloomberb",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "packageManager": "bun@1.3.11",
   "description": "Market research and portfolio tracker for the terminal",
   "module": "src/public/index.ts",

package/src/api-client/data.ts

@@ -38,7 +38,7 @@ import type { BeneficialOwnersPayload, CloudBeneficialOwnersParams } from "./ben
 import type { SocialMentionDayPosts, SocialMentionsPayload, SocialMentionsRange } from "./social-mentions";
 import type { FuturesContractTermsPayload, FuturesCurveAsOfPayload, FuturesCurvePayload } from "./futures-curve";
 import type { CotBoardPayload, CotContractPayload, CotFamily, CotClass } from "./cot";
-import type { DoeBoardPayload } from "./doe";
+import type { DoeBoardPayload, DoePricesPayload } from "./doe";
 import type { CarbonBoard, CarbonHistory, EuropePowerBoard, EuropePowerHistory, GasStorageBoard, GasStorageHistory, GasStorageSeasonal } from "./europe-energy";
 import type { GpuBoardPayload, GpuEventsPayload, GpuHistoryPayload, GpuHistoryQuery } from "./gpu";
 import type { CpiBoardPayload } from "./cpi";
@@ -586,6 +586,10 @@ export class CloudDataApi {
     return this.request<DoeBoardPayload>("/cloud/doe/board");
   }
 
+  async getCloudDoePrices(): Promise<DoePricesPayload> {
+    return this.request<DoePricesPayload>("/cloud/doe/prices");
+  }
+
   async getCloudAttention(window: AttentionWindow = "now", symbol?: string): Promise<AttentionPayload> {
     const path = symbol ? `/cloud/attention/${encodeURIComponent(symbol)}` : "/cloud/attention";
     return this.request<AttentionPayload>(`${path}?window=${window}`);

package/src/api-client/doe.ts

@@ -73,3 +73,22 @@ export interface DoeBoardPayload {
   reports: DoeReportStatus[];
   series: DoeSeriesRow[];
 }
+
+/** One EIA weekly US retail price series, as GET /cloud/doe/prices serves it. */
+interface DoePriceSeries {
+  id: string;
+  /** The EIA source key, which a report cites. */
+  key: string;
+  label: string;
+  unit: "usd-per-gallon";
+  /** [Monday the EIA surveyed, dollars per gallon], oldest first, the last five years. */
+  points: Array<[string, number]>;
+}
+
+export interface DoePricesPayload {
+  source: "EIA";
+  generatedAt: string;
+  status: "available" | "partial" | "unavailable";
+  gaps: string[];
+  series: DoePriceSeries[];
+}

package/src/api-client/index.ts

@@ -812,6 +812,7 @@ class GloomApiClient {
   getCloudAwards = this.data.getCloudAwards.bind(this.data);
   getCloudAward = this.data.getCloudAward.bind(this.data);
   getCloudDoeBoard = this.data.getCloudDoeBoard.bind(this.data);
+  getCloudDoePrices = this.data.getCloudDoePrices.bind(this.data);
   getCloudAttention = this.data.getCloudAttention.bind(this.data);
   getCloudPowerBoard = this.data.getCloudPowerBoard.bind(this.data);
   getCloudPowerHistory = this.data.getCloudPowerHistory.bind(this.data);

package/src/app/runtime/update.ts

@@ -10,13 +10,25 @@ import {
   performUpdate,
   type ReleaseInfo,
   type UpdateCheckResult,
+  type UpdateProgress,
 } from "../../updater";
 import { VERSION } from "../../version";
+import { debugLog } from "../../utils/debug-log";
 import { reportCrash } from "../../telemetry/crash-reports";
 import { runAutomated } from "../../telemetry/usage-counts";
 
 const UPDATE_CHECK_INTERVAL_MS = 60 * 60_000; // hourly
 
+const updateLog = debugLog.createLogger("update");
+
+/**
+ * The header and the command bar show a failed update's message, and the header
+ * cuts it to its room: the log keeps what the updater actually said.
+ */
+function logUpdateFailure(progress: UpdateProgress): void {
+  if (progress.phase === "error") updateLog.error("update failed", { error: progress.error });
+}
+
 /** An update is being downloaded, applied, or is downloaded and waiting for a restart. */
 function updateInFlight(progress: AppState["updateProgress"]): boolean {
   return progress?.phase === "downloading" || progress?.phase === "replacing" || progress?.phase === "ready";
@@ -53,6 +65,7 @@ export function useAppUpdateRuntime({
   const startUpdate = useCallback((release: ReleaseInfo) => {
     dispatch({ type: "SET_UPDATE_PROGRESS", progress: { phase: "downloading", percent: 0 } });
     void performUpdate(release, (progress) => {
+      logUpdateFailure(progress);
       dispatch({ type: "SET_UPDATE_PROGRESS", progress });
     });
   }, [dispatch]);
@@ -66,6 +79,7 @@ export function useAppUpdateRuntime({
     dispatch({ type: "SET_UPDATE_PROGRESS", progress: { phase: "replacing" } });
     void applyUpdate((progress) => {
       if (progress.phase === "error") restartingRef.current = false;
+      logUpdateFailure(progress);
       dispatch({ type: "SET_UPDATE_PROGRESS", progress });
     });
   }, [dispatch, enabled, isDetachedWindow, stateRef]);
@@ -91,6 +105,8 @@ export function useAppUpdateRuntime({
       return { kind: "error", error: message || "Update check failed" };
     });
 
+    if (result.kind === "error") updateLog.warn("update check failed", { error: result.error });
+
     if (!manual) {
       if (result.kind === "available") {
         dispatch({ type: "SET_UPDATE_AVAILABLE", release: result.release });

package/src/architecture/dom-cell-metrics-allowlist.json

@@ -1,28 +1,102 @@
 {
-  "src/components/layout/pane/header.tsx": 2,
-  "src/components/layout/pane/sizing.ts": 3,
-  "src/components/layout/shell/drag/slide.ts": 4,
-  "src/components/layout/shell/pane/layers.tsx": 6,
-  "src/components/ui/select-button.tsx": 2,
-  "src/renderers/dom/data-table/dom.ts": 26,
-  "src/renderers/dom/data-table/index.tsx": 21,
-  "src/renderers/dom/data-table/row.tsx": 11,
-  "src/renderers/dom/desktop/controls.tsx": 6,
-  "src/renderers/dom/desktop/list-view.tsx": 2,
-  "src/renderers/dom/desktop/popover.tsx": 6,
-  "src/renderers/dom/desktop/query-bar.tsx": 1,
-  "src/renderers/dom/desktop/select-field.tsx": 2,
-  "src/renderers/dom/dom-ui-host.tsx": 6,
-  "src/renderers/dom/host/input.tsx": 5,
-  "src/renderers/dom/host/live-frame.ts": 8,
-  "src/renderers/dom/host/mouse.ts": 10,
-  "src/renderers/dom/host/scroll-box.tsx": 22,
-  "src/renderers/dom/host/size-observer.ts": 6,
-  "src/renderers/dom/host/style.ts": 27,
-  "src/renderers/dom/host/surface-fit.ts": 4,
-  "src/renderers/dom/host/tabs.tsx": 2,
-  "src/renderers/dom/host/text.tsx": 2,
-  "src/renderers/dom/input-host.tsx": 4,
-  "src/renderers/dom/native-renderer.ts": 4,
-  "src/renderers/dom/styles.css": 17
+  "src/components/layout/pane/header.tsx": {
+    "uses": 2,
+    "why": "The title bar's inset for the window controls comes from the shell's header geometry, which the terminal shares, in cells."
+  },
+  "src/components/layout/pane/sizing.ts": {
+    "uses": 3,
+    "why": "Panes receive their size in cells (PaneProps); this gives the desktop's taller chrome row in those cells."
+  },
+  "src/components/layout/shell/drag/slide.ts": {
+    "uses": 4,
+    "why": "A dragged pane moves by offsets of the saved layout, which is kept in cells."
+  },
+  "src/components/layout/shell/pane/layers.tsx": {
+    "uses": 6,
+    "why": "Pane rectangles in the saved layout are in cells; this is where they become pixels."
+  },
+  "src/components/ui/select-button.tsx": {
+    "uses": 2,
+    "why": "A select's width is given in cells by the pane, as its terminal button's is."
+  },
+  "src/renderers/dom/data-table/dom.ts": {
+    "uses": 26,
+    "why": "The table's scroll and pointer API speaks rows and columns to callers shared with the terminal (j/k, paging, visible range); a row of text is one line tall."
+  },
+  "src/renderers/dom/data-table/index.tsx": {
+    "uses": 19,
+    "why": "Every pane gives its columns in cells (DataTableColumn.width) and rows are one line tall: the horizontal extent, the overflow decision, virtualization and paging follow from them."
+  },
+  "src/renderers/dom/data-table/row.tsx": {
+    "uses": 10,
+    "why": "Column widths and gaps are cells in the column model every pane uses; a row is one line tall."
+  },
+  "src/renderers/dom/desktop/controls.tsx": {
+    "uses": 6,
+    "why": "Callers give a button's size in cells; a framed field keeps its text one cell off its frame, as the terminal's does."
+  },
+  "src/renderers/dom/desktop/list-view.tsx": {
+    "uses": 2,
+    "why": "The caller gives a list's height in rows."
+  },
+  "src/renderers/dom/desktop/query-bar.tsx": {
+    "uses": 1,
+    "why": "The pane gives its search field's width in cells."
+  },
+  "src/renderers/dom/desktop/select-field.tsx": {
+    "uses": 2,
+    "why": "An inline select is one row tall, the row it sits in."
+  },
+  "src/renderers/dom/dom-ui-host.tsx": {
+    "uses": 6,
+    "why": "Exposes the cell size to components that still size in cells (chart bitmaps, the company logo)."
+  },
+  "src/renderers/dom/host/input.tsx": {
+    "uses": 3,
+    "why": "Callers give a field's width and height in cells; a one-line field is one row tall."
+  },
+  "src/renderers/dom/host/live-frame.ts": {
+    "uses": 8,
+    "why": "A resize's live frame is in cells, the pane's unit, until the pane renders at the new size."
+  },
+  "src/renderers/dom/host/mouse.ts": {
+    "uses": 10,
+    "why": "Pointer handlers receive cell coordinates, the event API every renderer shares."
+  },
+  "src/renderers/dom/host/scroll-box.tsx": {
+    "uses": 22,
+    "why": "The scroller's API (scrollTop, scrollBy, viewport) is in rows and columns for callers shared with the terminal; content insets are given in cells."
+  },
+  "src/renderers/dom/host/size-observer.ts": {
+    "uses": 6,
+    "why": "Observed sizes are reported in cells, as callers expect."
+  },
+  "src/renderers/dom/host/style.ts": {
+    "uses": 27,
+    "why": "Maps the shared Box and Text props that components give in cells (width, height, padding, margin, gap, position) to pixels."
+  },
+  "src/renderers/dom/host/surface-fit.ts": {
+    "uses": 4,
+    "why": "A chart takes its box when its cells come within a cell of it, because panes still count their space in cells."
+  },
+  "src/renderers/dom/host/tabs.tsx": {
+    "uses": 2,
+    "why": "A tab strip is one row tall, the row every caller reserves for it."
+  },
+  "src/renderers/dom/host/text.tsx": {
+    "uses": 2,
+    "why": "The ASCII wordmark draws one glyph per cell."
+  },
+  "src/renderers/dom/input-host.tsx": {
+    "uses": 4,
+    "why": "The viewport is reported in cells (useViewport), the unit every renderer shares."
+  },
+  "src/renderers/dom/native-renderer.ts": {
+    "uses": 4,
+    "why": "The renderer's width and height are reported in cells, the unit every renderer shares."
+  },
+  "src/renderers/dom/styles.css": {
+    "uses": 14,
+    "why": "Defines the cell size and the base line height; status, footer and hint lines are one row; a few insets are one cell, as the terminal's (the floating pane's two-cell grip, a query bar segment)."
+  }
 }

package/src/cli/commands/market.ts

@@ -31,6 +31,7 @@ import {
   formatPriceRange,
 } from "../helpers";
 import { cliStyles, colorBySign, renderSection, renderStats } from "../../utils/cli-output";
+import { statementHistoryNotes } from "../../utils/financial-statements";
 import { formatPerShareNumber } from "../../utils/reported-money";
 import {
   analystTargetCurrency,
@@ -48,9 +49,9 @@ import type { FuturesContractTermsPayload } from "../../api-client/futures-curve
 import { futuresSettleText, isFuturesInstrument } from "../../market-data/futures-contract";
 import {
   chainHasExpiry,
-  chainWithModelFigures,
   formatExpiryList,
   loadOptionModelInputs,
+  loadOptionsChainOpenInterest,
   formatOptionDeltaCell,
   formatOptionIvCell,
   formatOptionQuoteCell,
@@ -58,7 +59,12 @@ import {
   OPTION_MODEL_RATE,
   OPTIONS_USAGE,
   optionRows,
+  optionsBasisFields,
+  optionsBasisFootnote,
   parseOptionExpiration,
+  requestListedOpenInterest,
+  valueChainAtModelSpot,
+  type OptionsChainBasis,
 } from "./options-chain";
 import { DEFAULT_LEAPS_CRITERIA, LEAPS_USAGE, parseLeapsCriteria, runLeapsScreen, takeLeapsOptions } from "./options-leaps";
 import type { CliResultColumn } from "../result";
@@ -950,11 +956,13 @@ async function runFinancials(rawArgs: string[], ctx: Parameters<CliCommandDef["e
     const freshness = rowsFreshness(rows, {
       ...REPORTED_DATA, basis: "financial statements", observedKey: "date", oldest: null,
     });
+    // The rows are the annual years served; older ones are not, and the closing lines say so.
+    const historyNotes = statementHistoryNotes("annual", rows.map((row) => row.date), listing.key);
     // NDJSON keeps the raw statement rows it always wrote; CSV gets the table and its closing lines.
     const tables = tabular
       ? selectTables({
         tables: [exportRowsTable("Annual statements", STATEMENT_COLUMNS, rows)],
-        footer: reportFooterLines({ freshness }),
+        footer: reportFooterLines({ freshness, notes: historyNotes }),
       })
       : undefined;
     ctx.printResult({
@@ -966,6 +974,7 @@ async function runFinancials(rawArgs: string[], ctx: Parameters<CliCommandDef["e
         quarterlyStatements: financials.quarterlyStatements.length,
         fundamentals: exportedFundamentals(financials.fundamentals),
         profile: financials.profile,
+        ...(historyNotes.length > 0 ? { notes: historyNotes } : {}),
       },
       freshness,
       ...(choice.length > 0 ? { warnings: choice } : {}),
@@ -973,6 +982,7 @@ async function runFinancials(rawArgs: string[], ctx: Parameters<CliCommandDef["e
       heading: listingHeading(identity),
       rows: () => rows,
       columns: STATEMENT_COLUMNS,
+      ...(historyNotes.length > 0 ? { footnote: historyNotes.join("\n"), exportNotes: historyNotes } : {}),
       ...(tables && ctx.cliOptions.format === "csv" ? { tables } : {}),
       // Annual statements in the company's reporting currency.
       exportIdentity: { symbolOrSeries: listing.key, currencyOrUnit: rows.find((row) => row.currency)?.currency ?? null, interval: "annual" },
@@ -1495,6 +1505,8 @@ async function runOptions(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
     const quotePromise = loadListingQuote(market.dataProvider, listing);
     const fate = listingFateLoader(listing, market, quotePromise);
     const inputsPromise = loadOptionModelInputs(market.dataProvider, listing, quotePromise, refresh);
+    // OPX's listing dates the chain's open interest; asked for alongside the chain when the expiry is known.
+    const listedOpenInterest = expirationDate != null ? requestListedOpenInterest(symbol, expirationDate) : null;
     const { result, chain: loaded } = await loadForListing(listing, market, ctx, async () => {
       const cached = await market.dataProvider.getCachedQuery?.("getOptionsChain", [symbol, exchange, expirationDate, undefined])
         .load({ force: refresh });
@@ -1524,7 +1536,13 @@ async function runOptions(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
     }
     const quote = await quotePromise;
     const identity = listingIdentity(listing, quote);
-    const chain = chainWithModelFigures(loaded, inputs);
+    // IV and delta are valued at one spot and instant, named under the table and on every exported row.
+    const { chain, spot: modelSpot } = valueChainAtModelSpot(loaded, inputs, Date.now(), identity.exchange);
+    const basis: OptionsChainBasis = { spot: modelSpot, dividendYield: inputs.dividendYield ?? null,
+      openInterest: await loadOptionsChainOpenInterest(symbol, chain, listedOpenInterest) };
+    const basisFields = optionsBasisFields(basis);
+    const currency = [...chain.calls, ...chain.puts].find((contract) => contract.currency?.trim())?.currency.trim().toUpperCase()
+      ?? quote?.currency ?? null;
     // A failed refresh falls back to the stored chain, which can be days old.
     const refreshWarning = result?.refreshError == null ? null
       : `Options refresh failed; showing the chain stored ${new Date(result.fetchedAt).toISOString()}`
@@ -1546,23 +1564,54 @@ async function runOptions(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
       ...(chain.delayMinutes != null ? { delayMinutes: chain.delayMinutes } : {}),
       stale: refreshWarning != null,
     });
+    const contractCount = chain.calls.length + chain.puts.length;
     ctx.printResult({
       data: chain,
       metadata: {
         ...listingMetadata(identity),
         expirations: chain.expirationDates,
+        currency,
+        interval: OPTIONS_EXPORT_INTERVAL,
+        // `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 `iv` and `delta` on each contract are valued from; the provider's own impliedVolatility is left as sent.
-        model: { spot: inputs.spot ?? null, dividendYield: inputs.dividendYield ?? null, rate: OPTION_MODEL_RATE },
+        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,
+        },
+        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),
-      rows: optionRows,
+      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) } : {}),
+      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: [
+        { key: "side", header: "Side" },
+        { key: "contract", header: "Contract" },
+        { key: "expiration", header: "Expiry" },
+        { key: "strike", header: "Strike" },
+        { key: "last", header: "Last" },
+        { key: "bid", header: "Bid" },
+        { key: "ask", header: "Ask" },
+        { key: "iv", header: "IV (annualized decimal)" },
+        { key: "delta", header: "Delta (decimal)" },
+        { key: "volume", header: "Vol" },
+        { key: "openInterest", header: "OI" },
+        { key: "spot", header: "Spot" },
+        { key: "spotBasis", header: "Spot basis" },
+        { key: "spotAsOf", header: "Spot as of" },
+        { key: "openInterestAsOf", header: "OI as of" },
+      ],
+      textColumns: [
         { 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.
@@ -1580,6 +1629,9 @@ async function runOptions(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
   });
 }
 
+/** What an options chain export's `interval` says: one quote snapshot, not bars. */
+const OPTIONS_EXPORT_INTERVAL = "snapshot";
+
 const FX_USAGE = "fx <currency> | fx <base>/<quote>";
 
 async function runFx(rawArgs: string[], ctx: Parameters<CliCommandDef["execute"]>[1]) {

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

@@ -5,6 +5,12 @@ import { cliStyles, cliTerminalWidth, wrapText } from "../../utils/cli-output";
 import { isFiniteNumber } from "../../utils/guards";
 import { calculateOptionGreeks, solveChainVolatilities } from "../../plugins/builtin/options/analytics";
 import { optionQuoteSide } from "../../plugins/builtin/options/market-reference";
+import {
+  formatModelSpotPrice, modelSpotLabel, optionModelSpot, type OptionModelSpot,
+} from "../../plugins/builtin/options/model-spot";
+import {
+  chainOpenInterestAsOf, loadListedOpenInterest, openInterestAsOfLabel, type OpenInterestAsOf,
+} from "../../plugins/builtin/options/open-interest-as-of";
 import { DEFAULT_OPTION_CALC_DRAFT } from "../../plugins/builtin/options-calculator/model";
 import { expiryIsoDate, missingExpiryText, parseOptionExpiration } from "../../utils/option-expiry";
 
@@ -61,6 +67,8 @@ export function formatExpiryList(expirations: readonly number[], width = cliTerm
 export interface OptionModelInputs {
   /** The underlying's current price; absent when the quote is missing or stale. */
   spot?: number;
+  /** The quote `spot` is read from, for the spot the chain is valued at (`optionModelSpot`). */
+  quote?: Quote;
   dividendYield?: number;
   now?: number;
 }
@@ -119,7 +127,7 @@ export async function loadOptionModelInputs(
     .find((candidate) => candidate && candidate.stale !== true && isFiniteNumber(candidate.price) && candidate.price > 0);
   const dividendYield = financials?.fundamentals?.dividendYield;
   return {
-    ...(current ? { spot: current.price } : {}),
+    ...(current ? { spot: current.price, quote: current } : {}),
     ...(isFiniteNumber(dividendYield) && dividendYield >= 0 ? { dividendYield } : {}),
   };
 }
@@ -131,6 +139,72 @@ export function chainWithModelFigures(chain: OptionsChain, inputs: OptionModelIn
   return { ...chain, calls: chain.calls.map(add), puts: chain.puts.map(add) };
 }
 
+/**
+ * What a chain's IV, delta and open interest are as of: the spot and instant
+ * they are valued at, and the session the open interest counts. The rows and
+ * the closing lines of every format say it.
+ */
+export interface OptionsChainBasis {
+  spot: OptionModelSpot | null;
+  dividendYield: number | null;
+  openInterest: OpenInterestAsOf | null;
+}
+
+/** The chain with `iv` and `delta` valued at the spot `optionModelSpot` picks for it, and that spot. */
+export function valueChainAtModelSpot(
+  chain: OptionsChain, inputs: OptionModelInputs, now: number, exchange?: string,
+): { chain: OptionsChain; spot: OptionModelSpot | null } {
+  const spot = optionModelSpot(inputs.quote, chain, now, exchange);
+  return {
+    chain: chainWithModelFigures(chain, spot ? { spot: spot.price, dividendYield: inputs.dividendYield, now: spot.valuationTime } : inputs),
+    spot,
+  };
+}
+
+/** The open-interest date of the chain's expiry, from OPX's listing of it; null when the listing cannot be read. */
+export async function loadOptionsChainOpenInterest(
+  symbol: string, chain: OptionsChain, listed?: ReturnType<typeof loadListedOpenInterest> | null,
+): Promise<OpenInterestAsOf | null> {
+  const expiration = [...chain.calls, ...chain.puts][0]?.expiration;
+  if (expiration == null) return null;
+  const payload = await (listed ?? loadListedOpenInterest(symbol, expiryIsoDate(expiration)));
+  return payload ? chainOpenInterestAsOf(chain, payload) : null;
+}
+
+/** OPX's listing of an expiry, requested while the chain loads. */
+export function requestListedOpenInterest(symbol: string, expiration: number) {
+  return loadListedOpenInterest(symbol, expiryIsoDate(expiration));
+}
+
+/**
+ * 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.
+ */
+export function optionsBasisFootnote(basis: OptionsChainBasis): string {
+  const parts: string[] = [];
+  if (basis.spot) {
+    parts.push(`Greeks at spot ${formatModelSpotPrice(basis.spot.price)} (${modelSpotLabel(basis.spot)}), `
+      + `dividend yield ${basis.dividendYield == null ? "0%" : `${Number((basis.dividendYield * 100).toFixed(2))}%`}, `
+      + `rate ${Number((OPTION_MODEL_RATE * 100).toFixed(2))}%`);
+  }
+  const oi = basis.openInterest;
+  parts.push(oi?.date ? openInterestAsOfLabel(oi)
+    : oi?.listedDate && oi.compared > 0
+      ? `OI date not published: the counts differ from OPX's ${oi.listedDate} counts on ${oi.compared - oi.matched} of ${oi.compared} contracts`
+      : openInterestAsOfLabel(null));
+  return parts.join(" · ");
+}
+
+/** The spot and open-interest fields every exported row carries. */
+export function optionsBasisFields(basis: OptionsChainBasis) {
+  return {
+    spot: basis.spot?.price ?? null,
+    spotBasis: basis.spot ? basis.spot.basis === "close" ? "close" : basis.spot.session ?? "last" : null,
+    spotAsOf: basis.spot ? new Date(basis.spot.observedAt).toISOString() : null,
+    openInterestAsOf: basis.openInterest?.date ?? null,
+  };
+}
+
 export function optionRows(chain: OptionsChain) {
   const contracts = [
     ...chain.calls.map((contract) => ({ side: "call", contract })),

package/src/cli/commands/ticker.ts

@@ -1,6 +1,6 @@
 import { formatShortDate, parseDisplayDate } from "../../utils/datetime-format";
 import { formatReportedMoney } from "../../utils/reported-money";
-import { convertedPriceEarningsNote, epsConversionNote, fundamentalsCurrency, reportedEnterpriseValue, ttmConversionNote } from "../../utils/fundamentals";
+import { convertedPriceEarningsNote, enterpriseValueLabel, enterpriseValueReconciliationNote, epsConversionNote, fundamentalsCurrency, reportedEnterpriseValue, ttmConversionNote } from "../../utils/fundamentals";
 import { latestFinancialPeriod } from "../../utils/latest-financial-period";
 import { exportedFundamentals, formatPriceEarnings, priceEarningsOnEarnings } from "../../utils/price-earnings";
 import { describeFundamentalMarketCap, selectMarketCapitalization } from "../../utils/market-capitalization";
@@ -336,6 +336,13 @@ function reportedMoney(value: number | undefined, currency: string | undefined,
   return { text: formatReportedMoney(value, currency, perShare), value, unit: currency?.trim() || "ccy?" };
 }
 
+/** The EV line: labelled "(provider)" when it is more than 5% from market cap + debt - cash, "unavailable" when withdrawn. */
+function enterpriseValueFigure(figure: MetricFigure, fundamentals: TickerFinancials["fundamentals"]): MetricFigure {
+  const label = enterpriseValueLabel(fundamentals);
+  if (label === "unavailable") return { text: "unavailable", value: null, unit: figure.unit };
+  return label === "provider" && figure.text !== "—" ? { ...figure, text: `${figure.text} (provider)` } : figure;
+}
+
 function percentFigure(fraction: number | null | undefined, format: (value: number) => string): MetricFigure {
   return fraction != null ? { text: format(fraction), value: fraction * 100, unit: "%" } : { text: "—" };
 }
@@ -366,7 +373,7 @@ function fundamentalsMetrics(
   const receipt = fundamentals?.sharesOutstanding != null && sharesOutstandingInReceipts(quote, fundamentals, profile?.description);
   return [
     { label: "Market Cap", ...marketCap },
-    { label: "Enterprise Value", ...enterpriseValue },
+    { label: "Enterprise Value", ...enterpriseValueFigure(enterpriseValue, fundamentals) },
     // A multiple over a loss is N/M, even beside a positive one the source served from an older period.
     { label: "P/E (TTM)", ...multipleFigure(priceEarningsOnEarnings(fundamentals?.trailingPE, fundamentals?.eps)) },
     { label: "Forward P/E", ...multipleFigure(priceEarningsOnEarnings(fundamentals?.forwardPE, fundamentals?.forwardEps)) },
@@ -404,10 +411,11 @@ function metricLines(metrics: readonly FundamentalsMetric[]): Array<[string, str
 const TRAILING_MONEY_METRICS = new Set(["EPS (TTM)", "Revenue (TTM)", "Net Income (TTM)", "Operating Cash Flow (TTM)", "Free Cash Flow (TTM)"]);
 
 /**
- * The unit notes under shown fundamentals: what a converted TTM block was converted from, an EPS in another
- * currency than the amounts beside it, and what a P/E on such an EPS divides.
+ * The notes under shown fundamentals: how a labelled or withdrawn EV compares with market cap + debt - cash, what a
+ * converted TTM block was converted from, an EPS in another currency than the amounts beside it, and what a P/E on
+ * such an EPS divides.
  */
-function trailingConversionNotes(
+function fundamentalsNotes(
   fundamentals: TickerFinancials["fundamentals"],
   metrics: readonly FundamentalsMetric[],
   quoteCurrency: string | undefined,
@@ -418,7 +426,8 @@ function trailingConversionNotes(
   const priceEarnings = metrics.some((metric) => metric.label === "P/E (TTM)" && typeof metric.value === "number")
     ? convertedPriceEarningsNote(fundamentals, quoteCurrency)
     : undefined;
-  return [conversion, eps, priceEarnings].filter((note): note is string => !!note);
+  const enterpriseValue = shown("Enterprise Value") ? enterpriseValueReconciliationNote(fundamentals) : undefined;
+  return [enterpriseValue, conversion, eps, priceEarnings].filter((note): note is string => !!note);
 }
 
 const VALUATION_METRICS = new Set(["Market Cap", "Enterprise Value", "P/E (TTM)", "Forward P/E", "PEG", "EPS (TTM)"]);
@@ -523,7 +532,7 @@ export function renderFundamentalsReport(
   const fund = fundFactsNote(symbol, financials.exchange || quote?.exchangeName, financials);
   if (lines.length === before) lines.push("", cliStyles.muted([`No ${view} reported for ${financials.symbol}.`, fund].filter(Boolean).join(" ")));
   else if (fund) lines.push(cliStyles.muted(fund));
-  for (const note of trailingConversionNotes(financials.fundamentals, metrics, quote?.currency)) lines.push(cliStyles.muted(note));
+  for (const note of fundamentalsNotes(financials.fundamentals, metrics, quote?.currency)) lines.push(cliStyles.muted(note));
   if (view === "fundamentals") appendTextSection(lines, "Description", profile?.description);
   return lines.join("\n");
 }
@@ -563,7 +572,7 @@ export function fundamentalsReportTables(
       notes: [
         ...metrics.length === 0
           ? [`No ${view} reported for ${financials.symbol}.`]
-          : trailingConversionNotes(financials.fundamentals, metrics, financials.quote?.currency),
+          : fundamentalsNotes(financials.fundamentals, metrics, financials.quote?.currency),
         ...fund ? [fund] : [],
       ],
     }),
@@ -726,7 +735,7 @@ export async function buildTickerReport({
   const metrics = fundamentalsMetrics(quote, priced.fundamentals, profile, { text: marketCapText }, priceReturns, fundamentalsCurrency(financials), { text: enterpriseValueText });
   const beforeFundamentals = lines.length;
   appendMetricSection(lines, "Fundamentals", metricLines(metrics));
-  for (const note of trailingConversionNotes(fundamentals, metrics, quote?.currency)) lines.push(cliStyles.muted(note));
+  for (const note of fundamentalsNotes(fundamentals, metrics, quote?.currency)) lines.push(cliStyles.muted(note));
   // Where a fund's facts would go: under its fundamentals, or in their place.
   const fund = fundFactsNote(quote?.symbol ?? symbol,
     quote?.tradingExchangeName || listingExchange || quote?.listingExchangeName || quote?.exchangeName || tickerFile?.metadata.exchange, financials, tickerFile);

package/src/cli/glossary.ts

@@ -351,7 +351,7 @@ export const GLOSSARY: readonly GlossaryEntry[] = [
     term: "TTM", aliases: ["trailing twelve months", "trailing 12 months", "trailing four quarters", "ltm", "last twelve months"],
     functions: ["FA"],
     definition: "Trailing twelve months: the four latest quarters added up, a year that ends with the latest quarter rather than the fiscal year. "
-      + "FA's quarterly leverage ratios read their flows over it, and show < 4 quarters when fewer are on file.",
+      + "FA's quarterly leverage and valuation ratios (P/E, EV / EBITDA, P/S, FCF yield) read their flows over it, and show < 4 quarters when fewer are on file.",
   },
   // Funds (ETF). Named in what ETF says it cannot show yet.
   {