gloomberb 0.16.2 → 0.16.4

package/src/plugins/builtin/iv-history/model.ts

@@ -31,12 +31,16 @@ export interface IvHistoryModel {
   status: IvHistoryPayload["status"];
   iv30: DatedValue[];
   iv90: DatedValue[];
+  /** Trade-close one-year IV; it starts later than IV30 and has gaps where long-dated series did not trade. */
+  iv365: DatedValue[];
   /** Same-session quote captures, drawn as points over the trade-close line. */
   quoteIv30: DatedValue[];
   hv: DatedValue[];
   spread: DatedValue[];
   stats: IvStatRow[];
   since: string | null;
+  /** Where the 1Y series starts and how deep it is, when that differs from the rest or leaves it unranked. */
+  oneYearNote: string | null;
   asOf: string | null;
   warnings: string[];
 }
@@ -76,7 +80,7 @@ function seriesStat(id: string, label: string, unit: IvStatUnit, points: readonl
     percentile: midrankPercentile(window, value), samples: window.length };
 }
 
-function byMethod(series: readonly IvPoint[], method: IvMethod, field: "iv30" | "iv90") {
+function byMethod(series: readonly IvPoint[], method: IvMethod, field: "iv30" | "iv90" | "iv365") {
   return series.filter((point) => point.method === method && point[field] != null)
     .map((point) => ({ date: utc(point.sessionDate), value: point[field] }))
     .sort((a, b) => a.date.getTime() - b.date.getTime());
@@ -119,12 +123,18 @@ export function projectIvHistory(
     value: stats?.value ?? null, date: stats?.date ?? null, method: stats?.method ?? null, low: stats?.low ?? null, high: stats?.high ?? null,
     rank: stats?.rank ?? null, percentile: stats?.percentile ?? null, samples: stats?.samples ?? 0 });
   const stats: IvStatRow[] = [fromServer("iv30", "IV 30d ATM", payload.stats.iv30)];
-  // A newer same-day quote capture is shown on its own row: its rank would mix methods.
+  // A newer quote capture is shown on its own row: its rank would mix methods.
   if (latest?.method === "quote-mid" && latest.iv30 != null && (!payload.stats.iv30 || latest.date > payload.stats.iv30.date)) {
-    stats.push({ id: "iv30-live", label: "IV 30d live", unit: "vol", value: latest.iv30, date: latest.date, method: "quote-mid",
+    stats.push({ id: "iv30-quote", label: "IV 30d quote", unit: "vol", value: latest.iv30, date: latest.date, method: "quote-mid",
       low: null, high: null, rank: null, percentile: null, samples: 0 });
   }
+  // IV1Y ranks trade closes only; until there is one, a stored quote gives its level, unranked.
+  const oneYear = payload.stats.iv365 ?? null;
   stats.push(fromServer("iv90", "IV 90d ATM", payload.stats.iv90),
+    !oneYear && latest?.iv365 != null
+      ? { id: "iv365", label: "IV 1Y ATM", unit: "vol", value: latest.iv365, date: latest.date, method: latest.method,
+        low: null, high: null, rank: null, percentile: null, samples: 0 }
+      : fromServer("iv365", "IV 1Y ATM", oneYear),
     seriesStat("hv", `HV ${window}`, "vol", rolling, "prices"),
     seriesStat("spread", `IV 30d - HV ${window}`, "points", spreadAll, "trade-close"),
     seriesStat("term", "IV 30d / 90d", "ratio", termAll, "trade-close"));
@@ -134,12 +144,19 @@ export function projectIvHistory(
   else if (payload.status === "unavailable" && !payload.warnings.length) warnings.push(`No listed options history found for ${payload.symbol}.`);
   if (!prices.length) warnings.push("Realized volatility unavailable: daily price history is missing.");
 
+  const tradeIv365 = byMethod(payload.series, "trade-close", "iv365");
+  const since = payload.coverage?.since ?? earliest;
+  const oneYearSince = payload.coverage?.iv365Since ?? (tradeIv365[0] ? day(tradeIv365[0].date) : null);
+  const oneYearNote = !oneYearSince ? (since ? "no IV1Y history yet" : null)
+    : oneYear?.percentile == null ? `IV1Y from ${oneYearSince}, ${tradeIv365.length} session${tradeIv365.length === 1 ? "" : "s"}`
+    : since && oneYearSince > since ? `IV1Y from ${oneYearSince}` : null;
+
   return {
     symbol: payload.symbol, status: payload.status,
-    iv30: visible(tradeIv30), iv90: visible(byMethod(payload.series, "trade-close", "iv90")),
+    iv30: visible(tradeIv30), iv90: visible(byMethod(payload.series, "trade-close", "iv90")), iv365: visible(tradeIv365),
     quoteIv30: visible(byMethod(payload.series, "quote-mid", "iv30")),
     hv, spread: visible(spreadAll), stats,
-    since: payload.coverage?.since ?? earliest, asOf: latestDate, warnings,
+    since, oneYearNote, asOf: latestDate, warnings,
   };
 }
 
@@ -152,21 +169,50 @@ export interface RichCheapRow {
   method: IvMethod | null;
   rank: number | null;
   percentile: number | null;
-  /** Session the rank belongs to (latest trade close). */
+  /** Trade close the rank is measured on: the newest trade-close session, which a newer quote reading can be ahead of. */
   rankDate: string | null;
   termSlope: number | null;
+  /** The latest reading's one-year IV, dated with IV30. */
+  iv1y: number | null;
+  /**
+   * IV1Y percentile on the close IVR and IVP are ranked on. Empty when the 1Y
+   * series has no reading that session, or there is no IV1Y beside it to describe.
+   */
+  iv1yPercentile: number | null;
   skew: number | null;
+  /** Session of the quote capture the skew comes from. */
+  skewDate: string | null;
   hv: number | null;
   ivHv: number | null;
   verdict: RichCheap;
 }
 
-/** The one reading date every screened row shares, shown once instead of per row. */
-export function sharedReading(rows: readonly RichCheapRow[]): { date: string; method: IvMethod | null } | null {
-  const dated = rows.filter((row) => row.date);
-  const first = dated[0];
-  return first && dated.every((row) => row.date === first.date && row.method === first.method)
-    ? { date: first.date!, method: first.method } : null;
+/**
+ * The dates the screened rows agree on, so each is said once instead of per
+ * row. The reading (IV30, term slope, IV/HV) and the rank (IVR, IVP) are dated
+ * apart: a quote reading can be a session ahead of the trade close its rank
+ * is measured on. A group the rows disagree on gets its own column.
+ */
+export interface RichCheapDates {
+  reading: { date: string; method: IvMethod } | null;
+  /** The trade close every ranked row is ranked on. */
+  rank: string | null;
+  /** Ranked rows are ranked on different closes. */
+  rankApart: boolean;
+  /** Some skew comes from a different session than its row's reading. */
+  skewApart: boolean;
+}
+export function richCheapDates(rows: readonly RichCheapRow[]): RichCheapDates {
+  const read = rows.filter((row) => row.date && row.method);
+  const ranked = rows.filter((row) => row.rankDate);
+  const first = read[0], firstRanked = ranked[0];
+  return {
+    reading: first && read.every((row) => row.date === first.date && row.method === first.method)
+      ? { date: first.date!, method: first.method! } : null,
+    rank: firstRanked && ranked.every((row) => row.rankDate === firstRanked.rankDate) ? firstRanked.rankDate : null,
+    rankApart: !!firstRanked && ranked.some((row) => row.rankDate !== firstRanked.rankDate),
+    skewApart: rows.some((row) => row.skew != null && row.skewDate !== row.date),
+  };
 }
 
 /** Rich or cheap against the symbol's own year: IV30 percentile at or above 80, or at or below 20. */
@@ -185,7 +231,9 @@ export function projectRichCheap(rows: readonly IvScreenRow[], hv: ReadonlyMap<s
       symbol: row.symbol, status: row.status, iv30, date: latest?.date ?? null, method: latest?.method ?? null,
       rank: row.iv30?.rank ?? null, percentile, rankDate: row.iv30?.date ?? null,
       termSlope: iv30 != null && latest?.iv90 != null ? iv30 - latest.iv90 : null,
-      skew: row.skew?.skew ?? null, hv: realized,
+      iv1y: latest?.iv365 ?? null,
+      iv1yPercentile: latest?.iv365 != null && row.iv365 && row.iv365.date === row.iv30?.date ? row.iv365.percentile : null,
+      skew: row.skew?.skew ?? null, skewDate: row.skew?.date ?? null, hv: realized,
       ivHv: iv30 != null && realized != null && realized > 0 ? iv30 / realized : null,
       verdict: verdictFor(percentile),
     };

package/src/plugins/builtin/iv-history/pane.tsx

@@ -17,6 +17,8 @@ import { loadIvHistory } from "./client";
 import { formatRank, formatStat, statSource } from "./format";
 import { HV_WINDOWS, type HvWindow, type IvLookback, type IvStatRow, projectIvHistory } from "./model";
 
+/** Pane borders, the footer's padding and its [s]urface hint. */
+const FOOTER_RESERVE = 16;
 const LOOKBACKS = [{ value: "1Y", label: "1Y" }, { value: "2Y", label: "2Y" }, { value: "ALL", label: "All" }];
 const HV_OPTIONS = HV_WINDOWS.map((window) => ({ value: String(window), label: `HV ${window}` }));
 const STAT_COLUMNS: DataTableColumn[] = [
@@ -80,14 +82,19 @@ export function IvHistoryPane({ width, height, focused }: PaneProps) {
     else return;
     event.preventDefault(); event.stopPropagation();
   }, { enabled: focused });
+  // In a pane too narrow for the whole footer, the history start drops its prefix.
+  const sinceText = model?.since ? `trade closes since ${model.since}` : null;
+  const footerText = [sinceText, model?.oneYearNote, model?.asOf].filter(Boolean).join(" ");
+  const since = sinceText && footerText.length + FOOTER_RESERVE > width ? `since ${model!.since}` : sinceText;
   usePaneFooter("iv-history", () => ({ info: [
     ...(resource.loading ? [{ id: "loading", parts: [{ text: "loading", tone: "muted" as const }] }] : []),
-    ...(model?.since ? [{ id: "since", parts: [{ text: `trade closes since ${model.since}`, tone: "muted" as const }] }] : []),
+    ...(since ? [{ id: "since", parts: [{ text: since, tone: "muted" as const }] }] : []),
+    ...(model?.oneYearNote ? [{ id: "one-year", parts: [{ text: model.oneYearNote, tone: "muted" as const }] }] : []),
     ...(model?.asOf ? [{ id: "date", parts: [{ text: model.asOf, tone: "muted" as const }] }] : []),
   ], hints: [
     // Lookback (y) and realized window (w) keep their keys; the query bar shows them.
     ...(symbol ? [{ id: "surface", key: "s", label: "urface", onPress: openSurface }] : []),
-  ] }), [resource.loading, model?.since, model?.asOf, lookback, hvWindow, symbol]);
+  ] }), [resource.loading, since, model?.oneYearNote, model?.asOf, lookback, hvWindow, symbol]);
 
   const statsHeight = model ? model.stats.length + 1 : 0;
   const statSelection = statSelectionValue ?? model?.stats[0]?.id ?? "";
