gloomberb 0.18.1 → 0.18.3

package/src/plugins/builtin/equity-screener/headless.ts

@@ -1,10 +1,12 @@
 import type { HeadlessPaneDefinition } from "../../../types/plugin";
 import type { HeadlessPaneColumn, HeadlessPaneContext } from "../../../types/headless";
 import {
+  KPI_FIELDS,
   NUMERIC_FIELDS,
   type NumericField,
   type ScreenRow,
 } from "../../../api-client/equity-screener";
+import { KPI_COVERAGE_NOTE } from "../company-kpis/model";
 import { EXTENDED_SESSION_LABELS, type ExtendedSession } from "../../../market-data/market/status";
 import { buildQuoteKey } from "../../../market-data/selectors";
 import type { Quote } from "../../../types/financials";
@@ -17,8 +19,12 @@ import {
   formatScreenValue,
   metricDate,
   parseScreenDefinition,
+  screenColumnLabel,
   screenDefinitionSyntax,
-  SHORT_LABELS,
+  screenCurrencyEmpty,
+  screenLabel,
+  screenYtdBase,
+  withheldMetricNote,
 } from "./model";
 import type { ScreenDefinition } from "../../../api-client/equity-screener";
 
@@ -128,15 +134,33 @@ export const equityScreenerHeadless: HeadlessPaneDefinition<"bundle"> = {
     // A sort on one of them is redone on those figures.
     const rows = sortLiveScreenRows(overlayScreenQuotes(data.rows, await loadRowQuotes(data.rows, ctx)), data.definition.sort);
     const extendedSessions = screenExtendedSessions(rows);
+    // A Pro metric the server held back from Free says so once, as KPIS says it; a KPI
+    // with gaps says what a gap is, as KPIS does.
+    const withheld = rows.some((row) => row.metrics[metric].access === "pro");
+    const errors = withheld ? [...data.warnings, withheldMetricNote(metric)] : data.warnings;
+    const missing = rows.filter((row) => row.metrics[metric].value === null).length;
+    const kpiGaps = !withheld && missing > 0 && (KPI_FIELDS as readonly string[]).includes(metric)
+      ? [`${missing} of ${rows.length} ${rows.length === 1 ? "row has" : "rows have"} no ${screenLabel(metric)}. ${KPI_COVERAGE_NOTE}`]
+      : [];
+    // A CAD screen of listings quoted in USD is empty for its currency, not for want of companies: say so, and give the screen in USD.
+    const currencyEmpty = rows.length === 0 ? screenCurrencyEmpty(data.definition, data.universe) : null;
+    const empty = currencyEmpty
+      ? [
+        `${currencyEmpty.title} ${currencyEmpty.detail}`,
+        `In the base currency, ${currencyEmpty.base.currency}: gloomberb fn EQS --definition '${spacedJson(currencyEmpty.base)}'${metric === "marketCap" ? "" : ` --metric ${metric}`}`,
+      ].join("\n")
+      : null;
     // Payload status also counts ordinary per-field sparsity; only generation
     // warnings are failures, and more pages are not an error.
     return {
       freshness: { asOf: data.snapshot?.sourceNewestAt ?? null },
-      complete: !data.nextCursor && data.warnings.length === 0,
-      errors: data.warnings,
+      complete: !data.nextCursor && errors.length === 0,
+      errors,
+      ...(kpiGaps.length ? { notes: kpiGaps } : {}),
       sections: [
         {
           title: "Matching equities",
+          ...(empty ? { empty } : {}),
           columns: [
             { key: "symbol", header: "Symbol" },
             { key: "exchange", header: "Exchange" },
@@ -145,7 +169,8 @@ export const equityScreenerHeadless: HeadlessPaneDefinition<"bundle"> = {
             ...(metric === "price" ? [] : [{ key: "price", header: "Last", align: "right" as const, format: price }]),
             ...(metric === "changePercent" ? [] : [{ key: "changePercent", header: "Chg%", align: "right" as const, format: percent }]),
             ...extendedSessions.map(extendedColumn),
-            { key: "value", header: SHORT_LABELS[metric], align: "right" },
+            // YTD names the close it is measured from: `YTD% vs 31 Dec close`.
+            { key: "value", header: screenColumnLabel(metric, screenYtdBase(data.rows, data.snapshot?.assembledAt), "report"), align: "right" },
             { key: "unit", header: "Unit" },
             { key: "percentile", header: "Covered pctl", align: "right" },
             { key: "asOf", header: "As of" },
@@ -172,7 +197,7 @@ export const equityScreenerHeadless: HeadlessPaneDefinition<"bundle"> = {
                   ? null
                   : Math.round(observation.percentile.value),
               asOf: stamp.collected ? `${stamp.text} (collected)` : stamp.text,
-              state: observation.state,
+              state: observation.access === "pro" ? "locked" : observation.state,
             };
           }),
         },

package/src/plugins/builtin/equity-screener/model.ts

@@ -17,9 +17,11 @@ import {
   type ScreenPayload,
   type ScreenRow,
 } from "../../../api-client/equity-screener";
+import { yearToDateBaseLabel } from "../../../market-data/market/year-to-date";
 import { canonicalExchange } from "../../../utils/exchanges";
 import { LATEST_DISTRIBUTION, TRAILING_DIVIDEND_BASIS } from "../../../utils/forward-dividend";
 import { formatCompact, formatNumber } from "../../../utils/format";
+import { kpiFreeLimitNote } from "../company-kpis/model";
 
 /**
  * Column headers. Currency sits in the footer; percentage fields carry %.
@@ -160,8 +162,29 @@ export function resultFields(definition: ScreenDefinition, metric: NumericField)
   return [...new Set(fields)].filter((field) => definition.currency || !MONETARY.has(field) || field === metric);
 }
 
+/**
+ * The close the screen's YTD returns are measured from, `31 Dec`: NYSE's last
+ * session of the year before the newest session a row's YTD ends on, the
+ * snapshot's day without one.
+ */
+export function screenYtdBase(rows: readonly ScreenRow[], assembledAt?: string | null, now = Date.now()): string | null {
+  const day = rows.map((row) => row.metrics.returnYtdPercent?.asOf?.slice(0, 10) ?? "").filter(Boolean).sort().at(-1)
+    ?? assembledAt?.slice(0, 10);
+  return day ? yearToDateBaseLabel(day, "NYSE", now) : null;
+}
+
+/**
+ * A column's header. YTD names the close it is measured from: `YTD% vs 31 Dec
+ * close` in a report, `YTD% vs 31 Dec` in the pane and `YTD% 31 Dec` where
+ * the pane is short of room.
+ */
+export function screenColumnLabel(field: NumericField, ytdBase: string | null, form: "report" | "pane" | "compact" = "pane"): string {
+  if (field !== "returnYtdPercent" || !ytdBase) return SHORT_LABELS[field];
+  return form === "compact" ? `YTD% ${ytdBase}` : `YTD% vs ${ytdBase}${form === "report" ? " close" : ""}`;
+}
+
 /** Prices get room for a separated six-figure quote (757,398.00). */
-export const columnWidth = (field: NumericField) => Math.max(field === "price" ? 10 : 8, SHORT_LABELS[field].length);
+export const columnWidth = (field: NumericField, label = SHORT_LABELS[field]) => Math.max(field === "price" ? 10 : 8, label.length);
 
 export const DEFAULT_SCREEN: ScreenDefinition = {
   version: 1,
@@ -169,6 +192,34 @@ export const DEFAULT_SCREEN: ScreenDefinition = {
   criteria: [{ field: "marketCap", op: "gte", value: 10_000_000_000 }],
   sort: { field: "marketCap", direction: "desc" },
 };
+
+/**
+ * Why a screen with a currency found nothing, when the currency may be why:
+ * `currency` keeps the listings quoted in it and converts nothing, so a CAD
+ * screen of listings quoted in USD reads as no company at all. `title` says
+ * which listings it kept, `detail` that it converts nothing and what the
+ * covered listings are quoted in, and `base` is the same screen in the base
+ * currency the default screen uses (USD), to run instead. Null for a screen
+ * in that currency or with none.
+ */
+export function screenCurrencyEmpty(
+  definition: ScreenDefinition,
+  universe: Pick<ScreenPayload["universe"], "covered" | "currencies">,
+): { title: string; detail: string; base: ScreenDefinition } | null {
+  const currency = definition.currency;
+  const baseCurrency = DEFAULT_SCREEN.currency!;
+  if (!currency || currency === baseCurrency) return null;
+  const quoted = universe.currencies.filter(Boolean);
+  const none = quoted.length > 0 && !quoted.includes(currency);
+  return {
+    title: none
+      ? `None of the ${universe.covered.toLocaleString("en-US")} covered listings is quoted in ${currency}.`
+      : `No listing quoted in ${currency} matches.`,
+    detail: `Currency ${currency} keeps only the listings quoted in ${currency} and converts nothing${none ? `; the covered listings are quoted in ${quoted.join(", ")}` : ""}.`,
+    base: { ...definition, currency: baseCurrency },
+  };
+}
+
 export const screenRowId = (row: Pick<ScreenRow, "symbol" | "exchange">) =>
   `${canonicalExchange(row.exchange)}:${row.symbol}`;
 export const screenLabel = (field: string) =>
@@ -481,6 +532,20 @@ const unavailableMetric = (): ScreenMetric => ({
   state: "unavailable", scope: "reported", reason: "Not provided by this server", sourceUrl: null,
   percentile: { value: null, sampleCount: 0, scope: "covered-universe" },
 });
+/** Company KPIs, guidance, hiring and app attention: the server leaves them out of a screen for a caller without Gloom Pro. */
+const PRO_FIELDS: ReadonlySet<string> = new Set([...KPI_FIELDS, ...HIRING_APP_FIELDS]);
+const withheldMetric = (): ScreenMetric => ({ ...unavailableMetric(), reason: "Needs Gloom Pro", access: "pro" });
+
+/**
+ * What a screen says once of a metric the server held back from Free, a
+ * KPI's in the words `fn KPIS` uses ("The free screener shows no KPI values;
+ * Gloom Pro shows each company's Backlog.").
+ */
+export function withheldMetricNote(field: NumericField): string {
+  return (KPI_FIELDS as readonly string[]).includes(field)
+    ? kpiFreeLimitNote({ metric: screenLabel(field), shown: 0, total: null, guidance: field.startsWith("guide"), where: "The free screener" })
+    : `${screenLabel(field)} needs Gloom Pro.`;
+}
 export function validateScreenPayload(value: unknown): ScreenPayload {
   const data = value as ScreenPayload;
   if (
@@ -523,8 +588,9 @@ export function validateScreenPayload(value: unknown): ScreenPayload {
     ids.add(screenRowId(row));
     for (const field of NUMERIC_FIELDS) {
       // A server from before social, research, volatility or dividend fields omits them; they read as unavailable.
+      // A Pro field it left out was held back from this caller.
       if (!row.metrics[field] && ([...SOCIAL_FIELDS, ...RESEARCH_FIELDS, ...VOLATILITY_FIELDS, ...ATTENTION_FIELDS, ...HIRING_APP_FIELDS, ...KPI_FIELDS, ...DIVIDEND_FIELDS] as readonly string[]).includes(field))
-        row.metrics[field] = unavailableMetric();
+        row.metrics[field] = PRO_FIELDS.has(field) ? withheldMetric() : unavailableMetric();
       const metric = row.metrics[field];
       if (
         !metric ||

package/src/plugins/builtin/equity-screener/pane.tsx

@@ -67,10 +67,12 @@ import {
   metricDate,
   parseScreenDefinition,
   resultFields,
-  SHORT_LABELS,
   SIGN_COLORED,
+  screenColumnLabel,
+  screenCurrencyEmpty,
   screenLabel,
   screenRowId,
+  screenYtdBase,
 } from "./model";
 import { useScreenResults } from "./results";
 import { overlayLiveScreenRows, screenExtendedMove, screenExtendedSessions, sortLiveScreenRows, type LiveScreenRow } from "./live";
@@ -101,20 +103,19 @@ const EXTENDED_COLUMN_PREFIX = "ext:";
  * CHG% for each session in `extendedSessions`, and is added only whole, as
  * the metrics are.
  */
-function resultColumns(
+export function resultColumns(
   width: number,
   definition: ScreenDefinition,
   metric: NumericField,
   asOf: boolean,
   extendedSessions: readonly ExtendedSession[] = [],
+  ytdBase: string | null = null,
 ): DataTableColumn[] {
   const [focus, ...others] = resultFields(definition, metric);
-  const metricColumn = (field: NumericField): DataTableColumn => ({
-    id: `m:${field}`,
-    label: SHORT_LABELS[field],
-    width: columnWidth(field),
-    align: "right",
-  });
+  const metricColumn = (field: NumericField, form: "pane" | "compact"): DataTableColumn => {
+    const label = screenColumnLabel(field, ytdBase, form);
+    return { id: `m:${field}`, label, width: columnWidth(field, label), align: "right" };
+  };
   const extendedColumns = extendedSessions.map((session): DataTableColumn => ({
     id: `${EXTENDED_COLUMN_PREFIX}${session}`,
     label: extendedSessionStateLabel(session),
@@ -122,20 +123,21 @@ function resultColumns(
     align: "right",
   }));
   // The extended move reads beside CHG%, or first after the focus metric when that is CHG%.
-  const extras = [
+  const extras = (form: "pane" | "compact") => [
     ...(focus === "changePercent" ? extendedColumns : []),
-    ...others.flatMap((field) => field === "changePercent" ? [metricColumn(field), ...extendedColumns] : [metricColumn(field)]),
+    ...others.flatMap((field) => field === "changePercent" ? [metricColumn(field, form), ...extendedColumns] : [metricColumn(field, form)]),
   ];
   const build = (
     extra: DataTableColumn[],
     exchange: boolean,
     sector: boolean,
+    form: "pane" | "compact",
   ): DataTableColumn[] => [
     { id: "symbol", label: "SYMBOL", width: 8, align: "left" },
     { id: "name", label: "NAME", width: 18, flexGrow: 1, align: "left" },
     ...(exchange ? [{ id: "exchange", label: "EXCH", width: 7, align: "left" as const }] : []),
     ...(sector ? [{ id: "sector", label: "SECTOR", width: 22, align: "left" as const }] : []),
-    metricColumn(focus!),
+    metricColumn(focus!, form),
     { id: "percentile", label: "PCTL", width: 4, align: "right" },
     ...(asOf ? [{ id: "date", label: "AS OF", width: 10, align: "left" as const }] : []),
     ...extra,
@@ -143,15 +145,15 @@ function resultColumns(
   // Measured the way the table draws them (header floor, gaps, lead gaps), so a
   // column is only added when it fits whole.
   const fits = (columns: DataTableColumn[]) => getTableWidth(columns) <= width;
-  let shown: DataTableColumn[] = [];
-  for (const column of extras) {
-    const next = [...shown, column];
-    if (!fits(build(next, false, false))) break;
-    shown = next;
-  }
-  const exchange = fits(build(shown, true, false));
-  const sector = exchange && fits(build(shown, true, true));
-  return build(shown, exchange, sector);
+  // Columns are chosen with YTD's short header (`YTD% 31 Dec`), which reads
+  // `YTD% vs 31 Dec` when that still fits: naming the close never costs a column.
+  const compact = extras("compact");
+  let shown = 0;
+  while (shown < compact.length && fits(build(compact.slice(0, shown + 1), false, false, "compact"))) shown++;
+  const exchange = fits(build(compact.slice(0, shown), true, false, "compact"));
+  const sector = exchange && fits(build(compact.slice(0, shown), true, true, "compact"));
+  const named = build(extras("pane").slice(0, shown), exchange, sector, "pane");
+  return fits(named) ? named : build(compact.slice(0, shown), exchange, sector, "compact");
 }
 const loadFields = () => fetchScreenFields();
 function ScreenDetail({
@@ -351,7 +353,11 @@ function EquityScreenView({
   const staleFocus = snapshotRows.some((row) => row.metrics[metric]?.state === "stale");
   // A pre-market, after-hours or overnight column only while a row has such a print.
   const extendedSessions = screenExtendedSessions(rows);
-  const columns = resultColumns(width, definition, metric, staleFocus, extendedSessions);
+  // YTD names the close it is measured from, `31 Dec`.
+  const ytdBase = screenYtdBase(snapshotRows, data?.snapshot?.assembledAt);
+  // A screen its currency emptied says so, not that no company matches.
+  const currencyEmpty = data && data.rows.length === 0 ? screenCurrencyEmpty(data.definition, data.universe) : null;
+  const columns = resultColumns(width, definition, metric, staleFocus, extendedSessions, ytdBase);
   const apply = (next: ScreenDefinition) => {
     try {
       setDefinition(parseScreenDefinition(next));
@@ -886,11 +892,8 @@ function EquityScreenView({
         </PaneStatusBody>
       )
     ) : (
-      <PaneStatusBody
-        loading={results.loading && !data}
-        error={!data ? results.error : null}
-        subject="equity screen"
-      >
+      // The metric stays above the results while a new sort loads.
+      <>
         {!opened ? (
           <QueryBar
             width={width}
@@ -915,101 +918,108 @@ function EquityScreenView({
             }]}
           />
         ) : null}
-        <DataTableStackView
-          columns={columns}
-          items={rows}
-          focused={focused && !saveForm}
-          rootWidth={width}
-          rootHeight={bodyHeight - 1}
-          scrollRef={tableScroll}
-          onBodyScrollActivity={loadMore}
-          resetScrollKey={JSON.stringify(definition)}
-          visibleRangeKey={JSON.stringify(definition)}
-          onVisibleRangeChange={setVisibleRange}
-          getItemKey={screenRowId}
-          selection={{
-            kind: "id",
-            selectedId: selectedId ?? (rows[0] ? screenRowId(rows[0]) : null),
-            getId: screenRowId,
-            onChange: setSelectedId,
-          }}
-          onActivate={(row) => setOpenId(screenRowId(row))}
-          detailOpen={!!opened}
-          onBack={() => setOpenId(null)}
-          detailTitle={opened?.name ?? opened?.symbol}
-          detailContent={
-            opened ? (
-              <ScreenDetail
-                row={opened}
-                width={width}
-                height={bodyHeight - 2}
-              />
-            ) : null
-          }
-          renderCell={(row, column) => {
-            if (column.id.startsWith(EXTENDED_COLUMN_PREFIX)) {
-              // The extended print's move from the close in PRICE and CHG%.
-              const move = screenExtendedMove(row, column.id.slice(EXTENDED_COLUMN_PREFIX.length) as ExtendedSession);
-              return move == null
-                ? { text: "--", color: colors.textDim }
-                : { text: formatPercentRaw(move), color: priceColor(move, colors) };
+        <PaneStatusBody
+          loading={results.loading && !data}
+          error={!data ? results.error : null}
+          subject="equity screen"
+        >
+          <DataTableStackView
+            columns={columns}
+            items={rows}
+            focused={focused && !saveForm}
+            rootWidth={width}
+            rootHeight={bodyHeight - 1}
+            scrollRef={tableScroll}
+            onBodyScrollActivity={loadMore}
+            resetScrollKey={JSON.stringify(definition)}
+            visibleRangeKey={JSON.stringify(definition)}
+            onVisibleRangeChange={setVisibleRange}
+            getItemKey={screenRowId}
+            selection={{
+              kind: "id",
+              selectedId: selectedId ?? (rows[0] ? screenRowId(rows[0]) : null),
+              getId: screenRowId,
+              onChange: setSelectedId,
+            }}
+            onActivate={(row) => setOpenId(screenRowId(row))}
+            detailOpen={!!opened}
+            onBack={() => setOpenId(null)}
+            detailTitle={opened?.name ?? opened?.symbol}
+            detailContent={
+              opened ? (
+                <ScreenDetail
+                  row={opened}
+                  width={width}
+                  height={bodyHeight - 2}
+                />
+              ) : null
             }
-            const field = column.id.startsWith("m:")
-              ? (column.id.slice(2) as NumericField)
-              : null;
-            if (field) {
-              const observation = row.metrics[field];
-              const change = SIGN_COLORED.has(field) && observation.value != null
-                // A move that prints 0.0 stays neutral.
-                ? priceColor(Math.abs(observation.value) < 0.05 ? 0 : observation.value, colors)
-                : undefined;
-              return {
-                text: formatScreenValue(field, observation.value),
-                color: observation.state === "stale" ? colors.warning : change,
-              };
+            renderCell={(row, column) => {
+              if (column.id.startsWith(EXTENDED_COLUMN_PREFIX)) {
+                // The extended print's move from the close in PRICE and CHG%.
+                const move = screenExtendedMove(row, column.id.slice(EXTENDED_COLUMN_PREFIX.length) as ExtendedSession);
+                return move == null
+                  ? { text: "--", color: colors.textDim }
+                  : { text: formatPercentRaw(move), color: priceColor(move, colors) };
+              }
+              const field = column.id.startsWith("m:")
+                ? (column.id.slice(2) as NumericField)
+                : null;
+              if (field) {
+                const observation = row.metrics[field];
+                const change = SIGN_COLORED.has(field) && observation.value != null
+                  // A move that prints 0.0 stays neutral.
+                  ? priceColor(Math.abs(observation.value) < 0.05 ? 0 : observation.value, colors)
+                  : undefined;
+                return {
+                  text: formatScreenValue(field, observation.value),
+                  color: observation.state === "stale" ? colors.warning : change,
+                };
+              }
+              const focus = row.metrics[metric];
+              if (column.id === "percentile")
+                return { text: rank(focus.percentile.value) };
+              if (column.id === "date")
+                return focus.state === "stale"
+                  ? { text: metricDate(focus).text, color: colors.warning }
+                  : { text: "" };
+              if (column.id === "name") return { text: row.name ?? "--" };
+              return { text: String(row[column.id as "symbol"] ?? "--") };
+            }}
+            sortColumnId={
+              (NUMERIC_FIELDS as readonly string[]).includes(definition.sort.field)
+                ? `m:${definition.sort.field}`
+                : definition.sort.field
             }
-            const focus = row.metrics[metric];
-            if (column.id === "percentile")
-              return { text: rank(focus.percentile.value) };
-            if (column.id === "date")
-              return focus.state === "stale"
-                ? { text: metricDate(focus).text, color: colors.warning }
-                : { text: "" };
-            if (column.id === "name") return { text: row.name ?? "--" };
-            return { text: String(row[column.id as "symbol"] ?? "--") };
-          }}
-          sortColumnId={
-            (NUMERIC_FIELDS as readonly string[]).includes(definition.sort.field)
-              ? `m:${definition.sort.field}`
-              : definition.sort.field
-          }
-          sortDirection={definition.sort.direction}
-          onHeaderClick={(id) => {
-            const field = id.startsWith("m:")
-              ? (id.slice(2) as NumericField)
-              : id === "percentile" || id === "date"
-                ? metric
-                : ["symbol", "sector", "exchange"].includes(id)
-                  ? (id as ScreenField)
-                  : null;
-            if (!field) return;
-            if ((NUMERIC_FIELDS as readonly string[]).includes(field))
-              setMetric(field as NumericField);
-            apply({
-              ...definition,
-              sort: {
-                field,
-                direction:
-                  definition.sort.field === field &&
-                  definition.sort.direction === "desc"
-                    ? "asc"
-                    : "desc",
-              },
-            });
-          }}
-          emptyStateTitle="No equities match this screen."
-        />
-      </PaneStatusBody>
+            sortDirection={definition.sort.direction}
+            onHeaderClick={(id) => {
+              const field = id.startsWith("m:")
+                ? (id.slice(2) as NumericField)
+                : id === "percentile" || id === "date"
+                  ? metric
+                  : ["symbol", "sector", "exchange"].includes(id)
+                    ? (id as ScreenField)
+                    : null;
+              if (!field) return;
+              if ((NUMERIC_FIELDS as readonly string[]).includes(field))
+                setMetric(field as NumericField);
+              apply({
+                ...definition,
+                sort: {
+                  field,
+                  direction:
+                    definition.sort.field === field &&
+                    definition.sort.direction === "desc"
+                      ? "asc"
+                      : "desc",
+                },
+              });
+            }}
+            emptyStateTitle={currencyEmpty?.title ?? "No equities match this screen."}
+            emptyStateHint={currencyEmpty ? `${currencyEmpty.detail} Choose ${currencyEmpty.base.currency} to screen in the base currency.` : undefined}
+          />
+        </PaneStatusBody>
+      </>
     );
   return (
     <Box width={width} height={height} flexDirection="column">

package/src/plugins/builtin/estimate-revisions/headless.ts

@@ -45,10 +45,11 @@ export const estimateRevisionsHeadless: HeadlessPaneDefinition<"bundle"> = {
       instrument?.exchange ?? "",
       ctx.apiClient,
       ctx.marketData,
-    ).catch((error: unknown) => {
-      throw explainRefusal(error, estimateRevisionsLockNote, {
+    ).catch(async (error: unknown) => {
+      throw await explainRefusal(error, estimateRevisionsLockNote, {
         symbol: args.symbols[0] ?? null,
         token: ctx.settings?.tab === "guidance" ? "GUID" : "EM",
+        context: ctx,
       });
     });
     const periods = pinnedEstimatePeriods(

package/src/plugins/builtin/estimate-revisions/lock-note.ts

@@ -1,13 +1,37 @@
 import type { PaneLock } from "../../../types/plugin";
-import { proLockNote } from "../shared/pro-lock-note";
+import { fetchCompanyData } from "../company-kpis/client";
+import { filesForm } from "../shared/free-routes";
+import { resolveHeadlessIssuerListing } from "../shared/headless-market-data";
+import { proLockNote, type FreeRoute } from "../shared/pro-lock-note";
+
+/** GUIDE's free preview, where it holds guidance for the company: Apple issues none, so GUIDE has no AAPL rows. */
+const GUIDE_ROUTE: FreeRoute = {
+  text: (ticker, company) => `gloomberb fn GUIDE ${ticker} lists ${company}'s latest guidance ranges, with the date each was issued.`,
+  answers: async (symbol, context) => {
+    const data = await fetchCompanyData("guidance", symbol, {}, context.apiClient, await resolveHeadlessIssuerListing(context, symbol), context.signal);
+    return "guidance" in data && data.guidance.length + data.history.length > 0;
+  },
+};
+
+/** The company's 8-Ks, where results and any guidance it gives are filed, for a company that files them. */
+const EIGHT_K_ROUTE: FreeRoute = {
+  text: (ticker, company) => `gloomberb filings ${ticker} --form 8-K lists ${company}'s 8-Ks, where it files its results and any guidance, each with its items and a link to the filing.`,
+  answers: (symbol, context) => filesForm(symbol, "8-K", context),
+};
+
+const EARNINGS_ROUTE: FreeRoute = {
+  text: (ticker, company) => `gloomberb earnings ${ticker} lists ${company}'s next report date with its consensus EPS estimate.`,
+  answers: async (symbol, context) => (await context.marketData.getEarningsCalendar?.([symbol]) ?? []).length > 0,
+};
 
 /**
  * EM, EEO and GUID read one Gloom Cloud route that asks for a signed-in account
  * with a verified email, and no plan. The report names the function it was run
- * for. GUIDE lists a company's latest guidance ranges, as a free preview;
- * `earnings` lists the next report date with its consensus EPS estimate.
+ * for. GUIDE lists a company's latest guidance ranges, as a free preview, and
+ * its 8-Ks hold what GUIDE does not cover; `earnings` lists the next report
+ * date with its consensus EPS estimate.
  */
-export function estimateRevisionsLockNote(lock: PaneLock): string {
+export function estimateRevisionsLockNote(lock: PaneLock): Promise<string> {
   const guidance = lock.token === "GUID";
   return proLockNote(lock, {
     token: guidance ? "GUID" : "EM",
@@ -16,8 +40,6 @@ export function estimateRevisionsLockNote(lock: PaneLock): string {
       ? "it reads the EPS guidance a company issued, cited from its filings and calls, against consensus"
       : "it reads consensus EPS estimates by fiscal period, how they were revised, the surprises against reported EPS and the guidance",
     shows: "it",
-    free: guidance
-      ? (ticker, company) => `gloomberb fn GUIDE ${ticker} lists ${company}'s latest guidance ranges, with the date each was issued.`
-      : (ticker, company) => `gloomberb earnings ${ticker} lists ${company}'s next report date with its consensus EPS estimate.`,
+    free: guidance ? [GUIDE_ROUTE, EIGHT_K_ROUTE] : [EARNINGS_ROUTE],
   });
 }

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

@@ -21,7 +21,10 @@ export function validateExposure(value: ExposurePayload): ExposurePayload {
     && typeof data.evaluatedAt === "string" && Number.isFinite(Date.parse(data.evaluatedAt))
     && Number.isInteger(data.requestedHoldings) && Number.isInteger(data.lockedHoldings) && data.lockedHoldings >= 0
     && Array.isArray(data.holdings) && strings(data.unknowns) && strings(data.methodology);
-  try { parseCustomScenario(JSON.stringify(data.scenario)); } catch { valid = false; }
+  try { parseCustomScenario(JSON.stringify(data.scenario)); } catch {
+    // Intentional ignore: invalid scenarios use the payload validation error below.
+    valid = false;
+  }
   valid &&= data.holdings.every(h => typeof h.symbol === "string" && finite(h.weight) && Array.isArray(h.unknowns)
     && ["quantified", "partial", "unknown"].includes(h.status) && !!h.coverage
     && Array.isArray(h.measures) && h.measures.every(m => validRange(m.exposurePct) && nullableRange(m.impactPct) && strings(m.componentIds))

package/src/plugins/builtin/exposure/editor.tsx

@@ -7,13 +7,13 @@ import type { ExposureScenario } from "../../../api-client/exposure";
 import { parseCustomScenario } from "./model";
 
 export interface ExposureInputs { input: string; source: string; nav: string; cash: string; depth: number; scenario: ExposureScenario; }
-export function ExposureEditor({ initial, sources, focused, width, onSave, onCancel }: {
-  initial: ExposureInputs; sources: { value: string; label: string }[]; focused: boolean; width: number;
+export function ExposureEditor({ initial, initialCustom, sources, focused, width, onSave, onCancel }: {
+  initial: ExposureInputs; initialCustom?: string; sources: { value: string; label: string }[]; focused: boolean; width: number;
   onSave: (value: ExposureInputs) => void; onCancel: () => void;
 }) {
   const [draft, setDraft] = useState(initial);
   const first = initial.scenario.shocks[0]!;
-  const [custom, setCustom] = useState(initial.scenario.shocks.length > 1 || !!first.transmission ? JSON.stringify(initial.scenario) : "");
+  const [custom, setCustom] = useState(initialCustom ?? (initial.scenario.shocks.length > 1 || !!first.transmission ? JSON.stringify(initial.scenario) : ""));
   const [label, setLabel] = useState(initial.scenario.label);
   const [kind, setKind] = useState(first.kind);
   const [target, setTarget] = useState(first.target);

package/src/plugins/builtin/exposure/evidence.ts

@@ -26,7 +26,10 @@ export const exposureScreenshotEvidence: PaneScreenshotEvidenceHook<ExposureCapt
       const rows = metadata.tab === "drivers" ? driverRows(payload) : metadata.tab === "paths" ? pathRows(payload) : metadata.tab === "portfolio" ? portfolioRows(payload, String(metadata.view)) : tableRows(payload);
       if (metadata.plottedValueCount !== rows.length || metadata.rowIds.length !== rows.length || metadata.rowIds.some(id => !rows.some(r => r.id === id))) return null;
       return metadata as unknown as ExposureCapture;
-    } catch { return null; }
+    } catch {
+      // Intentional ignore: malformed capture metadata cannot prove the screenshot's exposure data.
+      return null;
+    }
   },
   mismatches(evidence, { resolved, payload }) {
     const snapshot = payload.config.layout.instances.find(i => i.instanceId === payload.paneId)?.settings?.exposureSnapshot;

package/src/plugins/builtin/exposure/holdings.ts

@@ -4,6 +4,7 @@ import type { Portfolio, TickerRecord } from "../../../types/ticker";
 import { publicTickerKey } from "../../../utils/exchanges";
 import { resolveCurrencyUnit } from "../../../utils/currency-units";
 import { convertCurrency } from "../../../utils/format";
+import { logFailure } from "../../../utils/log-failure";
 import { getPortfolioPositionMetrics, getPortfolioQuoteDisplay, resolvePortfolioMarketValue } from "../../../portfolio/position-metrics";
 
 /** Explicit NAV preserves cash, shorts and leverage; net holdings are never used as NAV. */
@@ -35,7 +36,8 @@ export async function portfolioHoldings(portfolio: Portfolio, tickers: TickerRec
   for (const currency of currencies) await ensureRate(currency);
   const holdings: ExposureHolding[] = [];
   for (const ticker of positions) {
-    const quote = await market.getQuote(ticker.metadata.ticker, ticker.metadata.exchange).catch(() => null);
+    const quote = await market.getQuote(ticker.metadata.ticker, ticker.metadata.exchange)
+      .catch(logFailure("exposure.holdings", "Load portfolio holding quote failed", null));
     const currency = quote?.currency || ticker.metadata.currency;
     if (!rates.has(currency)) await ensureRate(currency);
     const metrics = getPortfolioPositionMetrics(ticker, portfolio.id, currency, {