gloomberb 0.18.1 → 0.18.2

package/src/plugins/builtin/econ/print-watch.ts

@@ -0,0 +1,279 @@
+import type { GloomPluginContext } from "../../../types/plugin";
+import {
+  getCalendarCache,
+  landedHighImpactPrints,
+  loadCalendar,
+  pendingHighImpactPrints,
+  PRINT_PENDING_MS,
+  subscribeCalendar,
+  type EconCalendarCacheEntry,
+} from "./calendar-model";
+import type { EconEvent } from "./types";
+
+/** The ECO setting that turns the print toast on. Off until the user turns it on, as breaking news is. */
+export const ECON_PRINT_NOTIFICATIONS_ENABLED_KEY = "econPrintNotificationsEnabled";
+
+const TOAST_DURATION_MS = 20_000;
+/**
+ * The waits between asks while a print is due: short just after the release
+ * time, when most prints land, then longer until the window closes, which
+ * keeps a release to about twenty asks per app instead of eighty.
+ */
+const PRINT_BACKOFF_MS = [15_000, 30_000, 60_000] as const;
+/** Each wait moves by up to a fifth either way, so apps that started together drift apart. */
+const PRINT_JITTER = 0.2;
+/** How often the watch looks at the calendar it already has while nothing is due. */
+const PRINT_IDLE_MS = 60_000;
+/** While idle, a calendar this old is asked for again, so a release added since is known. */
+const CALENDAR_RECHECK_MS = 6 * 60 * 60 * 1000;
+/** With no calendar at all, how long a failed ask waits before the next. */
+const NO_CALENDAR_RETRY_MS = 5 * 60 * 1000;
+
+type CalendarRead = Pick<EconCalendarCacheEntry, "data" | "fetchedAt">;
+
+export interface PrintWatchDeps {
+  now: () => number;
+  /** Asks for the calendar; `force` skips a fresh cache. */
+  load: (force: boolean) => Promise<CalendarRead>;
+  /** The cached calendar, however old, without a request. */
+  read: () => CalendarRead | null;
+  /** Called whenever anyone, a pane included, loads the calendar. */
+  subscribe: (listener: () => void) => () => void;
+  schedule: (run: () => Promise<void> | void, delay: number) => () => void;
+  random: () => number;
+}
+
+const DEFAULT_DEPS: PrintWatchDeps = {
+  now: Date.now,
+  load: (force) => loadCalendar(force),
+  read: () => getCalendarCache({ allowExpired: true }),
+  subscribe: subscribeCalendar,
+  schedule: (run, delay) => {
+    const timer = setTimeout(run, delay);
+    return () => clearTimeout(timer);
+  },
+  random: Math.random,
+};
+
+function printBody(event: EconEvent): string {
+  return event.forecast ? `${event.event} ${event.actual} vs ${event.forecast}` : `${event.event} ${event.actual}`;
+}
+
+type PrintWatchContext = Pick<GloomPluginContext, "notify" | "showPane">;
+
+/**
+ * Toasts a high-impact print once, when it lands within
+ * {@link PRINT_PENDING_MS} of its release time. While one is due the
+ * calendar is asked for on {@link PRINT_BACKOFF_MS}, and every read is
+ * compared: the watch's own, its idle look at the cache, and a pane's
+ * refresh. The first read only records what has already printed.
+ */
+export function startHighImpactPrintWatch(
+  ctx: PrintWatchContext,
+  overrides: Partial<PrintWatchDeps> = {},
+): () => void {
+  const deps: PrintWatchDeps = { ...DEFAULT_DEPS, ...overrides };
+  let stopped = false;
+  let running = false;
+  let cancel: (() => void) | null = null;
+  /** The newest calendar the watch has seen. */
+  let latest: CalendarRead | null = null;
+  let lastAskAt = Number.NEGATIVE_INFINITY;
+  let primed = false;
+  /**
+   * Each high-impact row not yet past its window, by id: null while blank,
+   * then its number. A number stays once seen, so a print that blanks and
+   * comes back is not a new print.
+   */
+  const actuals = new Map<string, string | null>();
+  const expiries = new Map<string, number>();
+  let attempt = 0;
+  let dueIds = new Set<string>();
+
+  const toast = (event: EconEvent) => {
+    ctx.notify({
+      title: event.country,
+      body: printBody(event),
+      type: "info",
+      desktop: "always",
+      sound: "Glass",
+      duration: TOAST_DURATION_MS,
+      refId: `econ:${event.id}`,
+      action: { label: "Open", onClick: () => ctx.showPane("econ-calendar") },
+    });
+  };
+
+  /** `now` is when the read was asked for, so a print the last ask in the window brings back still counts. */
+  const observe = (read: CalendarRead | null, now = deps.now()) => {
+    if (stopped || !read) return;
+    if (!latest || read.fetchedAt >= latest.fetchedAt) latest = read;
+    const landed = primed ? landedHighImpactPrints(actuals, read.data) : [];
+    for (const event of read.data) {
+      if (event.impact !== "high") continue;
+      const expiresAt = event.date.getTime() + PRINT_PENDING_MS;
+      if (expiresAt < now) continue;
+      expiries.set(event.id, expiresAt);
+      if (event.actual) actuals.set(event.id, event.actual);
+      else if (!actuals.has(event.id)) actuals.set(event.id, null);
+    }
+    for (const [id, expiresAt] of expiries) {
+      if (expiresAt >= now) continue;
+      expiries.delete(id);
+      actuals.delete(id);
+    }
+    primed = true;
+    // A print that turns up after its window is recorded, not announced late.
+    for (const event of landed) {
+      if (now - event.date.getTime() <= PRINT_PENDING_MS) toast(event);
+    }
+  };
+
+  /** Whether a print in the newest calendar is due and still within its window. */
+  const printDue = (now: number): boolean => {
+    const pending = latest ? pendingHighImpactPrints(latest.data, now) : [];
+    // A release that has just come due starts the waits over.
+    if (pending.length === 0 || pending.some((event) => !dueIds.has(event.id))) attempt = 0;
+    dueIds = new Set(pending.map((event) => event.id));
+    return pending.length > 0;
+  };
+
+  const backoff = (): number => {
+    const base = PRINT_BACKOFF_MS[Math.min(attempt, PRINT_BACKOFF_MS.length - 1)]!;
+    attempt += 1;
+    return Math.round(base * (1 + (deps.random() * 2 - 1) * PRINT_JITTER));
+  };
+
+  const askWhileIdle = (now: number): boolean => (latest
+    ? now - Math.max(latest.fetchedAt, lastAskAt) >= CALENDAR_RECHECK_MS
+    : now - lastAskAt >= NO_CALENDAR_RETRY_MS);
+
+  const arm = (delay: number) => {
+    if (stopped || cancel) return;
+    cancel = deps.schedule(() => {
+      cancel = null;
+      return run();
+    }, delay);
+  };
+
+  const run = async () => {
+    if (stopped || running) return;
+    observe(deps.read());
+    const before = deps.now();
+    const due = printDue(before);
+    if (!due && !askWhileIdle(before)) {
+      arm(PRINT_IDLE_MS);
+      return;
+    }
+    running = true;
+    lastAskAt = before;
+    try {
+      // A due print is asked for past the cache; otherwise a fresh cache answers without a request.
+      observe(await deps.load(due), before);
+    } catch {
+      // The next ask follows the same schedule.
+    } finally {
+      running = false;
+    }
+    if (stopped) return;
+    // Past the window nothing is due, so the asks stop and the watch goes back to idle looks.
+    arm(printDue(deps.now()) ? backoff() : PRINT_IDLE_MS);
+  };
+
+  // A load the watch is waiting on is compared when it answers, at the time it was asked.
+  const unsubscribe = deps.subscribe(() => {
+    if (!running) observe(deps.read());
+  });
+  void run();
+  return () => {
+    stopped = true;
+    unsubscribe();
+    cancel?.();
+    cancel = null;
+  };
+}
+
+type PrintNotificationContext = PrintWatchContext & Pick<GloomPluginContext, "configState" | "on">;
+
+function printNotificationsEnabled(ctx: Pick<GloomPluginContext, "configState">): boolean {
+  return ctx.configState.get<boolean>(ECON_PRINT_NOTIFICATIONS_ENABLED_KEY) === true;
+}
+
+/**
+ * The one print watch, run while anything wants it: the Notifications
+ * setting, or an ECO pane in view, which fills a print in as it lands. Every
+ * reason shares its timing and its requests; only the setting toasts.
+ */
+export interface PrintRefresh {
+  /** The plugin's context, for toasts and their Open; null once it is disposed. */
+  attach(ctx: PrintWatchContext | null): void;
+  setNotifying(on: boolean): void;
+  /** An ECO pane can be seen; the returned release says it no longer can. */
+  retainVisiblePane(): () => void;
+}
+
+export function createPrintRefresh(
+  start: (ctx: PrintWatchContext) => () => void = startHighImpactPrintWatch,
+): PrintRefresh {
+  let host: PrintWatchContext | null = null;
+  let notifying = false;
+  let visiblePanes = 0;
+  let stopWatch: (() => void) | null = null;
+  // A print that lands while only a pane wants the watch is recorded, not toasted.
+  const watchContext: PrintWatchContext = {
+    notify: (notice) => {
+      if (notifying) host?.notify(notice);
+    },
+    showPane: (paneId) => host?.showPane(paneId),
+  };
+  const sync = () => {
+    const wanted = notifying || visiblePanes > 0;
+    if (wanted && !stopWatch) stopWatch = start(watchContext);
+    if (!wanted && stopWatch) {
+      stopWatch();
+      stopWatch = null;
+    }
+  };
+  return {
+    attach(ctx) {
+      host = ctx;
+    },
+    setNotifying(on) {
+      notifying = on;
+      sync();
+    },
+    retainVisiblePane() {
+      visiblePanes += 1;
+      sync();
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        visiblePanes -= 1;
+        sync();
+      };
+    },
+  };
+}
+
+const printRefresh = createPrintRefresh();
+
+/** For the ECO pane: while it can be seen, a due high-impact print is asked for on the watch's timing. */
+export function retainVisiblePrintRefresh(): () => void {
+  return printRefresh.retainVisiblePane();
+}
+
+/** Toasts prints while the Notifications setting is on; off, only a pane in view keeps the watch asking. */
+export function setupHighImpactPrintNotifications(
+  ctx: PrintNotificationContext,
+  refresh: PrintRefresh = printRefresh,
+): () => void {
+  refresh.attach(ctx);
+  const sync = () => refresh.setNotifying(printNotificationsEnabled(ctx));
+  const disposeConfigListener = ctx.on("config:changed", sync);
+  sync();
+  return () => {
+    disposeConfigListener();
+    refresh.setNotifying(false);
+    refresh.attach(null);
+  };
+}

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,11 @@ import {
   formatScreenValue,
   metricDate,
   parseScreenDefinition,
+  screenColumnLabel,
   screenDefinitionSyntax,
-  SHORT_LABELS,
+  screenLabel,
+  screenYtdBase,
+  withheldMetricNote,
 } from "./model";
 import type { ScreenDefinition } from "../../../api-client/equity-screener";
 
@@ -128,12 +133,21 @@ 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}`]
+      : [];
     // 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",
@@ -145,7 +159,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 +187,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,
@@ -481,6 +504,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 +560,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,11 @@ import {
   metricDate,
   parseScreenDefinition,
   resultFields,
-  SHORT_LABELS,
   SIGN_COLORED,
+  screenColumnLabel,
   screenLabel,
   screenRowId,
+  screenYtdBase,
 } from "./model";
 import { useScreenResults } from "./results";
 import { overlayLiveScreenRows, screenExtendedMove, screenExtendedSessions, sortLiveScreenRows, type LiveScreenRow } from "./live";
@@ -101,20 +102,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 +122,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 +144,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 +352,9 @@ 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);
+  const columns = resultColumns(width, definition, metric, staleFocus, extendedSessions, ytdBase);
   const apply = (next: ScreenDefinition) => {
     try {
       setDefinition(parseScreenDefinition(next));

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, {