@@ -112,7 +119,7 @@ export function IvHistoryPane({ width, height, focused }: PaneProps) {
       { id: "lookback", label: "Lookback", value: lookback, options: LOOKBACKS, onChange: setLookback },
       { id: "realized", label: "Realized", value: String(hvWindow), options: HV_OPTIONS, onChange: setHvWindow },
     ]} />
-    {!symbol ? <EmptyState title="Choose a ticker." /> : <PaneStatusBody subject="implied volatility history" loading={resource.loading && !model}
+    {!symbol ? <EmptyState title="Select a ticker." /> : <PaneStatusBody subject="implied volatility history" loading={resource.loading && !model}
       error={!model ? resource.error ?? identityError ?? null : null} empty={!!model && !model.iv30.length && !model.quoteIv30.length}
       emptyTitle={model?.status === "queued" || model?.status === "backfilling" ? `Backfilling ${symbol} implied volatility history...` : undefined}>
       {model ? <>
@@ -120,6 +127,7 @@ export function IvHistoryPane({ width, height, focused }: PaneProps) {
           getItemKey={(row) => row.id} emptyStateTitle="No statistics." sortColumnId={null} sortDirection="asc"
           selection={{ kind: "id", selectedId: statSelection, getId: (row) => row.id, onChange: (id) => setStatSelection(id) }}
           getExportMetadata={() => [["symbol", model.symbol], ["as of", model.asOf], ["history since", model.since],
+            ...(model.oneYearNote ? [["IV1Y", model.oneYearNote]] : []),
             ["IV", "ATM, constant maturity, annualized"], ["HV", `${hvWindow}-session close-to-close`], ["warnings", ...notices]]}
           renderCell={(row, column) => statCell(row, column.id)} />
         <IvHistoryChart model={model} width={width} height={Math.max(6, height - 1 - statsHeight)} hvLabel={`HV ${hvWindow}`} focused={focused} />

package/src/plugins/builtin/iv-history/screen-pane.tsx

@@ -4,25 +4,32 @@ import { useAsyncResource } from "../../../react/async-resource";
 import { usePaneCollection, usePaneSettingValue, usePluginAppActions, useTickers } from "../../../public/react";
 import { useThemeColors } from "../../../theme/theme-context";
 import type { PaneProps } from "../../../types/plugin";
-import { Box } from "../../../ui";
+import { Box, Text } from "../../../ui";
+import { wrapTextLines } from "../../../utils/text-wrap";
 import { useAutoRefresh } from "../../../react/auto-refresh";
 import { compareSortValues, nextHeaderSort, type SortDirection } from "../../../utils/sort-values";
 import { loadIvScreen, loadRealizedVolatilities } from "./client";
-import { formatPoints, formatRank, formatVol, shortDate, verdictLabel } from "./format";
-import { projectRichCheap, type RichCheapRow, sharedReading, type VcaPreset } from "./model";
+import { formatPoints, formatRank, formatVol, readingLabel, sharedDates, shortDate, VCA_DEFINITIONS, verdictLabel } from "./format";
+import { projectRichCheap, type RichCheapRow, richCheapDates, type VcaPreset } from "./model";
 import { vcaUniverse } from "./universe";
 
 type SortId = keyof RichCheapRow;
 const HV_WINDOW = 20;
+/** Pane borders and the footer's own padding. */
+const FOOTER_MARGIN = 6;
 const COLUMNS: DataTableColumn[] = [
   { id: "symbol", label: "Symbol", width: 8, align: "left" },
   { id: "iv30", label: "IV30", width: 7, align: "right" },
   { id: "date", label: "As of", width: 11, align: "right" },
+  { id: "rankDate", label: "Rank as of", width: 11, align: "right" },
   { id: "rank", label: "IVR", width: 5, align: "right" },
   { id: "percentile", label: "IVP", width: 5, align: "right" },
   { id: "verdict", label: "Rich/Cheap", width: 11, align: "left" },
+  { id: "iv1y", label: "IV1Y", width: 7, align: "right" },
+  { id: "iv1yPercentile", label: "IVP1Y", width: 6, align: "right" },
   { id: "termSlope", label: "30-90", width: 7, align: "right" },
   { id: "skew", label: "25D skew", width: 9, align: "right" },
+  { id: "skewDate", label: "Skew as of", width: 11, align: "right" },
   { id: "hv", label: `HV${HV_WINDOW}`, width: 7, align: "right" },
   { id: "ivHv", label: "IV/HV", width: 6, align: "right" },
 ];
@@ -57,10 +64,19 @@ export function IvScreenPane({ width, height, focused }: PaneProps) {
     const projected = projectRichCheap(resource.data?.rows ?? [], hv);
     return projected.sort((left, right) => compareSortValues(left[sort.columnId], right[sort.columnId], sort.direction));
   }, [resource.data, hv, sort]);
-  const shared = useMemo(() => sharedReading(rows), [rows]);
-  // A shared reading date moves to the footer, and a column no row fills is left out.
-  const columns = useMemo(() => COLUMNS.filter((column) => !(column.id === "date" && shared)
-    && !(column.id === "skew" && rows.every((row) => row.skew == null))), [rows, shared]);
+  const dates = useMemo(() => richCheapDates(rows), [rows]);
+  // A date every row shares moves to the footer; a column no row fills, or whose dates agree, is left out.
+  const columns = useMemo(() => COLUMNS.filter((column) => {
+    switch (column.id) {
+      case "date": return !dates.reading;
+      case "rankDate": return dates.rankApart;
+      case "iv1y": return rows.some((row) => row.iv1y != null);
+      case "iv1yPercentile": return rows.some((row) => row.iv1yPercentile != null);
+      case "skew": return rows.some((row) => row.skew != null);
+      case "skewDate": return dates.skewApart;
+      default: return true;
+    }
+  }), [rows, dates]);
   const [selected, setSelected] = useState<string | null>(null);
   const queued = rows.filter((row) => row.status === "queued").length;
   const uncovered = rows.filter((row) => row.status !== "queued" && row.iv30 == null).length;
@@ -70,11 +86,13 @@ export function IvScreenPane({ width, height, focused }: PaneProps) {
     .filter((value): value is string => !!value);
   usePaneNoticeFooter({ registrationId: "iv-screen-notices", notices, focused });
   const openHistory = (row: RichCheapRow) => createPaneFromTemplate("iv-history-pane", { symbol: row.symbol });
+  // The full wording gives way to the short form in a pane too narrow to show the rank date.
+  const fullDatesText = useMemo(() => sharedDates(dates).join(" · "), [dates]);
+  const datesText = fullDatesText.length + FOOTER_MARGIN > width ? sharedDates(dates, true).join(" · ") : fullDatesText;
   usePaneFooter("iv-screen", () => ({ info: [
     ...(resource.loading ? [{ id: "loading", parts: [{ text: "loading", tone: "muted" as const }] }] : []),
-    ...(shared ? [{ id: "date", parts: [{ text: readingLabel(shared.date, shared.method), tone: "muted" as const }] }]
-      : resource.data?.asOf ? [{ id: "date", parts: [{ text: resource.data.asOf, tone: "muted" as const }] }] : []),
-  ] }), [resource.loading, shared, resource.data?.asOf]);
+    ...(datesText ? [{ id: "dates", parts: [{ text: datesText, tone: "muted" as const }] }] : []),
+  ] }), [resource.loading, datesText]);
   const handleKey = (event: DataTableKeyEvent): boolean => {
     if (event.ctrl || event.alt || event.meta || event.name !== "r") return false;
     void resource.reload();
@@ -84,19 +102,25 @@ export function IvScreenPane({ width, height, focused }: PaneProps) {
     switch (id) {
       case "symbol": return { text: row.symbol, color: colors.textBright };
       case "iv30": return { text: formatVol(row.iv30), color: colors.warning };
-      case "date": return { text: row.date ? readingLabel(row.date, row.method) : row.status === "queued" ? "queued" : "--",
+      case "date": return { text: row.date ? readingLabel(row.date, row.method, true) : row.status === "queued" ? "queued" : "--",
         color: colors.textDim };
+      case "rankDate": return { text: row.rankDate ? `${shortDate(row.rankDate)} close` : "--", color: colors.textDim };
       case "rank": return { text: formatRank(row.rank) };
       case "percentile": return { text: formatRank(row.percentile) };
       case "verdict": return { text: verdictLabel(row.verdict), color: row.verdict === "rich" ? colors.negative : row.verdict === "cheap" ? colors.positive : colors.textDim };
+      case "iv1y": return { text: formatVol(row.iv1y) };
+      case "iv1yPercentile": return { text: formatRank(row.iv1yPercentile) };
       case "termSlope": return { text: formatPoints(row.termSlope), color: row.termSlope != null && row.termSlope > 0 ? colors.negative : colors.text };
       case "skew": return { text: formatPoints(row.skew) };
+      case "skewDate": return { text: row.skewDate ? readingLabel(row.skewDate, "quote-mid", true) : "--", color: colors.textDim };
       case "hv": return { text: hv.has(row.symbol) ? formatVol(row.hv) : "...", color: colors.positive };
       case "ivHv": return { text: row.ivHv == null ? "--" : row.ivHv.toFixed(2) };
       default: return { text: "" };
     }
   };
   const custom = scope === "custom";
+  // The skew's sign and VIX beside IV30 are units of the figures above them, so they stay under the table.
+  const definitions = useMemo(() => VCA_DEFINITIONS.flatMap((line) => wrapTextLines(line, Math.max(1, width - 2))), [width]);
   return <Box width={width} height={height} flexDirection="column" overflow="hidden">
     <QueryBar width={width} filters={[
       { id: "universe", label: "Universe", value: VCA_SCOPE_OPTIONS.some((option) => option.value === scope) ? scope : "etfs",
@@ -106,22 +130,22 @@ export function IvScreenPane({ width, height, focused }: PaneProps) {
         onChange: setSymbolsText }] : []),
     ]} />
     <PaneStatusBody subject="volatility rich/cheap" loading={resource.loading && !resource.data} error={universe.error && !universe.instruments.length ? universe.error : !resource.data ? resource.error : null}>
-      <DataTableView<RichCheapRow> focused={focused && !symbolsActive} columns={columns} items={rows} rootWidth={width} rootHeight={Math.max(2, height - 1)}
+      <DataTableView<RichCheapRow> focused={focused && !symbolsActive} columns={columns} items={rows} rootWidth={width}
+        rootHeight={Math.max(2, height - 1 - definitions.length)}
         getItemKey={(row) => row.symbol} sortColumnId={sort.columnId} sortDirection={sort.direction} emptyStateTitle="No symbols to screen."
         onHeaderClick={(id) => setSort((current) => nextHeaderSort(current, id as SortId, { firstDirection: "desc" }))}
         selection={{ kind: "id", selectedId: selected ?? rows[0]?.symbol ?? "", getId: (row) => row.symbol, onChange: (id) => setSelected(id) }}
         onActivate={openHistory} onRootKeyDown={handleKey}
-        getExportMetadata={() => [["universe", universe.label], ["as of", resource.data?.asOf], ["IV", "30-day ATM, annualized"],
-          ["rank window", "prior 52 weeks of trade-close readings"], ["HV", `${HV_WINDOW}-session close-to-close`]]}
+        getExportMetadata={() => [["universe", universe.label], ["as of", fullDatesText || undefined],
+          ["IV", "30-day ATM, annualized"], ["IV1Y", "one-year ATM, annualized"], ["rank window", "prior 52 weeks of trade-close readings"], ["HV", `${HV_WINDOW}-session close-to-close`]]}
         renderCell={(row, column) => cell(row, column.id)} />
+      <Box flexDirection="column" paddingX={1} height={definitions.length} flexShrink={0}>
+        {definitions.map((line, index) => <Text key={index} fg={colors.textDim}>{line}</Text>)}
+      </Box>
     </PaneStatusBody>
   </Box>;
 }
 
