gloomberb 0.16.2 → 0.16.4

package/src/plugins/builtin/vol-surface/client.ts

@@ -12,6 +12,7 @@ import {
 } from "./model";
 import { abortable, abortError } from "../../../utils/async-deadline";
 import { errorMessage } from "../../../utils/errors";
+import { findListedExpiry, unlistedExpiryText } from "../../../utils/option-expiry";
 
 const DEFAULT_SURFACE_EXPIRY_LIMIT = 18;
 const SURFACE_LOAD_CONCURRENCY = 4;
@@ -198,13 +199,16 @@ export async function loadVolatilitySurface(
     if (!chain) catalogueError ??= "Options expiry catalogue unavailable";
     catalogue = [...new Set((chain?.expirationDates ?? []).filter((expiration) =>
       Number.isFinite(expiration) && expiration > 0 && daysToExpiryFrom(expiration, now) > 0))].sort((a, b) => a - b);
+    // A typed date is that day's UTC midnight; the catalogue's stamp for the
+    // same expiry is matched by calendar date, as OMON matches it.
     const required = [...new Set([...(request.requiredExpiries ?? []), ...(request.expiries ?? [])]
-      .filter((expiration) => Number.isFinite(expiration) && expiration > 0))];
+      .filter((expiration) => Number.isFinite(expiration) && expiration > 0)
+      .map((expiration) => findListedExpiry(expiration, catalogue) ?? expiration))];
     const listed = new Set(catalogue);
     selected = [...new Set([...request.expiries ? [] : selectSurfaceExpiries(catalogue, limit, now),
       ...required.filter((expiration) => listed.has(expiration))])].sort((a, b) => a - b);
     requiredFailures = required.filter((expiration) => !listed.has(expiration)).map((expiration) => ({
-      expiration, message: "Selected expiration unavailable in the current option catalogue",
+      expiration, message: unlistedExpiryText(expiration, catalogue),
     }));
     if (chain && catalogue.length === 0) catalogueError ??= "No unexpired option expiries available";
   } catch (error) {

package/src/plugins/builtin/vol-surface/evidence.ts

@@ -3,6 +3,8 @@ import { useRemoteUiNode } from "../../../remote/semantic-tree";
 import { parsePublicTickerKey } from "../../../utils/exchanges";
 import type { SurfaceExpiry, SurfaceGrid, SurfaceSnapshot } from "./model";
 import { isFiniteNumber, isRecord } from "../../../utils/guards";
+import { expiryIsoDate } from "../../../utils/option-expiry";
+import { surfaceSkewRow } from "./tables";
 
 export interface VolSurfaceEvidenceInput {
   snapshot: SurfaceSnapshot | null | undefined;
@@ -88,11 +90,12 @@ export function volSurfaceSemanticEvidence(input: VolSurfaceEvidenceInput): VolS
   const term = view === "term" ? (snapshot?.expiries ?? []).filter((expiry) => iv(expiry.atmIV))
     .map((expiry) => ({ expiration: expiry.expiration, years: expiry.years, atm: expiry.atmIV!,
       put25: expiry.skew.put25, call25: expiry.skew.call25 })) : [];
-  const table = view === "skew" || view === "forwards" ? (snapshot?.expiries ?? []).map((expiry) => ({
-    expiration: expiry.expiration,
-    values: view === "forwards" ? [expiry.forward, expiry.dividendYield, expiry.rate]
-      : [expiry.skew.put25, expiry.skew.call25, expiry.skew.riskReversal, expiry.skew.butterfly, expiry.skew.moneynessSkew, expiry.termSlope],
-  })) : [];
+  const table = view === "skew" || view === "forwards" ? (snapshot?.expiries ?? []).map((expiry) => {
+    // The slope the table leaves out under a week to expiry is not a rendered observation.
+    const skew = surfaceSkewRow(expiry);
+    return { expiration: expiry.expiration, values: view === "forwards" ? [expiry.forward, expiry.dividendYield, expiry.rate]
+      : [skew.put25, skew.call25, skew.riskReversal, skew.butterfly, skew.moneynessSkew, skew.termSlope] };
+  }) : [];
   const counts = grid ? gridCounts(grid.values) : { values: 0, quads: 0 };
   const plottedValueCount = grid ? counts.values : smile ? smile.points.length : term.length
     || table.reduce((total, row) => total + row.values.filter(isFiniteNumber).length, 0);
@@ -186,7 +189,9 @@ export const volSurfaceScreenshotEvidence: PaneScreenshotEvidenceHook<VolSurface
     if (evidence.ivSource !== (resolved.options.ivSource ?? "recomputed")) mismatches.push("rendered volatility source does not match");
     if (evidence.priceSide !== (resolved.options.priceSide ?? "mid")) mismatches.push("rendered option quote side does not match");
     const expiration = resolved.instance?.settings?.expiration;
-    if (expiration != null && Number(expiration) !== evidence.selectedExpiration) mismatches.push("rendered volatility expiry does not match");
+    // A typed date names the listed expiry of that calendar day, whatever its stamp's time.
+    if (expiration != null && (evidence.selectedExpiration == null
+      || expiryIsoDate(Number(expiration)) !== expiryIsoDate(evidence.selectedExpiration))) mismatches.push("rendered volatility expiry does not match");
     return mismatches;
   },
   unavailable(evidence, { resolved, payload }) {

package/src/plugins/builtin/vol-surface/headless.ts

@@ -1,9 +1,18 @@
-import type { HeadlessPaneDefinition } from "../../../types/plugin";
+import type { HeadlessBundleSection, HeadlessPaneDefinition, HeadlessPaneFreshness, HeadlessPaneRow } from "../../../types/plugin";
+import {
+  expirationOptionSeconds, OPTION_EXPIRATION_FORMAT, OPTION_EXPIRATION_PLACEHOLDER, readOptionExpiration,
+} from "../../../utils/option-expiry";
 import { formatStrikeLabel } from "../options/table";
 import { createSurfaceDependencies, loadVolatilitySurface } from "./client";
-import { buildSurfaceGrid, type SurfaceGridOptions, type SurfaceSettings } from "./model";
+import { buildSurfaceGrid, type SurfaceGridOptions, type SurfaceSettings, type SurfaceSnapshot } from "./model";
+import {
+  expiryFeedFields, expiryLabel, formatIv, formatPrice, formatVolPoints, HIDDEN_SLOPE_TEXT, HIDDEN_YIELD_TEXT, selectSurfaceExpiry, surfaceForwardRow, surfaceSkewRow,
+  surfaceSmileRows, surfaceTermRows, TERM_SLOPE_MIN_DAYS, type SurfaceForwardRow, type SurfaceSkewRow,
+} from "./tables";
 
 type SurfaceAxis = NonNullable<SurfaceGridOptions["axis"]>;
+const SURFACE_TABS = ["surface", "table", "smile", "term", "skew", "forwards"] as const;
+type SurfaceTab = typeof SURFACE_TABS[number];
 
 /** Column label for a surface coordinate: strike/spot or strike/forward ratio, delta bucket, or listed strike. */
 export function surfaceCoordinateLabel(axis: SurfaceAxis, coordinate: number, index: number): string {
@@ -11,18 +20,113 @@ export function surfaceCoordinateLabel(axis: SurfaceAxis, coordinate: number, in
     : axis === "strike" ? formatStrikeLabel(coordinate) : `${Math.round(coordinate * 100)}%`;
 }
 
+/** The Skew view's sign conventions and units, one line each. */
+const SKEW_NOTES = [
+  "RR is 25D call IV minus 25D put IV, BF the average 25D wing IV minus ATM IV, 90/110 the IV at 90% of spot minus the IV at 110%; all in vol points.",
+  `Slope is the ATM IV change per year to the next listed expiry, in vol points; left out under ${TERM_SLOPE_MIN_DAYS} days to expiry, where it annualises a few hours of noise.`,
+];
+
+const number = (value: unknown) => typeof value === "number" && Number.isFinite(value) ? value : null;
+const iv = (value: unknown) => formatIv(number(value));
+const price = (value: unknown) => formatPrice(number(value));
+const points = (value: unknown) => formatVolPoints(number(value));
+const days = (value: unknown) => typeof value === "number" ? value.toFixed(value < 10 ? 1 : 0) : "--";
+
+function surfaceSections(snapshot: SurfaceSnapshot, axis: SurfaceAxis, tenors: "listed" | "fixed"): HeadlessBundleSection[] {
+  const grid = buildSurfaceGrid(snapshot, { axis, tenors });
+  return [
+    // One row per tenor, one IV column per coordinate, as the pane's Table tab lays it out.
+    { title: "Surface", columns: [
+      { key: "tenor", header: "Expiry / tenor" },
+      ...(grid.rows[0]?.cells.map((cell, index) => ({ key: String(index), header: surfaceCoordinateLabel(axis, cell.coordinate, index),
+        format: (value: unknown) => typeof value === "number" ? `${(value * 100).toFixed(1)}%` : "--" })) ?? []),
+    ], rows: grid.rows.map((row) => ({ tenor: `${row.label}${row.extrapolated ? " E" : row.interpolated ? " I" : ""}`,
+      ...Object.fromEntries(row.cells.map((cell, index) => [String(index), cell.volatility])) })) },
+    { title: "Expiries", columns: [
+      { key: "expiry", header: "Expiry" }, { key: "state", header: "State" }, { key: "forward", header: "Forward", format: price },
+      { key: "rate", header: "Rate", format: (value) => typeof value === "number" ? `${(value * 100).toFixed(2)}%` : "--" }, { key: "fit", header: "Fit" }, { key: "asOf", header: "As of" },
+    ], rows: snapshot.expiries.map((expiry) => ({ ...expiry, expiry: expiryLabel(expiry.expiration), fit: expiry.fit?.method ?? null })) },
+  ];
+}
+
+/** The selected expiry's clean quotes against its fitted smile. */
+function smileSections(snapshot: SurfaceSnapshot, requested: number | null): {
+  sections: HeadlessBundleSection[]; errors: string[]; freshness?: HeadlessPaneFreshness;
+} {
+  const expiry = selectSurfaceExpiry(snapshot, requested);
+  // An unlisted request is already an error naming the listed dates.
+  if (!expiry) return { sections: [], errors: requested == null ? ["No expiry loaded"] : [] };
+  // The quotes are one chain's, so its observation dates the report.
+  const freshness: HeadlessPaneFreshness = { asOf: expiry.asOf, ...expiry.stale ? { status: "stale" as const }
+    : expiry.dataSource ? { status: expiry.dataSource } : {}, ...expiry.delayMinutes ? { delayMinutes: expiry.delayMinutes } : {} };
+  if (!expiry.fit || expiry.points.length < 2) {
+    return { sections: [], freshness, errors: [`${expiryLabel(expiry.expiration)}: no clean quoted smile`] };
+  }
+  return { errors: [], freshness, sections: [
+    { title: `Smile ${expiryLabel(expiry.expiration)}`, entries: [
+      { key: "days", label: "Days to expiry", value: expiry.years * 365, formatted: days(expiry.years * 365) },
+      { key: "forward", label: "Forward", value: expiry.forward, formatted: price(expiry.forward) },
+      { key: "atm", label: "ATM IV (at spot)", value: expiry.atmIV, formatted: iv(expiry.atmIV) },
+      { key: "fit", label: "Fit", value: expiry.fit.method, formatted: `${expiry.fit.method}, RMSE ${points(expiry.fit.residual)} vol pts` },
+    ] },
+    { title: "Clean quotes", columns: [
+      { key: "strike", header: "Strike", format: (value) => typeof value === "number" ? formatStrikeLabel(value) : "--" },
+      { key: "side", header: "Side" },
+      { key: "moneyness", header: "Spot %", format: (value) => typeof value === "number" ? `${(value * 100).toFixed(1)}%` : "--" },
+      { key: "volatility", header: "Quote IV", format: iv }, { key: "fitted", header: "Fitted IV", format: iv },
+      { key: "residual", header: "Residual pts", format: points }, { key: "mid", header: "Mid", format: price },
+      { key: "openInterest", header: "OI" },
+    ], rows: surfaceSmileRows(expiry) },
+  ] };
+}
+
+function termSection(snapshot: SurfaceSnapshot): HeadlessBundleSection {
+  return { title: "Term structure", columns: [
+    { key: "expiry", header: "Expiry" }, { key: "days", header: "Days", format: days },
+    { key: "atm", header: "ATM IV", format: iv }, { key: "put25", header: "25D put IV", format: iv }, { key: "call25", header: "25D call IV", format: iv },
+    { key: "straddle", header: "Straddle", format: price }, { key: "sigma", header: "1-sigma", format: price },
+    { key: "sigmaPercent", header: "1-sigma %", format: (value) => typeof value === "number" ? `${value.toFixed(2)}%` : "--" },
+  ], rows: surfaceTermRows(snapshot).map((row) => ({ ...row, expiry: expiryLabel(row.expiration) })) };
+}
+
+function skewSection(snapshot: SurfaceSnapshot): HeadlessBundleSection {
+  const gap = (value: unknown, row: HeadlessPaneRow) => typeof value === "number" ? points(value) : (row as unknown as SurfaceSkewRow).gap ?? "--";
+  return { title: "Skew", columns: [
+    { key: "expiry", header: "Expiry" }, { key: "days", header: "Days", format: days },
+    { key: "put25", header: "25D put IV", format: iv }, { key: "call25", header: "25D call IV", format: iv },
+    { key: "riskReversal", header: "RR pts", format: gap }, { key: "butterfly", header: "BF pts", format: gap },
+    { key: "moneynessSkew", header: "90/110 pts", format: (value, row) => typeof value === "number" ? points(value)
+      : (row as unknown as SurfaceSkewRow).moneynessGap ?? "--" },
+    { key: "termSlope", header: "Slope pts/yr", format: (value, row) => typeof value === "number" ? points(value)
+      : (row as unknown as SurfaceSkewRow).termSlopeHidden ? HIDDEN_SLOPE_TEXT : "--" },
+  ], rows: snapshot.expiries.map((expiry) => ({ ...surfaceSkewRow(expiry), ...expiryFeedFields(expiry), expiry: expiryLabel(expiry.expiration) })) };
+}
+
+function forwardsSection(snapshot: SurfaceSnapshot): HeadlessBundleSection {
+  const percent = (value: unknown) => typeof value === "number" ? `${(value * 100).toFixed(2)}%` : "--";
+  return { title: "Forwards", columns: [
+    { key: "expiry", header: "Expiry" }, { key: "forward", header: "Forward", format: price },
+    { key: "basis", header: "Basis", format: (value) => typeof value === "number" ? `${value > 0 ? "+" : ""}${formatPrice(value)}` : "--" },
+    { key: "dividendYield", header: "Div yield", format: (value, row) => typeof value === "number" ? percent(value)
+      : (row as unknown as SurfaceForwardRow).dividendYieldHidden ? HIDDEN_YIELD_TEXT : "--" }, { key: "rate", header: "Rate", format: percent },
+    { key: "pairs", header: "Pairs" }, { key: "asOf", header: "As of", format: (value) => typeof value === "string" ? value.slice(0, 10) : "--" },
+  ], rows: snapshot.expiries.map((expiry) => ({ ...surfaceForwardRow(expiry, snapshot), ...expiryFeedFields(expiry), expiry: expiryLabel(expiry.expiration) })) };
+}
+
 export const volSurfaceHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle", argument: { kind: "ticker", description: "Underlying ticker" },
   describe: (args) => `OVDV ${args.symbols[0] ?? ""}`,
   options: [
-    { key: "tab", type: "enum", values: ["surface", "table", "smile", "term", "skew", "forwards"].map((value) => ({ value })),
-      defaultValue: "surface", description: "Initial view", pluginState: { pluginId: "ticker-research", key: "activeTabId" } },
+    { key: "tab", type: "enum", values: SURFACE_TABS.map((value) => ({ value })),
+      defaultValue: "surface", description: "Initial view; the report prints that view's figures", pluginState: { pluginId: "ticker-research", key: "activeTabId" } },
     { key: "ivSource", type: "enum", values: [{ value: "recomputed" }, { value: "provider" }], defaultValue: "recomputed", description: "Quote-derived IV or provider comparison" },
     { key: "priceSide", type: "enum", values: [{ value: "mid" }, { value: "bid" }, { value: "ask" }], defaultValue: "mid", description: "Quote side used by the IV solver" },
     { key: "axis", type: "enum", values: ["spot", "forward", "delta", "strike"].map((value) => ({ value })), defaultValue: "spot", description: "Surface coordinates" },
     { key: "tenors", type: "enum", values: [{ value: "listed" }, { value: "fixed" }], defaultValue: "listed", description: "Listed or interpolated tenors" },
     { key: "limit", type: "integer", minimum: 1, maximum: 100, defaultValue: 18, description: "Representative expiry request limit; selected expiry may add one", pluginState: { pluginId: "ticker-research", key: "expiryLimit" } },
-    { key: "expiration", type: "integer", minimum: 1, description: "Selected expiry in Unix seconds", settingKey: "expiration" },
+    { key: "expiration", type: "string", placeholder: OPTION_EXPIRATION_PLACEHOLDER, example: "--expiration 2027-01-15 --tab smile",
+      description: `Selected expiry, as ${OPTION_EXPIRATION_FORMAT}; the first at least four weeks out when omitted`,
+      settingKey: "expiration", normalize: (value) => expirationOptionSeconds(value) },
   ],
   async load(args, ctx) {
     const symbol = args.symbols[0]!;
@@ -31,39 +135,39 @@ export const volSurfaceHeadless: HeadlessPaneDefinition<"bundle"> = {
     if (!(quote.price > 0) || !Number.isFinite(quote.price) || quote.stale) {
       return { sections: [], complete: false, unavailableSymbols: [symbol], errors: ["A current underlying price is required"] };
     }
+    const requested = readOptionExpiration(args.options.expiration);
     const snapshot = await loadVolatilitySurface({ instrument, spot: quote.price, spotAsOf: quote.lastUpdated,
       settings: { ivSource: args.options.ivSource as SurfaceSettings["ivSource"], priceSide: args.options.priceSide as SurfaceSettings["priceSide"] },
       limit: Number(args.options.limit), signal: ctx.signal,
-      requiredExpiries: typeof args.options.expiration === "number" ? [args.options.expiration] : [],
+      requiredExpiries: requested == null ? [] : [requested],
     }, createSurfaceDependencies(ctx.marketData, ctx.apiClient));
     const axis = args.options.axis as SurfaceAxis;
-    const grid = buildSurfaceGrid(snapshot, { axis, tenors: args.options.tenors as "listed" | "fixed" });
+    const tab = (SURFACE_TABS as readonly string[]).includes(String(args.options.tab)) ? args.options.tab as SurfaceTab : "surface";
     const available = snapshot.expiries.some((expiry) => expiry.fit);
     const expiryWarnings = snapshot.expiries.flatMap((expiry) => expiry.warnings.map((warning) =>
-      ({ expiry: new Date(expiry.expiration * 1000).toISOString().slice(0, 10), warning })));
+      ({ expiry: expiryLabel(expiry.expiration), warning })));
     const perExpiry = new Set(expiryWarnings.map((row) => row.warning));
     // Calendar arbitrage compares expiries, so it belongs to the whole surface.
     const warnings = [...expiryWarnings, ...snapshot.warnings.filter((warning) => !perExpiry.has(warning))
       .map((warning) => ({ expiry: "All", warning }))];
+    const smile = tab === "smile" ? smileSections(snapshot, requested) : null;
+    // The report prints the view it was asked for, as the pane opens on it.
+    const view: HeadlessBundleSection[] = tab === "smile" ? smile!.sections : tab === "term" ? [termSection(snapshot)]
+      : tab === "skew" ? [skewSection(snapshot)] : tab === "forwards" ? [forwardsSection(snapshot)]
+      : surfaceSections(snapshot, axis, args.options.tenors as "listed" | "fixed");
     return {
       sections: [
-        // One row per tenor, one IV column per coordinate, as the pane's Table tab lays it out.
-        { title: "Surface", columns: [
-          { key: "tenor", header: "Expiry / tenor" },
-          ...(grid.rows[0]?.cells.map((cell, index) => ({ key: String(index), header: surfaceCoordinateLabel(axis, cell.coordinate, index),
-            format: (value: unknown) => typeof value === "number" ? `${(value * 100).toFixed(1)}%` : "--" })) ?? []),
-        ], rows: grid.rows.map((row) => ({ tenor: `${row.label}${row.extrapolated ? " E" : row.interpolated ? " I" : ""}`,
-          ...Object.fromEntries(row.cells.map((cell, index) => [String(index), cell.volatility])) })) },
-        { title: "Expiries", columns: [
-          { key: "expiry", header: "Expiry" }, { key: "state", header: "State" }, { key: "forward", header: "Forward", format: (value) => typeof value === "number" && Number.isFinite(value) ? value.toFixed(2) : "--" },
-          { key: "rate", header: "Rate", format: (value) => typeof value === "number" ? `${(value * 100).toFixed(2)}%` : "--" }, { key: "fit", header: "Fit" }, { key: "asOf", header: "As of" },
-        ], rows: snapshot.expiries.map((expiry) => ({ ...expiry, expiry: new Date(expiry.expiration * 1000).toISOString().slice(0, 10), fit: expiry.fit?.method ?? null })) },
+        ...view,
         // The pane lists these (arbitrage, SVI fallback) beside the surface; here each names its expiry.
         ...(warnings.length ? [{ title: "Warnings", columns: [{ key: "expiry", header: "Expiry" }, { key: "warning", header: "Warning" }],
           rows: warnings }] : []),
       ],
       complete: available && snapshot.failures.length === 0 && snapshot.expiries.every((expiry) => expiry.state === "ready"),
-      unavailableSymbols: available ? [] : [symbol], errors: snapshot.failures.map((failure) => failure.message),
+      unavailableSymbols: available ? [] : [symbol],
+      errors: [...snapshot.failures.map((failure) => failure.expiration == null ? failure.message
+        : `${expiryLabel(failure.expiration)}: ${failure.message}`), ...smile?.errors ?? []],
+      ...(tab === "skew" ? { notes: SKEW_NOTES } : {}),
+      ...(smile?.freshness ? { freshness: smile.freshness } : {}),
       metadata: { ...snapshot, underlyingQuote: quote, unit: "decimal annualized IV", methodology: "docs/research-data.md#shared-volatility-calculations" },
     };
   },

package/src/plugins/builtin/vol-surface/model.ts

@@ -3,7 +3,7 @@ import {
   daysToExpiryFrom, detectButterflyArbitrage, detectCalendarArbitrage, evaluateSmile, expectedMove,
   extractImpliedForward, fitVolatilitySmile, FIXED_VOLATILITY_TENORS,
   interpolateTotalVariance, logForwardMoneyness, optionDelta, optionMid,
-  smileSkew, solveImpliedVolatility, valueOption, volatilityTermSlope,
+  solveImpliedVolatility, valueOption, volatilityTermSlope,
   type ExpectedMove, type ImpliedForward, type OptionSide, type SkewMetrics, type SmileFit,
 } from "../shared/volatility";
 import type { YieldPoint } from "../yield-curve/treasury-data";
@@ -354,16 +354,7 @@ export function buildSurfaceExpiry(input: BuildSurfaceExpiryInput): SurfaceExpir
   const smile = (strike: number) => evaluateSurfaceSmile(result, strike);
   for (const point of result.points) point.fitResidual = point.volatility - (smile(point.strike) ?? point.volatility);
   result.atmIV = smile(spot);
-  const skew = smileSkew({ spot, years: result.years, rate: rate.rate, dividendYield: result.dividendYield },
-    (strike) => evaluateSmile(fit, logForwardMoneyness(strike, forward)!));
-  const putCovered = deltaStrike(result, spot, -0.25) != null;
-  const callCovered = deltaStrike(result, spot, 0.25) != null;
-  const moneynessCovered = smile(spot * 0.9) != null && smile(spot * 1.1) != null;
-  result.skew = { ...skew, atm: result.atmIV, put25: putCovered ? skew.put25 : null, call25: callCovered ? skew.call25 : null,
-    putCallSkew: putCovered && callCovered ? skew.putCallSkew : null,
-    riskReversal: putCovered && callCovered ? skew.riskReversal : null,
-    butterfly: putCovered && callCovered && result.atmIV != null ? skew.butterfly : null,
-    moneynessSkew: moneynessCovered ? skew.moneynessSkew : null };
+  result.skew = surfaceExpirySkew(result, spot);
   result.expectedMove = expectedMove(cleaned.calls, cleaned.puts, spot, result.years, result.atmIV);
   const calls = result.points.map((point) => ({ strike: point.strike, callPrice: valueOption({
     side: "call", spot: forward, strike: point.strike,
@@ -376,6 +367,27 @@ export function buildSurfaceExpiry(input: BuildSurfaceExpiryInput): SurfaceExpir
   return result;
 }
 
+/**
+ * A fitted expiry's skew in decimal IV: RR is the 25-delta call minus put, BF
+ * their average minus ATM, 90/110 the IV at 90% of spot minus 110%. The
+ * 25-delta strikes are found on the fit inside the quoted strikes, as the
+ * Table's delta columns find them, so a fit that cannot price a far wing it
+ * was never quoted at does not blank a quoted expiry's skew.
+ */
+export function surfaceExpirySkew(expiry: SurfaceExpiry, spot: number): SkewMetrics {
+  const smile = (strike: number) => evaluateSurfaceSmile(expiry, strike);
+  const at = (delta: number) => {
+    const strike = deltaStrike(expiry, spot, delta);
+    return strike == null ? null : smile(strike);
+  };
+  const put25 = at(-0.25), call25 = at(0.25), atm = expiry.atmIV;
+  const low = smile(spot * 0.9), high = smile(spot * 1.1);
+  const both = put25 != null && call25 != null;
+  return { atm, put25, call25, putCallSkew: both ? put25 - call25 : null, riskReversal: both ? call25 - put25 : null,
+    butterfly: both && atm != null ? (put25 + call25) / 2 - atm : null,
+    moneynessSkew: low != null && high != null ? low - high : null };
+}
+
 export function surfaceCalendarWarnings(expiries: readonly SurfaceExpiry[]): string[] {
   let count = 0;
   for (const ratio of SURFACE_MONEYNESS) {

package/src/plugins/builtin/vol-surface/pane.tsx

@@ -32,8 +32,11 @@ import {
   DEFAULT_SURFACE3D_CAMERA, rotateSurface3DCamera, zoomSurface3DCamera, type Surface3DCamera,
 } from "../../../components/chart/surface3d/model";
 import { VolatilitySurface } from "./surface";
-import { expiryLabel, formatIv, formatPrice, SmileChart, TermChart } from "./charts";
+import { SmileChart, TermChart } from "./charts";
 import { surfaceCoordinateLabel } from "./headless";
+import { expiryLabel, formatIv, formatPrice, formatVolPoints, HIDDEN_SLOPE_TEXT, HIDDEN_YIELD_TEXT, selectSurfaceExpiry, surfaceForwardRow,
+  surfaceSkewRow } from "./tables";
+import { findListedExpiry, unlistedExpiryText } from "../../../utils/option-expiry";
 
 const TABS = [
   { value: "surface", label: "3D surface" }, { value: "table", label: "Table" },
@@ -41,9 +44,6 @@ const TABS = [
   { value: "skew", label: "Skew" }, { value: "forwards", label: "Forwards" },
 ];
 type Axis = "spot" | "forward" | "delta" | "strike";
-const DEFAULT_EXPIRY_MIN_DAYS = 28;
-/** Annualising a few days of parity carry produces meaningless yields. */
-const DIVIDEND_YIELD_MIN_DAYS = 30;
 
 export function VolSurfacePane({ focused, width, height }: PaneProps) {
   const colors = useThemeColors();
@@ -176,14 +176,17 @@ export function VolSurfacePane({ focused, width, height }: PaneProps) {
   ] : [];
   const tableHeight = Math.max(3, height - 1 - tabRows - statGridRows(ivStats, width));
   const bitmapAvailable = !!useStaticChartBitmapSize(width, tableHeight);
+  // A typed date (`--expiration 2027-01-15`) is that day's UTC midnight; the
+  // catalogue may stamp the same expiry later in the day.
+  const pinned = expiration == null || !snapshot ? expiration : findListedExpiry(expiration, snapshot.catalogue) ?? expiration;
   useEffect(() => {
     // Existing slices only change selection. A new pin causes one load and then
     // remains in the request identity after its partial snapshots arrive.
-    if (expiration == null || expiration === requestedExpiration || resource.loading || !snapshot
-      || snapshot.expiries.some((entry) => entry.expiration === expiration)
-      || !snapshot.catalogue.includes(expiration)) return;
-    setRequestedExpiration(expiration);
-  }, [expiration, requestedExpiration, resource.loading, snapshot]);
+    if (pinned == null || pinned === requestedExpiration || resource.loading || !snapshot
+      || snapshot.expiries.some((entry) => entry.expiration === pinned)
+      || !snapshot.catalogue.includes(pinned)) return;
+    setRequestedExpiration(pinned);
+  }, [pinned, requestedExpiration, resource.loading, snapshot]);
   const grid = useMemo(() => snapshot ? buildSurfaceGrid(snapshot, { axis, tenors }) : null, [axis, snapshot, tenors]);
   // Delta columns give every expiry the same quoted wing span, so the 3D
   // surface is a full sheet; moneyness keeps each row within 2.5 ATM sigmas.
@@ -207,19 +210,16 @@ export function VolSurfacePane({ focused, width, height }: PaneProps) {
   // Sheet rows may be constant maturities: pair them with the nearest listed expiry.
   const nearestRow = (years: number | undefined) => years == null || !denseGrid?.tenors.length ? -1
     : denseGrid.tenors.reduce((best, value, index) => Math.abs(value - years) < Math.abs(denseGrid.tenors[best]! - years) ? index : best, 0);
-  // A one-day front expiry is the noisiest smile on the board; the default
-  // selection is the first expiry at least four weeks out.
-  const defaultExpiry = snapshot?.expiries.find((entry) => entry.years * 365 >= DEFAULT_EXPIRY_MIN_DAYS) ?? snapshot?.expiries[0];
-  const selectedExpiry = snapshot?.expiries.find((entry) => entry.expiration === (expiration ?? defaultExpiry?.expiration)) ?? null;
+  const selectedExpiry = snapshot ? selectSurfaceExpiry(snapshot, expiration) : null;
   const openChain = useCallback(() => {
     if (!snapshot) return;
-    const selected = expiration ?? selectedExpiry?.expiration;
+    const selected = pinned ?? selectedExpiry?.expiration;
     createPaneFromTemplate("options-pane", { symbol: symbol ?? snapshot.symbol, ticker, instrument: target?.instrument,
       ...(ticker ? { listing: { name: ticker.metadata.name, exchange: ticker.metadata.exchange,
         currency: ticker.metadata.currency, type: ticker.metadata.assetCategory ?? "STK" } } : {}),
       values: selected == null ? {} : { expiration: String(selected) },
     });
-  }, [createPaneFromTemplate, expiration, selectedExpiry?.expiration, snapshot?.symbol, symbol, ticker, target?.instrument]);
+  }, [createPaneFromTemplate, pinned, selectedExpiry?.expiration, snapshot?.symbol, symbol, ticker, target?.instrument]);
   useVolSurfaceEvidence({ snapshot, view: activeTab, grid: activeTab === "surface" && bitmapAvailable ? denseGrid : grid,
     selectedExpiry, loading: active.loading, bitmapAvailable, axis: activeTab === "surface" && bitmapAvailable ? (deltaSurface ? "delta" : "forward") : axis,
     tenors: activeTab === "surface" && bitmapAvailable ? "listed" : tenors, overlaySmiles });
@@ -323,8 +323,9 @@ export function VolSurfacePane({ focused, width, height }: PaneProps) {
     ...(!spotAvailable && symbol && !historyDate ? ["Underlying price unavailable or stale"] : []),
     ...(historyDate && !stored.loading && !stored.data && !stored.error ? [`No stored ${underlying} surface for ${historyDate}`] : []),
     ...(fallbackDate ? [`Live chain has no two-sided quotes; showing the ${fallbackDate} close`] : []),
-    ...(expiration != null && snapshot && !resource.loading && !snapshot.catalogue.includes(expiration)
-      ? [`${expiryLabel(expiration)}: selected expiration unavailable`] : []),
+    ...(pinned != null && snapshot && !resource.loading && !snapshot.catalogue.includes(pinned)
+      && !snapshot.failures.some((failure) => failure.expiration === pinned)
+      ? [`${expiryLabel(pinned)}: ${unlistedExpiryText(pinned, snapshot.catalogue)}`] : []),
     ...(active.error ? [active.error] : [])];
   // What the quotes are and when they were observed; a reload moves the time.
   const freshness = !snapshot ? null : snapshot.stored ? `stored close ${snapshot.stored.sessionDate}`
@@ -429,7 +430,7 @@ export function VolSurfacePane({ focused, width, height }: PaneProps) {
       error={!snapshot ? active.error : null} empty={!snapshot && !active.loading} subject="volatility surface">
       <QueryBar width={width}
         filters={[
-          { id: "expiry", label: "Expiry", value: String(expiration ?? selectedExpiry?.expiration ?? ""),
+          { id: "expiry", label: "Expiry", value: String(pinned ?? selectedExpiry?.expiration ?? ""),
             options: snapshot?.catalogue.map((value) => ({ value: String(value), label: expiryLabel(value) })) ?? [],
             onChange: (value: string) => setExpiration(Number(value)) },
           ...(storedDates.length ? [{ id: "date", label: "Date", value: shownDate ?? "", defaultValue: "",
@@ -468,25 +469,35 @@ function ExpiryTable({ snapshot, selected, onSelect, forwards, width, height, fo
   forwards: boolean; width: number; height: number; focused: boolean;
   onKey: (event: DataTableKeyEvent) => boolean; metadata: () => unknown[][];
 }) {
-  const fields = forwards ? ["Forward", "Basis", "Div %", "Rate %", "Pairs", "As of"] : ["25d put", "25d call", "RR pts", "BF pts", "90/110 pts", "Slope/yr"];
+  // IVs in percent, IV differences in vol points; a missing 25-delta figure says why.
+  const fields = forwards ? ["Forward", "Basis", "Div %", "Rate %", "Pairs", "As of"] : ["25d put %", "25d call %", "RR pts", "BF pts", "90/110 pts", "Slope pts/yr"];
   const integerColumn = forwards ? "4" : null;
   const [sort, setSort] = useState<{ columnId: string; direction: SortDirection }>({ columnId: "expiry", direction: "asc" });
-  const value = (entry: SurfaceExpiry, id: string): number | string | null => id === "expiry" ? entry.expiration
-    : forwards ? [entry.forward, entry.forward == null ? null : entry.forward - snapshot.spot,
-      entry.dividendYield == null || entry.years * 365 < DIVIDEND_YIELD_MIN_DAYS ? null : entry.dividendYield * 100,
-      entry.rate == null ? null : entry.rate * 100, snapshot.stored ? null : entry.parity.pairs.length, entry.asOf?.slice(0, 10) ?? null][Number(id)] ?? null
-      : [entry.skew.put25, entry.skew.call25, entry.skew.riskReversal, entry.skew.butterfly, entry.skew.moneynessSkew, entry.termSlope][Number(id)] ?? null;
+  const rowsByExpiry = useMemo(() => new Map(snapshot.expiries.map((entry) => [entry.expiration,
+    { skew: surfaceSkewRow(entry), forward: surfaceForwardRow(entry, snapshot) }])), [snapshot]);
+  const value = (entry: SurfaceExpiry, id: string): number | string | null => {
+    if (id === "expiry") return entry.expiration;
+    const { skew, forward } = rowsByExpiry.get(entry.expiration)!;
+    return (forwards ? [forward.forward, forward.basis, forward.dividendYield == null ? null : forward.dividendYield * 100,
+      forward.rate == null ? null : forward.rate * 100, forward.pairs, entry.asOf?.slice(0, 10) ?? null]
+      : [skew.put25, skew.call25, skew.riskReversal, skew.butterfly, skew.moneynessSkew, skew.termSlope])[Number(id)] ?? null;
+  };
+  const missing = (entry: SurfaceExpiry, id: string) => {
+    const { skew, forward } = rowsByExpiry.get(entry.expiration)!;
+    if (forwards) return id === "2" && forward.dividendYieldHidden ? HIDDEN_YIELD_TEXT : "--";
+    return (id === "2" || id === "3" ? skew.gap : id === "4" ? skew.moneynessGap : id === "5" && skew.termSlopeHidden ? HIDDEN_SLOPE_TEXT : null) ?? "--";
+  };
   const rows = [...snapshot.expiries].sort((a, b) => {
     const x = value(a, sort.columnId), y = value(b, sort.columnId);
     const difference = typeof x === "number" && typeof y === "number" ? x - y : String(x ?? "").localeCompare(String(y ?? ""));
     return sort.direction === "asc" ? difference : -difference;
   });
   return <DataTableView<SurfaceExpiry> focused={focused} rootWidth={width} rootHeight={height} items={rows}
-    columns={[{ id: "expiry", label: "Expiry", width: 13, align: "left" }, ...fields.map((label, i) => ({ id: String(i), label, width: 13, align: "right" as const }))]}
+    columns={[{ id: "expiry", label: "Expiry", width: 13, align: "left" }, ...fields.map((label, i) => ({ id: String(i), label, width: 14, align: "right" as const }))]}
     getItemKey={(entry) => String(entry.expiration)} selection={{ kind: "id", selectedId: String(selected?.expiration), getId: (entry) => String(entry.expiration), onChange: (_id, entry) => onSelect(entry) }}
     onActivate={onSelect} onRootKeyDown={onKey} getExportMetadata={metadata} freezeFirstColumn
     sortColumnId={sort.columnId} sortDirection={sort.direction} onHeaderClick={(id) => setSort((current) => nextHeaderSort(current, id))}
     renderCell={(entry, column) => { const raw = value(entry, column.id); return { text: column.id === "expiry" ? expiryLabel(entry.expiration)
-      : raw == null ? "--" : typeof raw === "string" ? raw : column.id === integerColumn ? String(raw)
-        : forwards ? (column.id === "1" && raw > 0 ? `+${formatPrice(raw)}` : formatPrice(raw)) : `${(raw * 100).toFixed(2)}` }; }} emptyStateTitle="No expiry observations." />;
+      : raw == null ? missing(entry, column.id) : typeof raw === "string" ? raw : column.id === integerColumn ? String(raw)
+        : forwards ? (column.id === "1" && raw > 0 ? `+${formatPrice(raw)}` : formatPrice(raw)) : formatVolPoints(raw) }; }} emptyStateTitle="No expiry observations." />;
 }

package/src/plugins/builtin/vol-surface/tables.ts

@@ -0,0 +1,124 @@
+import { findListedExpiry } from "../../../utils/option-expiry";
+import { evaluateSurfaceSmile, type SurfaceExpiry, type SurfaceSnapshot } from "./model";
+
+export const formatIv = (value: number | null | undefined) => value == null || !Number.isFinite(value) ? "--" : `${(value * 100).toFixed(2)}%`;
+export const formatPrice = (value: number | null | undefined) => value == null || !Number.isFinite(value) ? "--" : value.toFixed(2);
+export const expiryLabel = (expiration: number) => new Date(expiration * 1000).toISOString().slice(0, 10);
+
+/** A one-day front expiry is the noisiest smile on the board; the default selection is the first at least four weeks out. */
+const DEFAULT_EXPIRY_MIN_DAYS = 28;
+/** Annualising a few days of parity carry produces meaningless yields. */
+const DIVIDEND_YIELD_MIN_DAYS = 30;
+/**
+ * Below this many days to expiry, the ATM term slope to the next expiry
+ * annualises a few hours of IV change into hundreds of points a year.
+ */
+export const TERM_SLOPE_MIN_DAYS = 7;
+/** What the Skew view prints in place of a slope it leaves out. */
+export const HIDDEN_SLOPE_TEXT = `under ${TERM_SLOPE_MIN_DAYS}d`;
+/** What the Forwards view prints in place of a dividend yield it leaves out. */
+export const HIDDEN_YIELD_TEXT = `under ${DIVIDEND_YIELD_MIN_DAYS}d`;
+/** A decimal IV difference in vol points, as the Skew view prints it. */
+export const formatVolPoints = (value: number | null | undefined) =>
+  value == null || !Number.isFinite(value) ? "--" : (value * 100).toFixed(2);
+
+/** Calendar days to the expiry's close, as the model prices it. */
+const expiryDays = (expiry: Pick<SurfaceExpiry, "years">) => expiry.years * 365;
+
+/**
+ * The expiry the smile, chain and pricer actions use: the requested one,
+ * matched by calendar date as OMON matches it, else the first at least four
+ * weeks out. A requested expiry that is not loaded selects nothing.
+ */
+export function selectSurfaceExpiry(snapshot: Pick<SurfaceSnapshot, "expiries">, requested: number | null | undefined): SurfaceExpiry | null {
+  if (requested != null) {
+    const listed = findListedExpiry(requested, snapshot.expiries.map((entry) => entry.expiration));
+    return snapshot.expiries.find((entry) => entry.expiration === listed) ?? null;
+  }
+  return snapshot.expiries.find((entry) => expiryDays(entry) >= DEFAULT_EXPIRY_MIN_DAYS) ?? snapshot.expiries[0] ?? null;
+}
+
+/**
+ * Why an expiry has no 25-delta risk reversal or butterfly: no fitted smile,
+ * or clean quotes that stop short of a 25-delta strike (the fit is never
+ * extrapolated past them). Null when both are there, or while it loads.
+ */
+export function skewGap(expiry: SurfaceExpiry): string | null {
+  const { put25, call25, riskReversal, butterfly } = expiry.skew;
+  if (riskReversal != null && butterfly != null) return null;
+  if (!expiry.fit) return expiry.state === "loading" ? null : "no smile fit";
+  if (put25 == null && call25 == null) return "no 25D quotes";
+  if (put25 == null) return "no 25D put";
+  if (call25 == null) return "no 25D call";
+  return "no ATM IV";
+}
+
+export interface SurfaceSkewRow {
+  expiration: number;
+  days: number;
+  /** Decimal IVs at the 25-delta put and call. */
+  put25: number | null;
+  call25: number | null;
+  /** Decimal IV differences: call minus put, wing average minus ATM, 90% of spot minus 110%. */
+  riskReversal: number | null;
+  butterfly: number | null;
+  moneynessSkew: number | null;
+  /** Decimal ATM IV change per year to the next expiry; null under TERM_SLOPE_MIN_DAYS, which `termSlopeHidden` marks. */
+  termSlope: number | null;
+  termSlopeHidden: boolean;
+  /** Why the risk reversal and butterfly are missing. */
+  gap: string | null;
+  /** Why the 90/110 figure is missing. */
+  moneynessGap: string | null;
+}
+
+export function surfaceSkewRow(expiry: SurfaceExpiry): SurfaceSkewRow {
+  const days = expiryDays(expiry);
+  const termSlopeHidden = expiry.termSlope != null && days < TERM_SLOPE_MIN_DAYS;
+  return { expiration: expiry.expiration, days, put25: expiry.skew.put25, call25: expiry.skew.call25,
+    riskReversal: expiry.skew.riskReversal, butterfly: expiry.skew.butterfly, moneynessSkew: expiry.skew.moneynessSkew,
+    termSlope: termSlopeHidden ? null : expiry.termSlope, termSlopeHidden, gap: skewGap(expiry),
+    // 90% and 110% of spot lie past the clean quotes of a near expiry.
+    moneynessGap: expiry.skew.moneynessSkew != null ? null : !expiry.fit ? skewGap(expiry) : "not quoted" };
+}
+
+export interface SurfaceForwardRow {
+  expiration: number;
+  forward: number | null;
+  /** Forward minus spot, in price. */
+  basis: number | null;
+  /** Decimal implied dividend yield; null under 30 days out, which `dividendYieldHidden` marks. */
+  dividendYield: number | null;
+  dividendYieldHidden: boolean;
+  rate: number | null;
+  /** Put-call pairs behind the forward; a stored close keeps the forward, not its pairs. */
+  pairs: number | null;
+}
+
+export function surfaceForwardRow(expiry: SurfaceExpiry, snapshot: SurfaceSnapshot & { stored?: unknown }): SurfaceForwardRow {
+  const dividendYieldHidden = expiry.dividendYield != null && expiryDays(expiry) < DIVIDEND_YIELD_MIN_DAYS;
+  return { expiration: expiry.expiration, forward: expiry.forward, basis: expiry.forward == null ? null : expiry.forward - snapshot.spot,
+    dividendYield: dividendYieldHidden ? null : expiry.dividendYield, dividendYieldHidden,
+    rate: expiry.rate, pairs: snapshot.stored ? null : expiry.parity.pairs.length };
+}
+
+/** When and how an expiry's quotes were observed, as a report reads its freshness from each row. */
+export const expiryFeedFields = (expiry: SurfaceExpiry) => ({
+  asOf: expiry.asOf, dataSource: expiry.dataSource, delayMinutes: expiry.delayMinutes, stale: expiry.stale,
+});
+
+/** The Term view's points: ATM at spot and the 25-delta wings, with the expiry's straddle and one-sigma move. */
+export function surfaceTermRows(snapshot: SurfaceSnapshot) {
+  return snapshot.expiries.filter((expiry) => expiry.atmIV != null).sort((a, b) => a.years - b.years).map((expiry) => ({
+    expiration: expiry.expiration, days: expiryDays(expiry), atm: expiry.atmIV, put25: expiry.skew.put25, call25: expiry.skew.call25,
+    straddle: expiry.expectedMove.straddle, sigma: expiry.expectedMove.sigma, sigmaPercent: expiry.expectedMove.sigmaPercent,
+    ...expiryFeedFields(expiry),
+  }));
+}
+
+/** The Smile view's clean quotes against the fitted smile, in strike order. */
+export function surfaceSmileRows(expiry: SurfaceExpiry) {
+  return expiry.points.map((point) => ({ strike: point.strike, side: point.side, moneyness: point.moneyness,
+    volatility: point.volatility, fitted: evaluateSurfaceSmile(expiry, point.strike), residual: point.fitResidual,
+    mid: point.mid, openInterest: point.openInterest }));
+}