gloomberb 0.16.0 → 0.16.2

package/src/plugins/builtin/holders/beneficial-client.ts

@@ -0,0 +1,209 @@
+import { apiClient } from "../../../api-client";
+import type {
+  BeneficialOwnerFiling,
+  BeneficialOwnerReportingPerson,
+  BeneficialOwnerStatus,
+  BeneficialOwnersForm,
+  BeneficialOwnersPayload,
+} from "../../../api-client/beneficial-owners";
+import { ApiRequestError, isAccessDenied } from "../../../api-client/errors";
+import { createPluginCache } from "../../../data/plugin-cache";
+import { finiteOrNull, recordOrNull } from "../../../utils/guards";
+import { cachedCloudResource, loadCloudResource, type CloudResource } from "../shared/cloud-resource";
+import { CLOUD_SESSION_REQUIRED } from "../shared/research-cloud-session";
+
+/** One page of the route; the loader follows `nextOffset` until it has every report. */
+const PAGE_SIZE = 100;
+/** More than any issuer has filers; a history this long is cut and marked incomplete. */
+const MAX_ROWS = 2_000;
+
+export const beneficialOwnersCache = createPluginCache<BeneficialOwnersPayload>({
+  kind: "beneficial-owners",
+  source: "gloom-cloud",
+  schemaVersion: 1,
+  policy: { staleMs: 30 * 60_000, expireMs: 7 * 24 * 60 * 60_000 },
+});
+
+export interface BeneficialOwnersRequest {
+  form?: BeneficialOwnersForm;
+  /** Every report instead of the latest per filer. */
+  history?: boolean;
+}
+
+type BeneficialOwnersClient = Pick<typeof apiClient, "getCloudSecBeneficialOwners">;
+
+const text = (value: unknown): string | null => typeof value === "string" && value.trim() ? value.trim() : null;
+const isoDate = (value: unknown): string | null => {
+  const raw = text(value);
+  return raw && /^\d{4}-\d{2}-\d{2}/.test(raw) ? raw.slice(0, 10) : null;
+};
+const cikOrNull = (value: unknown): string | null => {
+  const raw = typeof value === "number" ? String(value) : text(value);
+  return raw && /\d/.test(raw) ? raw : null;
+};
+
+function normalizeReportingPerson(value: unknown): BeneficialOwnerReportingPerson | null {
+  const raw = recordOrNull(value);
+  const name = text(raw?.name);
+  if (!raw || !name) return null;
+  return { name, cik: cikOrNull(raw.cik), percentOfClass: finiteOrNull(raw.percentOfClass), shares: finiteOrNull(raw.shares) };
+}
+
+const STATUSES: readonly BeneficialOwnerStatus[] = ["holder", "below-threshold", "exited"];
+
+/**
+ * A report as the table can trust it. Fields the route adds later pass
+ * through; a report without a filer, accession or filing date is dropped,
+ * and a number that is not one stays null instead of being guessed. History
+ * reports carry no previous report or status, and none is made up for them.
+ */
+function normalizeBeneficialOwnerFiling(value: unknown): BeneficialOwnerFiling | null {
+  const raw = recordOrNull(value);
+  if (!raw) return null;
+  const filerName = text(raw.filerName);
+  const accessionNumber = text(raw.accessionNumber);
+  const filingDate = isoDate(raw.filingDate);
+  const form = text(raw.form) ?? "";
+  const kind = raw.kind === "13D" || raw.kind === "13G" ? raw.kind
+    : /13D/i.test(form) ? "13D" : /13G/i.test(form) ? "13G" : null;
+  if (!filerName || !accessionNumber || !filingDate || !kind) return null;
+  const source = raw.source === "xml" || raw.source === "text" ? raw.source : "index";
+  return {
+    ...raw,
+    filerCik: cikOrNull(raw.filerCik),
+    filerName,
+    form: form || `SCHEDULE ${kind}`,
+    kind,
+    amendment: raw.amendment === true || /\/A\b/i.test(form),
+    amendmentNo: finiteOrNull(raw.amendmentNo),
+    percentOfClass: finiteOrNull(raw.percentOfClass),
+    shares: finiteOrNull(raw.shares),
+    classTitle: text(raw.classTitle),
+    cusip: text(raw.cusip),
+    eventDate: isoDate(raw.eventDate),
+    filingDate,
+    accessionNumber,
+    filingUrl: text(raw.filingUrl) ?? "",
+    previousPercent: "previousPercent" in raw ? finiteOrNull(raw.previousPercent) : undefined,
+    previousFilingDate: "previousFilingDate" in raw ? isoDate(raw.previousFilingDate) : undefined,
+    status: STATUSES.includes(raw.status as BeneficialOwnerStatus) ? raw.status as BeneficialOwnerStatus : undefined,
+    provisional: raw.provisional === true ? true : undefined,
+    source,
+    reportingPersons: Array.isArray(raw.reportingPersons)
+      ? raw.reportingPersons.map(normalizeReportingPerson).filter((person) => person != null)
+      : [],
+  };
+}
+
+function normalizeFilings(value: unknown): BeneficialOwnerFiling[] {
+  return Array.isArray(value)
+    ? value.map(normalizeBeneficialOwnerFiling).filter((filing) => filing != null)
+    : [];
+}
+
+function normalizeBeneficialOwnersPayload(value: unknown, ticker: string): BeneficialOwnersPayload {
+  const raw = recordOrNull(value);
+  if (!raw || !Array.isArray(raw.owners)) throw new Error("The server returned an invalid 13D/13G list");
+  const coverage = recordOrNull(raw.coverage);
+  const nextOffset = finiteOrNull(raw.nextOffset);
+  return {
+    ...raw,
+    ticker: text(raw.ticker) ?? ticker,
+    cik: cikOrNull(raw.cik) ?? "",
+    companyName: text(raw.companyName) ?? "",
+    asOf: text(raw.asOf),
+    owners: normalizeFilings(raw.owners),
+    ...(Array.isArray(raw.filings) ? { filings: normalizeFilings(raw.filings) } : {}),
+    hasMore: raw.hasMore === true && nextOffset != null,
+    nextOffset,
+    coverage: coverage ? {
+      ...coverage,
+      from: isoDate(coverage.from),
+      filings: finiteOrNull(coverage.filings) ?? 0,
+      parsed: finiteOrNull(coverage.parsed) ?? 0,
+      unparsed: finiteOrNull(coverage.unparsed) ?? 0,
+      unavailable: finiteOrNull(coverage.unavailable) ?? 0,
+    } : null,
+  };
+}
+
+function describeFailure(error: unknown, ticker: string): unknown {
+  if (isAccessDenied(error)) return new Error(CLOUD_SESSION_REQUIRED);
+  // An unknown ticker, and a server that does not serve the route yet.
+  if (error instanceof ApiRequestError && error.status === 404) {
+    return new Error(`13D/13G filings are not available for ${ticker}.`);
+  }
+  return error;
+}
+
+/**
+ * Every page of the issuer's reports: the latest per filer, or with
+ * `history` every report. A list cut at the row cap keeps `hasMore`.
+ */
+export async function fetchBeneficialOwners(
+  ticker: string,
+  { form = "all", history = false }: BeneficialOwnersRequest = {},
+  { client = apiClient, signal }: { client?: BeneficialOwnersClient; signal?: AbortSignal } = {},
+): Promise<BeneficialOwnersPayload> {
+  const symbol = ticker.trim().toUpperCase();
+  try {
+    let offset = 0;
+    let first: BeneficialOwnersPayload | null = null;
+    const owners: BeneficialOwnerFiling[] = [];
+    const filings: BeneficialOwnerFiling[] = [];
+    for (;;) {
+      const page = normalizeBeneficialOwnersPayload(await client.getCloudSecBeneficialOwners({
+        ticker: symbol,
+        form,
+        history,
+        limit: PAGE_SIZE,
+        offset,
+      }, { signal }), symbol);
+      first ??= page;
+      owners.push(...page.owners);
+      filings.push(...(page.filings ?? []));
+      const loaded = history ? filings.length : owners.length;
+      const nextOffset = page.nextOffset ?? 0;
+      if (!page.hasMore || nextOffset <= offset || loaded >= MAX_ROWS) {
+        return {
+          ...first,
+          asOf: page.asOf ?? first.asOf,
+          coverage: page.coverage ?? first.coverage,
+          owners: dedupe(owners),
+          ...(history ? { filings: dedupe(filings) } : {}),
+          hasMore: page.hasMore,
+          nextOffset: page.nextOffset,
+        };
+      }
+      offset = nextOffset;
+    }
+  } catch (error) {
+    throw describeFailure(error, symbol);
+  }
+}
+
+/** Pages can overlap when a report lands between two requests. */
+function dedupe(rows: BeneficialOwnerFiling[]): BeneficialOwnerFiling[] {
+  const seen = new Set<string>();
+  return rows.filter((row) => {
+    const key = `${row.accessionNumber}:${row.filerCik ?? row.filerName}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+const cacheKey = (ticker: string) => ticker.trim().toUpperCase();
+
+export function cachedBeneficialOwners(ticker: string): CloudResource<BeneficialOwnersPayload> | null {
+  return cachedCloudResource(beneficialOwnersCache, cacheKey(ticker));
+}
+
+/** The pane's list: the latest report per filer, both kinds, cached on disk. */
+export async function loadBeneficialOwners(ticker: string, force = false): Promise<CloudResource<BeneficialOwnersPayload>> {
+  try {
+    return await loadCloudResource(beneficialOwnersCache, cacheKey(ticker), () => fetchBeneficialOwners(ticker), { force });
+  } catch (error) {
+    throw describeFailure(error, cacheKey(ticker));
+  }
+}

package/src/plugins/builtin/holders/beneficial-model.ts

@@ -0,0 +1,279 @@
+import type { BeneficialOwnerFiling, BeneficialOwnerStatus } from "../../../api-client/beneficial-owners";
+import type { DataTableColumn } from "../../../components";
+import type { HolderRecord } from "../../../types/financials";
+import { clipToDisplayWidth, displayWidth, formatCompact } from "../../../utils/format";
+import { compareSortValues, type SortDirection } from "../../../utils/sort-values";
+import { matchFilerToHolder, type Holder13FMatch } from "./thirteenf-match";
+
+export type BeneficialColumnId =
+  | "filer"
+  | "form"
+  | "percentOfClass"
+  | "change"
+  | "shares"
+  | "eventDate"
+  | "filingDate"
+  | "thirteenF";
+export type BeneficialColumn = DataTableColumn & { id: BeneficialColumnId };
+
+export interface BeneficialSortPreference {
+  columnId: BeneficialColumnId;
+  direction: SortDirection;
+}
+
+export const DEFAULT_BENEFICIAL_SORT: BeneficialSortPreference = { columnId: "percentOfClass", direction: "desc" };
+
+/** What the filer did in its latest 13F against the quarter before. */
+export interface ThirteenFAction {
+  label: string;
+  /** The share change as a fraction of the prior position: NEW sorts first, EXIT is -1. */
+  value: number;
+}
+
+export interface BeneficialOwnerRow {
+  id: string;
+  filing: BeneficialOwnerFiling;
+  /** `13G/A`: the kind, and `/A` for an amendment. */
+  formLabel: string;
+  /** Percent points against the filer's report before this one. */
+  changePoints: number | null;
+  thirteenF: ThirteenFAction | null;
+  /** The stake the report discloses; null when the report gives neither a percentage nor shares. */
+  stake: BeneficialOwnerStatus | null;
+}
+
+/** Holder rows the 13F join reads: the Table tab's rows, keyed by their id. */
+type JoinableHolder = HolderRecord & { id: string };
+
+/** The Schedule 13D/13G reporting threshold, in percent of the class. */
+const REPORTING_THRESHOLD = 5;
+
+/**
+ * The stake a report discloses, from its own figures first, as the route
+ * reads them. A stake under 5% is still a stake; only a report whose figures
+ * are all zero (0% and zero shares, or one of them with the other missing)
+ * is an exit, and a contradictory one is not. A report with neither figure
+ * keeps the route's word for a stake under the threshold, but is never read
+ * as an exit.
+ */
+export function disclosedStake(
+  filing: Pick<BeneficialOwnerFiling, "percentOfClass" | "shares" | "status">,
+): BeneficialOwnerStatus | null {
+  const { percentOfClass: percent, shares } = filing;
+  const reported = [percent, shares].filter((value) => value != null);
+  if (reported.length > 0 && reported.every((value) => value === 0)) return "exited";
+  if (percent != null) return percent < REPORTING_THRESHOLD ? "below-threshold" : "holder";
+  return filing.status === "holder" || filing.status === "below-threshold" ? filing.status : null;
+}
+
+function signedPercent(fraction: number): string {
+  const rounded = Math.round(fraction * 100);
+  return rounded > 0 ? `+${rounded}%` : rounded < 0 ? `${rounded}%` : "0%";
+}
+
+/**
+ * The quarter's action from a 13F holder row. A position that grew from
+ * nothing is NEW, one reported at zero shares after a sale EXIT; without a
+ * reported change it is unknown, never "no change".
+ */
+export function thirteenFAction(holder: HolderRecord | undefined): ThirteenFAction | null {
+  if (!holder) return null;
+  const { shares, changeShares, changePercent } = holder;
+  if (shares === 0 && changeShares != null && changeShares < 0) return { label: "EXIT", value: -1 };
+  if (shares != null && changeShares != null) {
+    const prior = shares - changeShares;
+    if (changeShares > 0 && prior === 0) return { label: "NEW", value: Number.POSITIVE_INFINITY };
+    if (prior > 0) return { label: signedPercent(changeShares / prior), value: changeShares / prior };
+  }
+  if (changePercent != null && Number.isFinite(changePercent)) {
+    // The Table tab reads a provider's change the same way: a fraction up to 1, percent points above.
+    const fraction = Math.abs(changePercent) <= 1 ? changePercent : changePercent / 100;
+    return { label: signedPercent(fraction), value: fraction };
+  }
+  return null;
+}
+
+function beneficialFormLabel(filing: Pick<BeneficialOwnerFiling, "kind" | "amendment">): string {
+  return `${filing.kind}${filing.amendment ? "/A" : ""}`;
+}
+
+function pointChange(filing: BeneficialOwnerFiling): number | null {
+  if (filing.percentOfClass == null || filing.previousPercent == null) return null;
+  return Math.round((filing.percentOfClass - filing.previousPercent) * 100) / 100;
+}
+
+/**
+ * One row per report, joined to the filer's 13F holder row (CIK first, then
+ * name) for the quarter's action.
+ */
+export function buildBeneficialRows(
+  filings: readonly BeneficialOwnerFiling[],
+  holders: readonly JoinableHolder[] = [],
+  fundMatches: ReadonlyMap<string, Pick<Holder13FMatch, "cik">> = new Map(),
+): BeneficialOwnerRow[] {
+  return filings.map((filing) => ({
+    id: `${filing.accessionNumber}:${filing.filerCik ?? filing.filerName}`,
+    filing,
+    formLabel: beneficialFormLabel(filing),
+    changePoints: pointChange(filing),
+    thirteenF: thirteenFAction(matchFilerToHolder(filing, holders, fundMatches)),
+    stake: disclosedStake(filing),
+  }));
+}
+
+function sortValue(row: BeneficialOwnerRow, columnId: BeneficialColumnId): string | number | null {
+  switch (columnId) {
+    case "filer": return row.filing.filerName;
+    case "form": return row.formLabel;
+    case "percentOfClass": return row.filing.percentOfClass;
+    case "change": return row.changePoints;
+    case "shares": return row.filing.shares;
+    case "eventDate": return row.filing.eventDate;
+    case "filingDate": return row.filing.filingDate;
+    case "thirteenF": {
+      const value = row.thirteenF?.value;
+      // NEW leads a descending sort without leaving the finite range compareSortValues keeps.
+      return value == null ? null : value === Number.POSITIVE_INFINITY ? Number.MAX_SAFE_INTEGER : value;
+    }
+  }
+}
+
+/** Filers over the threshold (or not saying) first, then stakes under 5%, then exits. */
+function stakeGroup(row: BeneficialOwnerRow): number {
+  return row.stake === "exited" ? 2 : row.stake === "below-threshold" ? 1 : 0;
+}
+
+/** Sorted by the column within each stake group, whatever the direction; ties newest filing first. */
+export function sortBeneficialRows(rows: readonly BeneficialOwnerRow[], preference: BeneficialSortPreference): BeneficialOwnerRow[] {
+  return [...rows].sort((left, right) => stakeGroup(left) - stakeGroup(right)
+    || compareSortValues(sortValue(left, preference.columnId), sortValue(right, preference.columnId), preference.direction)
+    || right.filing.filingDate.localeCompare(left.filing.filingDate)
+    || left.filing.filerName.localeCompare(right.filing.filerName));
+}
+
+// Widths as the table draws them: never narrower than the header and its sort marker.
+const FORM_WIDTH = 6;
+/** `22.2%`, `4.9% <5%`, `0.0% EXIT`. */
+const PERCENT_WIDTH = 9;
+const CHANGE_WIDTH = 8;
+const SHARES_WIDTH = 8;
+const DATE_WIDTH = 10;
+const THIRTEEN_F_WIDTH = 5;
+const MIN_FILER_WIDTH = 14;
+/** The longest filer names and a group count; a wider pane keeps the figures beside the names. */
+const MAX_FILER_WIDTH = 56;
+/** Below this the event date gives its room to the filer's name; the filing date stays. */
+const EVENT_FILER_WIDTH = 20;
+
+export function buildBeneficialColumns(width: number): BeneficialColumn[] {
+  const fixed = FORM_WIDTH + PERCENT_WIDTH + CHANGE_WIDTH + SHARES_WIDTH + DATE_WIDTH + THIRTEEN_F_WIDTH;
+  // Two cells of padding and one gap after every column.
+  const roomWithEvent = width - 2 - 8 - fixed - DATE_WIDTH;
+  const showEvent = roomWithEvent >= EVENT_FILER_WIDTH;
+  const filerWidth = Math.min(MAX_FILER_WIDTH, Math.max(MIN_FILER_WIDTH, showEvent ? roomWithEvent : roomWithEvent + DATE_WIDTH + 1));
+  return [
+    { id: "filer", label: "FILER", width: filerWidth, align: "left" },
+    { id: "form", label: "FORM", width: FORM_WIDTH, align: "left" },
+    { id: "percentOfClass", label: "% CLASS", width: PERCENT_WIDTH, align: "right" },
+    { id: "change", label: "CHG", width: CHANGE_WIDTH, align: "right" },
+    { id: "shares", label: "SHARES", width: SHARES_WIDTH, align: "right" },
+    ...(showEvent ? [{ id: "eventDate" as const, label: "EVENT", width: DATE_WIDTH, align: "right" as const }] : []),
+    { id: "filingDate", label: "FILED", width: DATE_WIDTH, align: "right" },
+    { id: "thirteenF", label: "13F", width: THIRTEEN_F_WIDTH, align: "right" },
+  ];
+}
+
+/** Entity suffixes a narrow column drops before it cuts into the name itself. */
+const LEGAL_SUFFIX = /(?:[,\s]+(?:L\.?L\.?C|L\.?L\.?P|L\.?P|INC|LTD|LIMITED|CORP|CORPORATION|CO|PLC|N\.?A|S\.?A|AG|GMBH)\.?)+$/i;
+
+/**
+ * The filer's name in `width` cells, with ` +N` for the other reporting
+ * persons of a group. The entity suffix goes first, then the name is cut
+ * behind an ellipsis; the count is never cut.
+ */
+export function formatFilerName(name: string, otherPersons: number, width: number): string {
+  const suffix = otherPersons > 0 ? ` +${otherPersons}` : "";
+  const room = Math.max(1, width - displayWidth(suffix));
+  if (displayWidth(name) <= room) return `${name}${suffix}`;
+  const short = name.replace(LEGAL_SUFFIX, "").trim() || name;
+  return `${clipToDisplayWidth(short, room)}${suffix}`;
+}
+
+/** The marker after a stake that is not a 5% holding: under the threshold, or reported at zero. */
+export function stakeMarker(stake: BeneficialOwnerStatus | null): string {
+  return stake === "below-threshold" ? "<5%" : stake === "exited" ? "EXIT" : "";
+}
+
+/**
+ * A percent of class to one decimal, or two when one would round a stake
+ * under 5% up to `5.0%`: 4.96 reads `4.96%`.
+ */
+export function formatClassPercent(value: number): string {
+  const short = value.toFixed(1);
+  if (value >= REPORTING_THRESHOLD || Number(short) < REPORTING_THRESHOLD) return `${short}%`;
+  return `${(Math.floor(value * 100) / 100).toFixed(2)}%`;
+}
+
+/**
+ * The reported percent of class, as filed: `4.9%` stays `4.9%`. With
+ * `marker`, a stake under 5% reads `4.9% <5%` and a report of zero
+ * `0.0% EXIT`. A missing figure is a dash, or the bare marker when the
+ * route says which side of 5% the stake is on.
+ */
+export function formatPercentOfClass(
+  row: Pick<BeneficialOwnerRow, "stake" | "filing">,
+  { marker = false }: { marker?: boolean } = {},
+): string {
+  const value = row.filing.percentOfClass;
+  const mark = marker ? stakeMarker(row.stake) : "";
+  if (value == null) return mark || "-";
+  return mark ? `${formatClassPercent(value)} ${mark}` : formatClassPercent(value);
+}
+
+export function formatPointChange(value: number | null): string {
+  if (value == null) return "";
+  const rounded = Math.round(value * 10) / 10;
+  if (rounded === 0) return "0.0 pt";
+  return `${rounded > 0 ? "+" : ""}${rounded.toFixed(1)} pt`;
+}
+
+export function formatOwnerShares(value: number | null): string {
+  return value == null ? "-" : formatCompact(value);
+}
+
+/**
+ * A row as `holders --form` and `fn HDS --form` print it; the keys are the
+ * JSON contract. Numbers a report did not give stay null, and `status` is
+ * the disclosed stake, null when the report does not say.
+ */
+export function beneficialReportRow(row: BeneficialOwnerRow) {
+  const { filing } = row;
+  return {
+    filer: filing.filerName,
+    filerCik: filing.filerCik,
+    form: row.formLabel,
+    formType: filing.form,
+    kind: filing.kind,
+    amendment: filing.amendment,
+    amendmentNo: filing.amendmentNo,
+    percentOfClass: filing.percentOfClass,
+    previousPercent: filing.previousPercent ?? null,
+    changePoints: row.changePoints,
+    shares: filing.shares,
+    classTitle: filing.classTitle,
+    cusip: filing.cusip,
+    eventDate: filing.eventDate,
+    filingDate: filing.filingDate,
+    previousFilingDate: filing.previousFilingDate ?? null,
+    thirteenF: row.thirteenF?.label ?? null,
+    status: row.stake,
+    /** The route could not read every filing, so this may not be the filer's latest disclosure or its change may be off. */
+    provisional: filing.provisional === true,
+    parsedFrom: filing.source,
+    accessionNumber: filing.accessionNumber,
+    filingUrl: filing.filingUrl,
+    reportingPersons: filing.reportingPersons,
+  };
+}
+
+export type BeneficialReportRow = ReturnType<typeof beneficialReportRow>;

package/src/plugins/builtin/holders/beneficial-report.ts

@@ -0,0 +1,126 @@
+import type { BeneficialOwnersCoverage, BeneficialOwnersForm, BeneficialOwnersPayload } from "../../../api-client/beneficial-owners";
+import type { HolderData } from "../../../types/financials";
+import {
+  beneficialReportRow,
+  buildBeneficialRows,
+  DEFAULT_BENEFICIAL_SORT,
+  formatClassPercent,
+  formatOwnerShares,
+  formatPointChange,
+  stakeMarker,
+  sortBeneficialRows,
+  type BeneficialReportRow,
+  type BeneficialSortPreference,
+} from "./beneficial-model";
+import { buildRows } from "./table-model";
+
+/** What `holders --form` lists: the 13F table, or the 13D/13G beneficial owners. */
+export type HolderForm = "13f" | "13d" | "13g" | "all";
+export const HOLDER_FORMS: readonly HolderForm[] = ["13f", "13d", "13g", "all"];
+
+export function parseHolderForm(value: unknown): HolderForm | null {
+  const form = typeof value === "string" ? value.trim().toLowerCase() : "";
+  return (HOLDER_FORMS as readonly string[]).includes(form) ? form as HolderForm : null;
+}
+
+export function beneficialRouteForm(form: Exclude<HolderForm, "13f">): BeneficialOwnersForm {
+  return form === "13d" ? "13D" : form === "13g" ? "13G" : "all";
+}
+
+/** Text columns for the 13D/13G rows; CSV and JSON keep the raw values. */
+export const BENEFICIAL_REPORT_COLUMNS = [
+  { key: "filer", header: "Filer", maxWidth: 32 },
+  { key: "form", header: "Form" },
+  {
+    key: "percentOfClass",
+    header: "% Class",
+    align: "right" as const,
+    format: (value: unknown, row: Record<string, unknown>) => {
+      const marker = stakeMarker(row.status === "below-threshold" || row.status === "exited" ? row.status : null);
+      if (typeof value !== "number") return marker || "-";
+      return marker ? `${formatClassPercent(value)} ${marker}` : formatClassPercent(value);
+    },
+  },
+  {
+    key: "changePoints",
+    header: "Chg",
+    align: "right" as const,
+    format: (value: unknown) => formatPointChange(typeof value === "number" ? value : null),
+  },
+  {
+    key: "shares",
+    header: "Shares",
+    align: "right" as const,
+    format: (value: unknown) => formatOwnerShares(typeof value === "number" ? value : null),
+  },
+  { key: "eventDate", header: "Event", format: (value: unknown) => typeof value === "string" ? value : "-" },
+  { key: "filingDate", header: "Filed" },
+  { key: "thirteenF", header: "13F", align: "right" as const, format: (value: unknown) => typeof value === "string" ? value : "-" },
+];
+
+const filings = (count: number) => `${count} ${count === 1 ? "filing" : "filings"}`;
+
+/**
+ * What the list leaves out, a sentence each: reports that could not be read
+ * this time, and reports known only from the EDGAR index whose figures are
+ * blank.
+ */
+export function beneficialCoverageNotices(coverage: BeneficialOwnersCoverage | null | undefined): string[] {
+  if (!coverage) return [];
+  const notices: string[] = [];
+  if (coverage.unavailable) {
+    notices.push(`${coverage.unavailable} of ${filings(coverage.filings)} could not be read this time and are left out, so a filer's row may not be its latest report; a refresh retries them.`);
+  }
+  // Reports that could not be read count as unparsed too.
+  const indexOnly = Math.max(0, coverage.unparsed - (coverage.unavailable ?? 0));
+  if (indexOnly) {
+    notices.push(`Percent of class and shares are blank for ${filings(indexOnly)} known only from the EDGAR index.`);
+  }
+  return notices;
+}
+
+/** What the list covers, for the line above it: `13D/13G filings since 2022-10-09`, `11 filers`. */
+export function beneficialListFacts(
+  payload: Pick<BeneficialOwnersPayload, "coverage">,
+  form: Exclude<HolderForm, "13f">,
+  rows: number,
+  history: boolean,
+): string[] {
+  const kind = form === "all" ? "13D/13G" : form.toUpperCase();
+  const since = payload.coverage?.from ? `${kind} filings since ${payload.coverage.from}` : `${kind} filings`;
+  const count = history ? `${rows} ${rows === 1 ? "report" : "reports"}` : `${rows} ${rows === 1 ? "filer" : "filers"}`;
+  return [since, count];
+}
+
+/** Every page loaded and every filing in the window read. */
+export function beneficialListComplete(payload: Pick<BeneficialOwnersPayload, "hasMore" | "coverage">): boolean {
+  return !payload.hasMore && !payload.coverage?.unavailable && payload.coverage?.complete !== false;
+}
+
+/** No rows although filings are listed: they could not be read, which is not the same as none filed. */
+export function beneficialListUnreadable(payload: Pick<BeneficialOwnersPayload, "owners" | "coverage">): boolean {
+  return payload.owners.length === 0 && (payload.coverage?.filings ?? 0) > 0;
+}
+
+/**
+ * The rows `--form 13d|13g|all` prints: the latest report per filer by
+ * percent of class, stakes under 5% and exits after the 5% holders, or with `history` every report
+ * newest first. The 13F action joins by name to the 13F holders when they
+ * loaded; a report without one shows none.
+ */
+export function buildBeneficialReportRows(
+  payload: BeneficialOwnersPayload,
+  {
+    history = false,
+    holders = null,
+    sort = DEFAULT_BENEFICIAL_SORT,
+  }: { history?: boolean; holders?: HolderData | null; sort?: BeneficialSortPreference } = {},
+): BeneficialReportRow[] {
+  const holderRows = buildRows(holders);
+  if (history) {
+    const filings = [...(payload.filings ?? payload.owners)]
+      .sort((left, right) => right.filingDate.localeCompare(left.filingDate));
+    return buildBeneficialRows(filings, holderRows).map(beneficialReportRow);
+  }
+  return sortBeneficialRows(buildBeneficialRows(payload.owners, holderRows), sort).map(beneficialReportRow);
+}