-function readingLabel(date: string, method: RichCheapRow["method"]): string {
-  return `${shortDate(date)} ${method === "quote-mid" ? "live" : "close"}`;
-}
-
 export const VCA_SCOPE_OPTIONS = [
   { value: "etfs", label: "Index and sector ETFs" },
   { value: "megacaps", label: "US mega caps" },

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

@@ -750,7 +750,7 @@ function JobsView({ width, height, focused, companyOnly = false }: JobsViewProps
   if (!access.hasProAccess) return <HiringProWall symbol={symbol} exchange={exchange} width={width} height={height} />;
 
   if (!symbol) {
-    if (companyOnly) return <EmptyState title="No ticker selected." message="Select a ticker to see its hiring." />;
+    if (companyOnly) return <EmptyState title="Select a ticker." />;
     return <HomeView width={width} height={height} focused={focused} registrationId={registrationId} />;
   }
   return (

package/src/plugins/builtin/kelly-sizer/headless.ts

@@ -0,0 +1,149 @@
+import type { HeadlessPaneDefinition, HeadlessPaneRow } from "../../../types/headless";
+import { resolveHeadlessInstrument } from "../shared/headless-market-data";
+import { MarketDataCoordinator, resolveEntryValue } from "../../../market-data/coordinator";
+import { parseHedgeAmount } from "../options-scenario/hedge";
+import { clipPriceHistoryToRange } from "../../../time-series/history-window";
+import { formatNumber } from "../../../utils/format";
+import { buildBinaryOutcomes, solveKellyFraction } from "./model";
+import {
+  clampKellyHistoryYears,
+  estimateKellyHistoryInputs,
+  KELLY_HISTORY_DEFAULT_YEARS,
+  KELLY_HISTORY_MAX_YEARS,
+  KELLY_HISTORY_MIN_PERIODS,
+  kellyHistoryRange,
+  kellyHistoryRequest,
+  type KellyHistoryInputs,
+} from "./history";
+import { formatPct, formatSignedPct } from "./view";
+
+/** The fractions of full Kelly a report sizes, largest first. */
+const KELLY_FRACTIONS = [
+  { id: "full", label: "Full Kelly", fraction: 1 },
+  { id: "half", label: "Half Kelly", fraction: 0.5 },
+  { id: "quarter", label: "Quarter Kelly", fraction: 0.25 },
+] as const;
+
+/** The inputs a ticker's monthly returns give, as the History tab shows them. */
+function inputEntries(inputs: KellyHistoryInputs, edge: number) {
+  const payoff = inputs.downsideReturn < 0 ? inputs.upsideReturn / -inputs.downsideReturn : null;
+  return [
+    { key: "window", label: "Window", value: { start: inputs.start, end: inputs.end, months: inputs.periods },
+      formatted: `${inputs.start} to ${inputs.end}, ${inputs.periods} monthly returns` },
+    { key: "winRate", label: "Win rate", value: inputs.winProbability,
+      formatted: `${formatPct(inputs.winProbability)} (${inputs.wins} of ${inputs.periods} months up)` },
+    { key: "averageGain", label: "Average gain", value: inputs.upsideReturn, formatted: `${formatSignedPct(inputs.upsideReturn)} a month` },
+    { key: "averageLoss", label: "Average loss", value: inputs.downsideReturn, formatted: `${formatSignedPct(inputs.downsideReturn)} a month` },
+    { key: "payoffRatio", label: "Payoff ratio", value: payoff, formatted: payoff == null ? "no down month" : `${formatNumber(payoff, 2)}x` },
+    { key: "edge", label: "Edge", value: edge, formatted: `${formatSignedPct(edge)} a month` },
+  ];
+}
+
+export const kellyHeadless: HeadlessPaneDefinition<"bundle"> = {
+  shape: "bundle",
+  argument: { kind: "ticker", description: "Ticker to size" },
+  freshness: { source: "Your inputs and Gloom Cloud", status: "not-a-feed", basis: "monthly returns from daily closes", cadence: "daily", oldest: null },
+  description: "Kelly sizing for a ticker from its own monthly returns: win rate, payoff ratio and edge over a lookback, then full, half and quarter Kelly as a share of a bankroll.",
+  describe: (args) => `Kelly sizing | ${args.symbols[0] ?? ""}`,
+  discovery: {
+    dataRequirements: ["Gloom Cloud daily closes over the lookback, and the latest quote for share counts"],
+    limitations: ["Win rate, gain and loss are the ticker's own non-overlapping 21-session returns; past months are not a forecast."],
+  },
+  options: [
+    {
+      key: "bankroll",
+      type: "string",
+      settingKey: "bankroll",
+      placeholder: "amount",
+      example: "--bankroll 250000",
+      description: "Bankroll in your base currency, such as 250000, 250k or 1.5m; sizes each Kelly fraction in money.",
+      normalize: (value) => parseHedgeAmount(value, "bankroll"),
+    },
+    {
+      key: "years",
+      type: "integer",
+      settingKey: "historyYears",
+      minimum: 1,
+      maximum: KELLY_HISTORY_MAX_YEARS,
+      defaultValue: KELLY_HISTORY_DEFAULT_YEARS,
+      description: "Lookback in years for the monthly returns.",
+    },
+  ],
+  async load(args, ctx) {
+    const { symbol, exchange = "" } = await resolveHeadlessInstrument(ctx, args.symbols[0]!);
+    const years = clampKellyHistoryYears(args.options.years);
+    const range = kellyHistoryRange(years);
+    // The quote and the one history window the lookback needs load together, through the
+    // coordinator every chart reads daily closes from (the History tab's request, cache included).
+    const [entry, quote] = await Promise.all([
+      new MarketDataCoordinator(ctx.marketData).loadChart(kellyHistoryRequest({ symbol, exchange }, years), { forceRefresh: ctx.refresh }),
+      ctx.marketData.getQuote(symbol, exchange, ctx.refresh ? { cacheMode: "refresh" } : undefined).catch(() => null),
+    ]);
+    const history = clipPriceHistoryToRange(resolveEntryValue(entry) ?? [], range);
+    ctx.signal.throwIfAborted();
+    const inputs = estimateKellyHistoryInputs(history, years);
+    if (!inputs) {
+      return {
+        complete: false,
+        unavailableSymbols: [symbol],
+        errors: [`${symbol}: fewer than ${KELLY_HISTORY_MIN_PERIODS} monthly returns in the last ${years} year${years === 1 ? "" : "s"}.`],
+        sections: [],
+      };
+    }
+    const solve = solveKellyFraction(buildBinaryOutcomes(inputs.winProbability, inputs.upsideReturn, inputs.downsideReturn));
+    const bankrollValue = args.options.bankroll;
+    const bankroll = typeof bankrollValue === "number" && bankrollValue > 0 ? bankrollValue : null;
+    const baseCurrency = ctx.config.baseCurrency || "USD";
+    const price = quote && quote.price > 0 && Number.isFinite(quote.price) ? quote.price : null;
+    // Shares only when the bankroll and the price are in one currency.
+    const sharePrice = price != null && quote?.currency === baseCurrency ? price : null;
+    const rows: HeadlessPaneRow[] = KELLY_FRACTIONS.map(({ id, label, fraction }) => {
+      const share = solve.fraction * fraction;
+      const position = bankroll == null ? null : share * bankroll;
+      return {
+        id,
+        kelly: label,
+        fraction: share,
+        position,
+        shares: position != null && sharePrice != null ? Math.floor(position / sharePrice) : null,
+      };
+    });
+    const notes = [
+      ...(solve.warning ? [solve.warning] : []),
+      ...(solve.fraction === 0 ? ["No positive edge over this window: every Kelly fraction sizes nothing."] : []),
+      ...(bankroll == null ? [`Add --bankroll <amount> to size each fraction in ${baseCurrency}.`] : []),
+    ];
+    return {
+      complete: true,
+      freshness: { asOf: inputs.end },
+      notes,
+      sections: [
+        { title: "Inputs", entries: inputEntries(inputs, solve.expectedReturn) },
+        {
+          title: bankroll == null ? "Sizing" : `Sizing on ${formatNumber(bankroll, 0)} ${baseCurrency}`,
+          columns: [
+            { key: "kelly", header: "Kelly" },
+            { key: "fraction", header: "% of bankroll", align: "right", format: (value) => typeof value === "number" ? formatPct(value, 2) : "--" },
+            ...(bankroll == null ? [] : [
+              { key: "position", header: `Position ${baseCurrency}`, align: "right" as const,
+                format: (value: unknown) => typeof value === "number" ? formatNumber(value, 0) : "--" },
+              ...(sharePrice == null ? [] : [{ key: "shares", header: "Shares", align: "right" as const,
+                format: (value: unknown) => typeof value === "number" ? formatNumber(value, 0) : "--" }]),
+            ]),
+          ],
+          rows,
+        },
+      ],
+      metadata: {
+        symbol,
+        inputs,
+        expectedReturn: solve.expectedReturn,
+        expectedLogGrowth: solve.expectedLogGrowth,
+        bankroll,
+        currency: baseCurrency,
+        price: price == null ? null : { value: price, currency: quote?.currency ?? null, asOf: quote?.lastUpdated ?? null },
+        method: "Binary Kelly on non-overlapping 21-session returns: win rate, mean gain and mean loss.",
+      },
+    };
+  },
+};

package/src/plugins/builtin/kelly-sizer/history.ts

@@ -0,0 +1,80 @@
+import type { PricePoint } from "../../../types/financials";
+import type { TimeRange } from "../../../time-series/range";
+import type { ChartRequest, InstrumentRef } from "../../../market-data/request-types";
+import { getPricePointTimestamp } from "../../../utils/price-history";
+
+/** Sessions in one holding period: a month of trading days. */
+export const KELLY_HISTORY_PERIOD_SESSIONS = 21;
+export const KELLY_HISTORY_DEFAULT_YEARS = 5;
+export const KELLY_HISTORY_MAX_YEARS = 5;
+/** Fewer monthly returns than this say too little about a win rate to size on. */
+export const KELLY_HISTORY_MIN_PERIODS = 6;
+
+const YEAR_MS = 365.25 * 24 * 60 * 60_000;
+
+/** The binary inputs a ticker's own monthly returns imply over a lookback window. */
+export interface KellyHistoryInputs {
+  winProbability: number;
+  /** Mean return of the up months, as a fraction. */
+  upsideReturn: number;
+  /** Mean return of the down months, as a negative fraction (0 when none fell). */
+  downsideReturn: number;
+  /** Up months over all months. */
+  wins: number;
+  periods: number;
+  /** Close the first return starts from, and the last bar, as YYYY-MM-DD. */
+  start: string;
+  end: string;
+  years: number;
+}
+
+export function clampKellyHistoryYears(value: unknown): number {
+  const years = Math.round(Number(value));
+  return Number.isFinite(years) ? Math.min(KELLY_HISTORY_MAX_YEARS, Math.max(1, years)) : KELLY_HISTORY_DEFAULT_YEARS;
+}
+
+/** The shortest history range that covers the lookback, so a one-year window never loads five. */
+export function kellyHistoryRange(years: number): TimeRange {
+  return clampKellyHistoryYears(years) <= 1 ? "1Y" : "5Y";
+}
+
+/** The daily closes the History tab and the KELLY report both read. */
+export function kellyHistoryRequest(instrument: InstrumentRef, years: number): ChartRequest {
+  return { instrument, bufferRange: kellyHistoryRange(years), granularity: "resolution", resolution: "1d" };
+}
+
+const dateKey = (time: number) => new Date(time).toISOString().slice(0, 10);
+
+/**
+ * Win rate, mean gain and mean loss of non-overlapping 21-session returns,
+ * counted back from the last daily close so the newest month is complete.
+ * Null when the window holds fewer than `KELLY_HISTORY_MIN_PERIODS` of them.
+ */
+export function estimateKellyHistoryInputs(points: readonly PricePoint[], yearsInput: number): KellyHistoryInputs | null {
+  const years = clampKellyHistoryYears(yearsInput);
+  const closes = points
+    .map((point) => ({ time: getPricePointTimestamp(point), close: point.close }))
+    .filter((point) => Number.isFinite(point.time) && Number.isFinite(point.close) && point.close > 0)
+    .sort((left, right) => left.time - right.time);
+  const last = closes.at(-1);
+  if (!last) return null;
+  const cutoff = last.time - years * YEAR_MS;
+  const window = closes.filter((point) => point.time >= cutoff);
+  const picks: typeof window = [];
+  for (let index = window.length - 1; index >= 0; index -= KELLY_HISTORY_PERIOD_SESSIONS) picks.unshift(window[index]!);
+  const returns = picks.slice(1).map((point, index) => point.close / picks[index]!.close - 1);
+  if (returns.length < KELLY_HISTORY_MIN_PERIODS) return null;
+  const gains = returns.filter((value) => value > 0);
+  const losses = returns.filter((value) => value < 0);
+  const mean = (values: number[]) => values.length ? values.reduce((sum, value) => sum + value, 0) / values.length : 0;
+  return {
+    winProbability: gains.length / returns.length,
+    upsideReturn: mean(gains),
+    downsideReturn: mean(losses),
+    wins: gains.length,
+    periods: returns.length,
+    start: dateKey(picks[0]!.time),
+    end: dateKey(last.time),
+    years,
+  };
+}

package/src/plugins/builtin/kelly-sizer/index.tsx

@@ -2,6 +2,7 @@ import type { PaneTemplateContext, PaneTemplateCreateOptions } from "../../../ty
 import type { PluginModule } from "../plugin-module";
 import { DEFAULT_FLOATING_SIZE, KELLY_PANE_ID } from "./constants";
 import { KellySizerPane } from "./pane";
+import { kellyHeadless } from "./headless";
 
 function resolveTemplateSymbol(context: PaneTemplateContext, options?: PaneTemplateCreateOptions): string | null {
   return options?.symbol
@@ -40,6 +41,7 @@ export const positionSizerModule: PluginModule = {
         const symbol = resolveTemplateSymbol(context, options);
         return symbol ? { params: { symbol }, placement: "floating" } : null;
       },
+      headless: kellyHeadless,
     },
   ],
 };