gloomberb 0.16.1 → 0.16.3

package/src/plugins/builtin/analytics/risk-headless.ts

@@ -62,6 +62,7 @@ function coverageSummary(coverage: RiskCoverage, limit = Infinity) {
     coveredValue: coverage.coveredValue,
     holdings: coverage.holdings,
     covered: coverage.covered,
+    convertedFromLocalCurrency: coverage.converted,
     leftOut: coverage.leftOut
       .slice(0, limit)
       .map((row) => ({ symbol: row.symbol, reason: row.reason, share: row.share })),
@@ -69,12 +70,14 @@ function coverageSummary(coverage: RiskCoverage, limit = Infinity) {
   };
 }
 
-/** One line for the whole coverage in place of a notice per left-out holding. */
-function coverageError(coverage: RiskCoverage | undefined): string | null {
+/** One line for the whole coverage in place of a note per left-out holding. */
+function coverageLine(coverage: RiskCoverage | undefined): { error?: string; note?: string } {
   const shortfall = riskCoverageShortfall(coverage);
-  if (shortfall) return `Basket estimates unavailable: ${shortfall.title} ${shortfall.message}`.trim();
-  const text = riskCoverageText(coverage);
-  return text ? `Basket ${text}; metadata.coverage lists each with its reason.` : null;
+  // No estimate at all is a failure; an estimate that leaves holdings out is a caveat.
+  if (shortfall) return { error: `Basket estimates unavailable: ${shortfall.title} ${shortfall.message}`.trim() };
+  return coverage?.leftOut.length
+    ? { note: `Basket ${riskCoverageText(coverage)}; metadata.coverage lists each with its reason.` }
+    : {};
 }
 
 /** One view, its strongest or first rows, and the portfolio's totals instead of the model. */
@@ -101,6 +104,7 @@ function compactRiskRows(model: PortfolioRiskModel, view: RiskView): { rows: Ris
 
 export const portfolioRiskHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle",
+  freshness: { source: "Local portfolio and Gloom Cloud", status: "not-a-feed", basis: "risk model on daily closes" },
   argument: {
     kind: "free-text",
     optional: true,
@@ -115,7 +119,7 @@ export const portfolioRiskHeadless: HeadlessPaneDefinition<"bundle"> = {
       "Explicit local evidence for account returns and attribution",
     ],
     limitations: [
-      `Fixed-current-weight USD equity basket over the holdings that qualify, largest ${RISK_HISTORY_LIMIT} by value; metadata.coverage states the covered share of market value and each holding left out`,
+      `Fixed-current-weight USD equity basket over the holdings that qualify, largest ${RISK_HISTORY_LIMIT} by value; foreign listings convert to USD at daily FX closes; metadata.coverage states the covered share of market value and each holding left out`,
       "No account performance inferred",
       "ETF price-return factor proxies",
       "Historical percentiles need 20 rolling samples",
@@ -237,9 +241,12 @@ export const portfolioRiskHeadless: HeadlessPaneDefinition<"bundle"> = {
               : view === "factors"
                 ? covered && model.factors.every((row) => row.value != null)
                 : model.complete;
+    // A basket view with too little covered shows no estimate, and the report says why rather than leaving dashes.
+    const shortfall = BASKET_VIEWS.has(view as RiskView) ? coverageLine(model.coverage).error : undefined;
     return {
       complete,
-      errors: [...riskCoverageNotices(model.coverage), ...model.warnings],
+      errors: [...(shortfall ? [shortfall] : []), ...model.warnings],
+      notes: [...riskCoverageNotices(model.coverage), ...model.notes],
       sections: RISK_VIEWS.map((view) => ({
         title: view,
         columns: RISK_COLUMNS,
@@ -253,17 +260,16 @@ export const portfolioRiskHeadless: HeadlessPaneDefinition<"bundle"> = {
     if (!model?.rows) return result;
     const view = isRiskView(args.options.view) ? args.options.view : "risk";
     const { rows, notices } = compactRiskRows(model, view);
-    // Each left-out holding is in metadata.coverage; the errors keep one line for all of them.
+    // Each left-out holding is in metadata.coverage; the notes keep one line for all of them.
     const perHolding = new Set(riskCoverageNotices(model.coverage));
     const basketView = BASKET_VIEWS.has(view);
-    const coverageLine = basketView ? coverageError(model.coverage) : null;
-    const errors = [
-      ...(coverageLine ? [coverageLine] : []),
-      ...(result.errors ?? []).filter((error) => !perHolding.has(error)),
-    ];
+    const coverage = basketView ? coverageLine(model.coverage) : {};
+    const errors = [...new Set([...(coverage.error ? [coverage.error] : []), ...(result.errors ?? [])])];
+    const notes = [...(coverage.note ? [coverage.note] : []), ...(result.notes ?? []).filter((note) => !perHolding.has(note))];
     return {
       complete: result.complete,
       ...(errors.length ? { errors } : {}),
+      ...(notes.length ? { notes } : {}),
       sections: [{ title: view, columns: RISK_COLUMNS, rows: rows.map(displayRow) }],
       metadata: {
         portfolio: {

package/src/plugins/builtin/analytics/risk-model.ts

@@ -46,6 +46,8 @@ interface PortfolioRiskHolding {
   priceAsOf: string | null;
   /** "close" when no current quote arrived and the latest completed close marks the holding. */
   markSource?: "quote" | "close" | null;
+  /** The listing currency its closes were converted from at daily FX closes; null for a USD listing. */
+  convertedFrom: string | null;
   historyAsOf: string | null;
   returns: DatedReturn[];
   error: string | null;
@@ -71,6 +73,8 @@ export interface RiskCoverage {
   holdings: number;
   /** Holdings that qualify for the basket. */
   covered: number;
+  /** Covered holdings whose returns were converted to USD from their listing currency. */
+  converted: number;
   unvalued: number;
   minimumShare: number;
   /** The basket views estimate only when qualifying holdings reach the minimum share. */
@@ -223,24 +227,28 @@ const coveragePercent = (share: number) => Math.floor(share * 100);
 const holdingCount = (count: number) => `${count} holding${count === 1 ? "" : "s"}`;
 const shareText = (share: number) =>
   share < 0.001 ? "under 0.1%" : `${(share * 100).toFixed(1)}%`;
-/** "covers 78% of market value · 9 holdings left out", or null when nothing is left out. */
+/**
+ * "covers 78% of market value · 9 holdings left out · 2 converted from local
+ * currency", or null when every holding is in the basket in its own USD listing.
+ */
 export function riskCoverageText(coverage: RiskCoverage | undefined): string | null {
-  if (!coverage?.leftOut.length) return null;
+  if (!coverage) return null;
+  const converted = coverage.converted ? `${holdingCount(coverage.converted)} converted from local currency` : null;
+  if (!coverage.leftOut.length) return converted;
   const covers = coverage.share == null
     ? "covers an unknown share of market value"
     : `covers ${coverage.unvalued ? "at most " : ""}${coveragePercent(coverage.share)}% of market value`;
-  return `${covers} · ${holdingCount(coverage.leftOut.length)} left out`;
+  return [covers, `${holdingCount(coverage.leftOut.length)} left out`, ...(converted ? [converted] : [])].join(" · ");
 }
-/** One notice per left-out holding, largest first, after a lead line. */
+/** A reason reads as the tail of a sentence, so its first word loses its capital unless it is an acronym ("FX", "USD"). */
+const lowerFirst = (text: string) => (/^[A-Z][a-z]/.test(text) ? text[0]!.toLowerCase() + text.slice(1) : text);
+/** One sentence per left-out holding, largest first, naming the holding and why it is out. */
 export function riskCoverageNotices(coverage: RiskCoverage | undefined): string[] {
   if (!coverage?.leftOut.length) return [];
-  return [
-    `${holdingCount(coverage.leftOut.length)} left out of the basket, largest first:`,
-    ...coverage.leftOut.map(
-      (row) =>
-        `${row.symbol} (${row.share == null ? "value unknown" : `${shareText(row.share)} of market value`}): ${row.reason}`,
-    ),
-  ];
+  return coverage.leftOut.map(
+    (row) =>
+      `${row.symbol} (${row.share == null ? "value unknown" : `${shareText(row.share)} of market value`}) is excluded from the risk estimate: ${lowerFirst(row.reason.replace(/\.$/, ""))}.`,
+  );
 }
 /** Why the basket views show no estimate, when too little of the account qualifies. */
 export function riskCoverageShortfall(
@@ -321,10 +329,13 @@ export function buildPortfolioRisk(
         ? { price: quote.price, currency: quote.currency, stale: !!quote.stale }
         : null;
     const quantity = signedQuantity(lots);
+    // A converted listing is marked and returned in USD; its own currency is what the holding records.
+    const convertedFrom = history?.converted?.currency ?? null;
     const listingCurrency =
       quote?.currency ?? close?.currency ?? history?.listing?.currency ?? ticker.metadata.currency;
+    const foreign = !convertedFrom && listingCurrency !== "USD";
     const error =
-      syntheticPositionUnsupportedReason(ticker, listingCurrency, portfolio.id) ??
+      syntheticPositionUnsupportedReason(ticker, "USD", portfolio.id) ??
       (lots.some((row) => !Number.isFinite(row.shares))
         ? "Invalid position quantity"
         : null) ??
@@ -332,10 +343,14 @@ export function buildPortfolioRisk(
         ? "Historical account-currency FX is required"
         : null) ??
       (ticker.metadata.currency &&
-      mark?.currency &&
-      ticker.metadata.currency !== mark.currency
+      (convertedFrom ?? mark?.currency) &&
+      ticker.metadata.currency !== (convertedFrom ?? mark?.currency)
         ? "Holding and quote currencies differ"
         : null) ??
+      // A foreign listing that did not convert says why: no pair, stale or gapped FX.
+      (foreign
+        ? (history?.error ?? syntheticPositionUnsupportedReason(ticker, listingCurrency, portfolio.id))
+        : null) ??
       history?.error ??
       (!history ? "Daily history unavailable" : null);
     const priceDate = close ? close.date : quoteDate(quote?.lastUpdated);
@@ -376,6 +391,7 @@ export function buildPortfolioRisk(
           : outsideValue(ticker, portfolio, quote ?? history?.listing ?? null, rates),
       priceAsOf: priceDate,
       markSource: close ? "close" : quote ? "quote" : null,
+      convertedFrom,
       historyAsOf: history?.asOf ?? null,
       returns,
       error,
@@ -395,6 +411,7 @@ export function buildPortfolioRisk(
     share,
     holdings: holdings.length,
     covered: qualifying.length,
+    converted: qualifying.filter((row) => row.convertedFrom != null).length,
     unvalued: holdings.length - valued.length,
     minimumShare: RISK_MIN_COVERAGE,
     sufficient,
@@ -416,14 +433,24 @@ export function buildPortfolioRisk(
     holding.weight =
       book?.rows.find((row) => row.id === holding.id)?.weight ?? null;
   const closeMarked = members.filter((row) => row.markSource === "close").length;
+  const converted = members.filter((row) => row.convertedFrom != null).length;
   const held = new Set(holdings.map((row) => row.id));
-  const warnings = [
-    ...market.warnings,
+  // Caveats about an estimate that was made; the warnings are what failed.
+  const notes = [
     ...(closeMarked
       ? [
           `${closeMarked} holding${closeMarked === 1 ? "" : "s"} had no current quote; weighted at the latest completed close.`,
         ]
       : []),
+    // Daily closes pair by date, so a market that closes before or after the US session is not synchronous with it.
+    ...(converted
+      ? [
+          "Converted holdings are matched to the US close of the same date; where their market closes at another time, correlations and betas to US holdings read lower than they are.",
+        ]
+      : []),
+  ];
+  const warnings = [
+    ...market.warnings,
     // A held instrument's failure is its left-out reason; factor proxies report here.
     ...market.histories.flatMap((row) =>
       row.error && !held.has(riskInstrumentId(row.instrument))
@@ -561,7 +588,7 @@ export function buildPortfolioRisk(
       asOf: row.priceAsOf,
       detail: row.leftOut
         ? row.leftOut
-        : `${row.quantity} shares; ${formatNumber(row.value ?? undefined)} ${row.currency}${row.markSource === "close" ? ` at ${row.priceAsOf} close` : ""}; history ${row.historyAsOf}`,
+        : `${row.quantity} shares; ${formatNumber(row.value ?? undefined)} ${row.currency}${row.markSource === "close" ? ` at ${row.priceAsOf} close` : ""}${row.convertedFrom ? ` from ${row.convertedFrom} at daily FX` : ""}; history ${row.historyAsOf}`,
       ...(row.leftOut ? { leftOut: row.leftOut } : {}),
     })),
     correlation: correlation.map((row) => ({
@@ -733,6 +760,7 @@ export function buildPortfolioRisk(
       coverage.leftOut.length === 0 &&
       metrics.some((row) => row.value != null),
     warnings: [...new Set(warnings)],
+    notes,
     fetchedAt: market.fetchedAt,
   };
 }

package/src/plugins/builtin/analytics/risk-pane.tsx

@@ -444,6 +444,7 @@ export function PortfolioRiskPane({ focused, width, height }: PaneProps) {
   // views say what they need in the body, with the import action.
   const notices = [
     ...riskCoverageNotices(model?.coverage),
+    ...(model?.notes ?? []),
     ...(model?.warnings ?? []),
     ...(derived.error ? [derived.error] : []),
     ...(resource.error ? [resource.error] : []),

package/src/plugins/builtin/analytics/risk-test-data.ts

@@ -178,14 +178,35 @@ function fredSeries(id: string, asOf: Date): CloudFredSeriesPayload {
   };
 }
 
+/**
+ * Daily closes of the pair that prices `currency` against the dollar, every
+ * weekday as FX trades, wobbling around the rate the endpoint reports.
+ */
+function fxPairHistory(symbol: string, asOf: Date): CloudMarketResponse<CloudPricePointPayload[]> | null {
+  const currency = symbol.replace(/(USD)?=X$/, "");
+  const rate = BROKER_FX_RATES[currency];
+  if (rate == null) return null;
+  const usdQuoted = symbol.endsWith("USD=X");
+  const data: CloudPricePointPayload[] = [];
+  const today = Date.parse(asOf.toISOString().slice(0, 10));
+  for (let day = today - 240 * 86_400_000; day < today; day += 86_400_000) {
+    if ([0, 6].includes(new Date(day).getUTCDay())) continue;
+    const usdPerUnit = rate * (1 + Math.sin(data.length / 5) / 100);
+    const close = usdQuoted ? usdPerUnit : 1 / usdPerUnit;
+    data.push({ date: new Date(day).toISOString(), open: close, high: close, low: close, close });
+  }
+  return { status: "success", data, providerMeta: { servedResolution: "1d", normalizedSymbol: symbol } };
+}
+
 /**
  * Cloud responses for the broker account: US listings and the factor proxies
  * quote and keep daily history, foreign listings quote in their own currency,
- * the uncovered holdings have neither.
+ * the uncovered holdings have neither. Daily FX history exists only with `fx`.
  */
 export function brokerRiskClient(
   asOf: Date = now,
   holdings: readonly BrokerFixtureHolding[] = brokerFixtureHoldings(),
+  { fx = false }: { fx?: boolean } = {},
 ) {
   const bySymbol = new Map(holdings.map((holding) => [normalizeSymbol(holding.symbol), holding]));
   const find = (symbol: string) => bySymbol.get(normalizeSymbol(symbol));
@@ -217,6 +238,9 @@ export function brokerRiskClient(
     },
     getCloudHistory: async (symbol: string, exchange: string) => {
       calls.histories.push(symbol);
+      if (symbol.endsWith("=X"))
+        return (fx && fxPairHistory(symbol, asOf)) ||
+          { status: "empty" as const, data: null, reasonCode: "Daily history unavailable" };
       const holding = find(symbol);
       if (holding && holding.price == null)
         return { status: "empty" as const, data: null, reasonCode: "Daily history unavailable" };

package/src/plugins/builtin/attention/headless.ts

@@ -15,16 +15,18 @@ export const attentionHeadless: HeadlessPaneDefinition<"bundle"> = {
     const metadata = { asOf: data.asOf, stale: data.stale, complete: data.status === "ready" && !data.truncated,
       status: data.status, periodStart: data.periodStart, periodEnd: data.periodEnd, entitlement: data.entitlement,
       privacy: data.privacy, coverage: data.coverage, methodologyUrl: data.methodologyUrl, selectedListing: data.selectedListing ?? null, historyEvidence: data.historyEvidence ?? null, unit: "rounded researcher-hours" };
-    if (tab === "sectors" || tab === "countries") return { metadata, sections: [{ title: tab === "sectors" ? "Sector attention" : "Country attention",
+    // Published hour by hour, so not a feed, but the service says when publication has fallen behind.
+    const freshness = { status: data.stale ? "stale" as const : "not-a-feed" as const, basis: "hourly publication" };
+    if (tab === "sectors" || tab === "countries") return { metadata, freshness, sections: [{ title: tab === "sectors" ? "Sector attention" : "Country attention",
       columns: [{ key: "name", header: "Group" }, { key: "researchUnits", header: "Research hours" }, { key: "sharePct", header: "Share %" }, { key: "tickers", header: "Tickers" }], rows: data[tab].map((row) => ({ ...row })) }] };
-    if (tab === "history") return { metadata, sections: [{ title: "Published hourly history", columns: [{ key: "symbol", header: "Ticker" },
+    if (tab === "history") return { metadata, freshness, sections: [{ title: "Published hourly history", columns: [{ key: "symbol", header: "Ticker" },
       { key: "bucketStart", header: "Hour (UTC)" }, { key: "researchUnits", header: "Research hours" }],
       rows: data.history && data.selectedListing ? data.history.map((point) => ({ symbol: data.selectedListing!.symbol, ...point })) : data.rows.flatMap((row) => row.history.map((point) => ({ symbol: row.symbol, ...point }))) }] };
-    if (tab === "evidence") return { metadata, sections: [{ title: "Publication evidence", columns: [{ key: "symbol", header: "Ticker" },
+    if (tab === "evidence") return { metadata, freshness, sections: [{ title: "Publication evidence", columns: [{ key: "symbol", header: "Ticker" },
       { key: "periodStart", header: "Period start" }, { key: "periodEnd", header: "Period end" }, { key: "asOf", header: "Published" },
       { key: "confidence", header: "Quality" }, { key: "marketAsOf", header: "Market as of" }],
       rows: data.rows.map((row) => ({ symbol: row.symbol, ...row.evidence, baselinePeriods: row.baselinePeriods, marketAsOf: row.marketAsOf, news: row.news })) }] };
-    return { metadata, sections: [{ title: tab === "abnormal" ? "Abnormal attention" : "Research ranking", columns: [
+    return { metadata, freshness, sections: [{ title: tab === "abnormal" ? "Abnormal attention" : "Research ranking", columns: [
       { key: "rank", header: "Rank" }, { key: "symbol", header: "Ticker" }, { key: "name", header: "Name" }, { key: "researchUnits", header: "Research hours" },
       { key: "sharePct", header: "Share %" }, { key: "zScore", header: "Latest-hour Z-score" }, { key: "priceChangePct", header: "Price %" },
       { key: "relativeVolume", header: "Relative volume" }, { key: "sector", header: "Sector" }, { key: "country", header: "Country" },

package/src/plugins/builtin/attention/index.tsx

@@ -7,7 +7,7 @@ import { AttentionPane } from "./pane";
 export const attentionModule: PluginModule = {
   panes: [{ id: "attention", name: "Research Attention", icon: "A", component: AttentionPane, defaultPosition: "right", defaultMode: "floating",
     defaultFloatingSize: { width: 126, height: 32 }, tableExport: true, headless: attentionHeadless },
-    { id: "attention-trending", name: "Gloom Trending", icon: "A", component: TrendingPane, defaultPosition: "right", defaultMode: "floating", defaultFloatingSize: { width: 58, height: 12 } }],
+    { id: "attention-trending", reportFreshness: { status: "not-a-feed", basis: "hourly publication" }, name: "Gloom Trending", icon: "A", component: TrendingPane, defaultPosition: "right", defaultMode: "floating", defaultFloatingSize: { width: 58, height: 12 } }],
   paneTemplates: [{ id: "attention-pane", paneId: "attention", label: "Research Attention",
     description: "Pro research attention: rankings, abnormal activity, sectors, countries and privacy-qualified hourly history.",
     keywords: ["attention", "trending", "research", "activity"], shortcut: { prefix: "ATTN", argKind: "text", argPlaceholder: "TICKER", argOptional: true },

package/src/plugins/builtin/attention/pane.tsx

@@ -58,7 +58,7 @@ function Evidence({ row, data, width, height }: { row: DetailRow; data: Attentio
   const sameDay = row.evidence.periodStart.slice(0, 10) === row.evidence.periodEnd.slice(0, 10);
   const period = sameDay ? `${hour(row.evidence.periodStart)} to ${row.evidence.periodEnd.slice(11, 16)} UTC` : `${hour(row.evidence.periodStart)} to ${date(row.evidence.periodEnd)}`;
   const latest = point?.bucketStart === row.history.at(-1)?.bucketStart;
-  return <ScrollBox width={width} height={desktop ? undefined : height} flexGrow={1} flexBasis={0} contentOptions={{ paddingX: 1 }}>
+  return <ScrollBox scrollY width={width} height={desktop ? undefined : height} flexGrow={1} flexBasis={0} contentOptions={{ paddingX: 1 }}>
     <KeyValueRow label="Listing" value={row.symbol} detail={row.name ?? undefined} labelWidth={20} />
     <SectionHeading title="Publication" />
     <KeyValueRow label="Research hours" value={number(row.researchUnits)} detail={`rounded to ${data.privacy.rounding}`} labelWidth={20} />
@@ -159,7 +159,7 @@ export function AttentionPane({ width, height, focused }: PaneProps) {
   const cell = (row: AttentionRow | AttentionGroup | Locked, column: DataTableColumn, _index: number, state: { selected: boolean }): DataTableCell => {
     if (isLocked(row)) return desktop ? { text: "", content: <Blurred><Text fg={colors.textDim}>{column.id === "name" ? "Additional research" : "Hidden"}</Text></Blurred> }
       : { text: column.id === columns[0]!.id && row.id === "locked:0" ? "Pro" : "░░░", color: colors.textDim };
-    if (column.id === "sharePct") return { ...shareCell(number(row.sharePct, 1), maxShare ? row.sharePct / maxShare : null, column.width, colors, state.selected, desktop), value: row.sharePct };
+    if (column.id === "sharePct") return { ...shareCell(number(row.sharePct, 1), maxShare ? row.sharePct / maxShare : null, column.width, colors, state.selected), value: row.sharePct };
     if ("symbol" in row) {
       const numeric = typeof row[column.id as keyof AttentionRow] === "number" ? row[column.id as keyof AttentionRow] as number : undefined;
       switch (column.id) {

package/src/plugins/builtin/awards/headless.ts

@@ -15,6 +15,7 @@ const awardRecord = (row: AwardRow) => ({ id: row.id, date: row.awardDate, dateB
 
 export const awardsHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle", argument: { kind: "free-text", optional: true, placeholder: "ticker", description: "Optional verified listed-company ticker, including exchange suffix." },
+  freshness: { source: "Public procurement records", status: "not-a-feed", basis: "published awards" },
   discovery: { aliases: ["AWARDS"], dataRequirements: ["Verified Gloom Cloud account"],
     limitations: ["Pro dataset; free accounts receive a limited preview", "Published procurement records; source coverage varies by jurisdiction",
       "Currencies and prime awards, subawards and notices are separate", "Award obligations are not revenue or remaining backlog", "Unresolved recipients retain their legal names"] },

package/src/plugins/builtin/awards/pane.tsx

@@ -240,7 +240,7 @@ function AwardsView({ width, height, focused, symbol }: PaneProps & { symbol: st
               if (column.id === "contracts") return { text: item.row.count.toLocaleString("en-US"), value: item.row.count, color: colors.textDim };
               if (column.id === "scope") return { text: awardScope(item.row.source), color: colors.textDim };
               return item.row.sharePercent === null ? missingCell(colors)
-                : { ...shareCell(`${item.row.sharePercent.toFixed(1)}%`, maxShare ? item.row.sharePercent / maxShare : null, column.width, colors, state.selected, desktop), value: item.row.sharePercent };
+                : { ...shareCell(`${item.row.sharePercent.toFixed(1)}%`, maxShare ? item.row.sharePercent / maxShare : null, column.width, colors, state.selected), value: item.row.sharePercent };
             }
             const award = item.row;
             if (column.id === "date") return { text: award.awardDate, value: award.awardDate };

package/src/plugins/builtin/backtest/headless.ts

@@ -8,6 +8,7 @@ import { parseRule } from "./rules";
 
 export const backtestHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle",
+  freshness: { status: "not-a-feed", basis: "backtest on daily closes", cadence: "daily", observedKey: "date", oldest: null },
   argument: { kind: "ticker", description: "Instrument to test" },
   describe: (args) => `BT ${args.symbols[0] ?? ""}`,
   discovery: {

package/src/plugins/builtin/bond-calculator/headless.ts

@@ -32,6 +32,7 @@ export const bondCalculatorHeadless: HeadlessPaneDefinition<"bundle"> = {
     return {
       complete: errors.length === 0,
       errors,
+      freshness: { source: "Your inputs, US Treasury", status: "not-a-feed", basis: "calculator", asOf: result.spread?.asOf ?? null },
       metadata: { settlement: draft.settlement, terms: result.terms, source: "Manual bond inputs; Treasury par yields via Gloom Cloud / FRED",
         treasuryAsOf: result.spread?.asOf ?? null, percentile: null, percentileReason: "Hypothetical bond has no historical sample", units: "Prices and DV01 per 100 face", mode: draft.mode },
       sections: [

package/src/plugins/builtin/buildout/index.tsx

@@ -4,6 +4,7 @@ import type { PluginModule } from "../plugin-module";
 export const buildoutModule: PluginModule = {
   panes: [{
     id: "buildout",
+    reportFreshness: { status: "not-a-feed", basis: "infrastructure research" },
     name: "TheBuildout",
     icon: "T",
     component: BuildoutPane,

package/src/plugins/builtin/catalysts/detail.tsx

@@ -18,7 +18,7 @@ function Evidence({ event, width, height }: { event: CatalystEvent; width: numbe
   const facts = catalystFacts(event);
   const procedures = Array.isArray(event.metadata?.proceduralStatements) ? event.metadata.proceduralStatements.filter((value): value is string => typeof value === "string") : [];
   const documents = Array.isArray(event.metadata?.documents) ? event.metadata.documents.filter((value): value is { url: string; title?: string; label?: string } => !!value && typeof value === "object" && "url" in value && typeof value.url === "string" && /^https?:\/\//.test(value.url)) : [];
-  return <ScrollBox width={width} height={desktop ? undefined : height} flexGrow={1} flexBasis={0} contentOptions={{ paddingX: 1 }}>
+  return <ScrollBox scrollY width={width} height={desktop ? undefined : height} flexGrow={1} flexBasis={0} contentOptions={{ paddingX: 1 }}>
     <KeyValueRow label="Classification" value={`${catalystLabel(event.type)} · ${catalystAgency(event.agency)} · ${event.country ?? event.jurisdiction}`} labelWidth={18} />
     <KeyValueRow label="Status" value={humanLabel(event.status)} detail={`Revision ${event.revision}`} labelWidth={18} />
     <KeyValueRow label="Announced" value={catalystDate(event, "announced")} labelWidth={18} />

package/src/plugins/builtin/catalysts/headless.ts

@@ -5,7 +5,9 @@ import { catalystCell, catalystChangeText, catalystDate, catalystQuery, catalyst
 
 function definition(litigation: boolean): HeadlessPaneDefinition<"bundle"> {
   return {
-    shape: "bundle", argument: { kind: "ticker", optional: !litigation, description: litigation ? "Company ticker, including exchange-qualified international listings." : "Optional ticker; omit for market-wide events." },
+    shape: "bundle",
+    freshness: { source: litigation ? "Court and agency dockets" : "Regulator, court and trade records", status: "not-a-feed", basis: "published records" },
+    argument: { kind: "ticker", optional: !litigation, description: litigation ? "Company ticker, including exchange-qualified international listings." : "Optional ticker; omit for market-wide events." },
     options: [
       { key: "tab", type: "enum", values: [{ value: "calendar" }, { value: "changes" }], defaultValue: "calendar", description: "Dated events or observed revisions." },
       { key: "type", type: "enum", values: CATALYST_TYPES.map((value) => ({ value })), description: "Event type." },

package/src/plugins/builtin/cds/headless.ts

@@ -89,6 +89,8 @@ export function createCdsHeadless(
 ): HeadlessPaneDefinition<"rows"> {
   return {
     shape: "rows",
+    // Public dissemination of swap trades, held back by rule for some trades.
+    freshness: { source: "DTCC", status: "delayed" },
     argument: {
       kind: "free-text",
       placeholder: "ticker or issuer",

package/src/plugins/builtin/central-bank-rates/headless.ts

@@ -6,6 +6,7 @@ export const centralBankRatesHeadless: HeadlessPaneDefinition<"bundle"> = {
   discovery: { aliases: ["CBR", "CBRT"], dataRequirements: ["Gloom Cloud central-bank-rates endpoint"],
     limitations: ["Published policy observations with individual dates", "Policy instruments differ", "Only US meeting dates are maintained"] },
   shape: "bundle", options: [], argument: { kind: "none" }, describe: "G20 central bank policy rates",
+  freshness: { source: "Central banks and BIS", status: "not-a-feed", basis: "published policy rates" },
   async load(_args, ctx) {
     const data = await fetchCentralBankRates(ctx.apiClient);
     const errors = policyNotices(data);

package/src/plugins/builtin/chart-composer/headless.ts

@@ -2,8 +2,10 @@ import { financialPeriodCoverage } from "../../../time-series/financial-period-c
 import { FINANCIAL_VINTAGE_NOTICE, SEC_EPS_BASIS_NOTICE } from "../../../utils/financial-statements";
 import { graphRowsForFinancials, summarizeResolvedSeries } from "../../../time-series/reporting";
 import { priceHistoryIntegrityNotices, chartPriceHistoryIntegrityNotices } from "../../../time-series/market";
-import type { HeadlessPaneContext, HeadlessPaneDefinition, HeadlessSeriesResult } from "../../../types/headless";
-import type { ChartResolutionResult, ChartSeriesSpec, ChartSpec } from "../../../time-series/types";
+import type { HeadlessPaneContext, HeadlessPaneDefinition, HeadlessPaneFreshness, HeadlessSeries, HeadlessSeriesResult } from "../../../types/headless";
+import type { CapabilitySeriesSource, ChartResolutionResult, ChartSeriesSpec, ChartSpec, ChartViewportSpec } from "../../../time-series/types";
+import { resolveGeoChartSeries } from "../world-venue-map/geo-series";
+import { GEO_SERIES_CAPABILITY_ID } from "./series-expression";
 import { mergePriceHistoryWindows, priceHistoryAcquisitionIdentity, priceHistoryTailAcquisition, resolveChartSpecData } from "../../../time-series/resolve";
 import { intersectChartResolutionSupport, isIntradayResolution, normalizeChartResolutionSupport, type ManualChartResolution } from "../../../time-series/resolution";
 import { intradaySessionDates, loadIntradayWindow, resolveIntradayRequest, type IntradayRequest, type IntradayWindow, type LoadedIntradayWindow } from "./session-history";
@@ -16,6 +18,7 @@ import { createChartSeriesResolver } from "../../../capabilities";
 import { parsePublicTickerKey, publicTickerKey, resolveExchangeTimeZone } from "../../../utils/exchanges";
 import { parseChartSpec } from "./chart-spec";
 import { paneSchemas } from "./headless-schema";
+import { barHistoryFreshness, REPORTED_DATA } from "../shared/report-freshness";
 
 export interface ChartPaneModel extends HeadlessSeriesResult {
   /** The renderer consumes the full model; generic reports project series and metadata. */
@@ -37,6 +40,23 @@ export interface ChartPaneModel extends HeadlessSeriesResult {
   };
 }
 
+/**
+ * Map series read straight from the Cloud client, so a report or screenshot
+ * charts them where plugin capability handlers are not running; every other
+ * capability series goes through the registry as before.
+ */
+function headlessCapabilityResolver(context: HeadlessPaneContext) {
+  const registry = context.capabilities ? createChartSeriesResolver(context.capabilities) : null;
+  return async (source: CapabilitySeriesSource, viewport: ChartViewportSpec, spec: ChartSeriesSpec) => {
+    if (source.capabilityId === GEO_SERIES_CAPABILITY_ID) {
+      const request = <T,>(path: string, init?: RequestInit) => context.apiClient.geo<T>(path, { ...init, signal: init?.signal ?? context.signal });
+      return resolveGeoChartSeries(request, source.seriesId, viewport, context.signal);
+    }
+    if (!registry) throw new Error(`Chart series capability "${source.capabilityId}" is unavailable. Enable its plugin or provider.`);
+    return registry(source, viewport, spec);
+  };
+}
+
 export async function loadChartPaneModel(
   spec: ChartSpec,
   context: HeadlessPaneContext,
@@ -101,7 +121,7 @@ export async function loadChartPaneModel(
         if (!primary || rank < primary.rank) primaryHistories.set(key, { key: variantKey, rank });
       }
     },
-    ...(context.capabilities ? { resolveCapabilitySeries: createChartSeriesResolver(context.capabilities) } : {}),
+    resolveCapabilitySeries: headlessCapabilityResolver(context),
     loadFredSeries: async (request) => ({
       data: await context.apiClient.getCloudFredSeries(request.seriesId, {
         startDate: request.startDate,
@@ -189,6 +209,20 @@ export async function loadChartPaneModel(
   };
 }
 
+/**
+ * Price series are bar histories, stale once bars of the coarsest size stop
+ * arriving; fundamentals, valuations and economic series are reported data.
+ */
+function chartFreshness(series: readonly HeadlessSeries[]): HeadlessPaneFreshness {
+  const order = ["1wk", "1mo"];
+  const resolutions = series.map((entry) => (entry as HeadlessSeries & { historyResolution?: string }).historyResolution);
+  if (!series.length || resolutions.some((resolution) => !resolution)) return { ...REPORTED_DATA, basis: "reported and published data" };
+  const coarsest = resolutions.reduce((worst, resolution) => (
+    order.indexOf(resolution!) > order.indexOf(worst!) ? resolution : worst
+  ), resolutions[0]);
+  return barHistoryFreshness(coarsest);
+}
+
 export function chartHeadless(template: keyof typeof paneSchemas): HeadlessPaneDefinition<"series"> {
   return {
     ...paneSchemas[template],
@@ -262,6 +296,7 @@ export function chartHeadless(template: keyof typeof paneSchemas): HeadlessPaneD
         }
       }
       model.snapshot.intradayHistories = intradayHistories;
+      model.freshness = chartFreshness(model.series);
       const priceDomainFailures = intradayHistories.flatMap(({ symbol, exchange, priceDomainFailure }) =>
         priceDomainFailure ? [{ symbol, exchange, ...priceDomainFailure }] : []);
       if (priceDomainFailures.length) {

package/src/plugins/builtin/chart-composer/index.tsx

@@ -253,7 +253,9 @@ const chartComposerTemplates: PaneTemplateDef[] = [
       label: "Chart Series",
       placeholder: "AAPL:price, MSFT:revenue, FRED:CPIAUCSL",
       type: "text",
-      body: ["Enter comma-separated SYMBOL:field or FRED:series expressions."],
+      // Empty falls back to the active ticker in createInstance, as `G` with no argument does.
+      required: false,
+      body: ["Enter comma-separated SYMBOL:field or FRED:series expressions, or leave empty to chart the active ticker."],
     }],
     canCreate: () => true,
     createInstance: (context, options) => {

package/src/plugins/builtin/chart-composer/series-expression.ts

@@ -33,6 +33,14 @@ export const CHART_FIELD_IDS = {
   evEbitda: "valuation.evEbitda",
 } as const;
 
+/** Series of things with a place (chokepoint transits, port calls), served with the map's layers. */
+export const GEO_SERIES_CAPABILITY_ID = "geo-series";
+
+/** `GEO:<series id or short alias>`, e.g. `GEO:SUEZ`. */
+export function formatGeoSeriesExpression(seriesId: string): string {
+  return `GEO:${seriesId}`;
+}
+
 export type ParsedSeriesExpression =
   | { kind: "security"; symbol: string; exchange?: string; fieldId: string; label?: string }
   | { kind: "economic"; provider: "fred"; seriesId: string; label?: string }
@@ -96,6 +104,12 @@ export function parseSeriesExpression(value: string): ParsedSeriesExpression | n
       ? { kind: "capability", capabilityId, seriesId }
       : null;
   }
+  if (parts[0]?.trim().toUpperCase() === "GEO") {
+    const seriesId = trimmed.slice(trimmed.indexOf(":") + 1).trim();
+    return parts.length >= 2 && isValidChartSeriesId(seriesId)
+      ? { kind: "capability", capabilityId: GEO_SERIES_CAPABILITY_ID, seriesId }
+      : null;
+  }
   if (parts[0]?.trim().toUpperCase() === "FRED") {
     const seriesId = parts.length === 2 ? parts[1]?.trim().toUpperCase() ?? "" : "";
     return /^[A-Z0-9._-]{1,80}$/.test(seriesId)
@@ -160,7 +174,7 @@ export function parseChartExpression(value: string): ParsedSeriesExpression[] {
     if (parsed) return parsed;
     const display = leg.trim() || "empty series";
     throw new Error(
-      `Invalid chart series "${display}". Use SYMBOL, SYMBOL:field, FUT:code, UST:maturity, FRED:series, or CAP:capability-id:series-id.`,
+      `Invalid chart series "${display}". Use SYMBOL, SYMBOL:field, FUT:code, UST:maturity, FRED:series, GEO:series, or CAP:capability-id:series-id.`,
     );
   });
 }
@@ -168,7 +182,9 @@ export function parseChartExpression(value: string): ParsedSeriesExpression[] {
 export function formatSeriesExpression(series: ChartSeriesSpec): string {
   if (series.source.kind === "economic") return `FRED:${series.source.seriesId}`;
   if (series.source.kind === "capability") {
-    return `CAP:${series.source.capabilityId}:${series.source.seriesId}`;
+    return series.source.capabilityId === GEO_SERIES_CAPABILITY_ID
+      ? formatGeoSeriesExpression(series.source.seriesId)
+      : `CAP:${series.source.capabilityId}:${series.source.seriesId}`;
   }
   return `${publicTickerKey(series.source.instrument.symbol, series.source.instrument.exchange)}:${series.source.fieldId}`;
 }

package/src/plugins/builtin/chat/channels.ts

@@ -4,6 +4,8 @@ import type { AppConfig } from "../../../types/config";
 import { t } from "../../../i18n";
 import { chatController } from "./controller";
 import { formatChannelLabel } from "./channel-labels";
+import { describeConversationStartError, knownConversationRefusal } from "./direct-messages";
+import { buildChatUserByUsername } from "./content/user-map";
 
 export const DEFAULT_CHAT_CHANNEL_ID = "everyone";
 export const LAST_VISITED_CHAT_CHANNEL_KEY = "lastChatChannelId";
@@ -87,9 +89,23 @@ export async function openDmTargetFromCommand(ctx: GloomPluginContext, usernames
     openDefaultChatPane(ctx);
     return;
   }
-  const channel = usernames.length === 1
-    ? await chatController.openDirectChannel({ username: usernames[0] })
-    : await chatController.openGroupChannel({ usernames });
+  // The command bar shows a thrown message as it is, so it says why.
+  const snapshot = chatController.getSnapshot();
+  const userByUsername = buildChatUserByUsername(snapshot.channels, snapshot.messages);
+  const refusal = knownConversationRefusal(usernames, {
+    userByUsername,
+    currentUserId: snapshot.user?.id,
+    channels: snapshot.channels,
+  });
+  if (refusal) throw new Error(refusal);
+  let channel: ChatChannel;
+  try {
+    channel = usernames.length === 1
+      ? await chatController.openDirectChannel({ username: usernames[0] })
+      : await chatController.openGroupChannel({ usernames });
+  } catch (error) {
+    throw new Error(describeConversationStartError(error, usernames, userByUsername));
+  }
   openChatChannelFromCommand(ctx, channel.id);
 }