gloomberb 0.18.3 → 0.18.4

package/src/plugins/builtin/holders/beneficial-view.tsx

@@ -14,6 +14,7 @@ import type { IssuerListingParams } from "../../../api-client/paths";
 import { useAsyncResource } from "../../../react/async-resource";
 import { useAutoRefresh } from "../../../react/auto-refresh";
 import { colors, priceColor } from "../../../theme/colors";
+import { MISSING_VALUE } from "../../../utils/format";
 import { isPlainKey } from "../../../utils/keyboard";
 import { nextHeaderSort } from "../../../utils/sort-values";
 import { usePluginAppActions, usePluginPaneState } from "../../runtime";
@@ -74,6 +75,7 @@ export function BeneficialOwnersView({
   holderRows,
   fundMatches,
   sharesOutstanding,
+  sharesOutstandingAsOf,
   onCycleView,
   onRefreshHolders,
   listing,
@@ -87,6 +89,8 @@ export function BeneficialOwnersView({
   fundMatches: ReadonlyMap<string, Holder13FMatch>;
   /** Today's shares outstanding, which a report's shares are set against when its own base is out of date. */
   sharesOutstanding?: number | null;
+  /** The day that count was taken, when it is dated. */
+  sharesOutstandingAsOf?: string | null;
   onCycleView: () => void;
   onRefreshHolders: () => void;
 }) {
@@ -161,7 +165,7 @@ export function BeneficialOwnersView({
   const renderTodayLine = useCallback((item: BeneficialItem) => (
     item.kind === "today" && item.row.today
       // Indented under its row's name; no-break spaces, which the desktop table does not collapse.
-      ? { text: `\u00a0\u00a0${formatStakeToday(item.row.today)}`, color: colors.textDim, attributes: TextAttributes.NONE }
+      ? { text: `\u00a0\u00a0${formatStakeToday(item.row.today, sharesOutstandingAsOf)}`, color: colors.textDim, attributes: TextAttributes.NONE }
       : null
   ), []);
 
@@ -204,12 +208,12 @@ export function BeneficialOwnersView({
       case "shares":
         return { text: formatOwnerShares(filing.shares), value: filing.shares, color: tone };
       case "eventDate":
-        return { text: filing.eventDate ?? "-", value: filing.eventDate, color: colors.textDim };
+        return { text: filing.eventDate ?? MISSING_VALUE, value: filing.eventDate, color: colors.textDim };
       case "filingDate":
         return { text: filing.filingDate, value: filing.filingDate, color: colors.textDim };
       case "thirteenF": {
         const action = row.thirteenF;
-        if (!action) return { text: "-", value: null, color: colors.textDim };
+        if (!action) return { text: MISSING_VALUE, value: null, color: colors.textDim };
         return { text: action.label, color: action.value === 0 ? colors.textDim : priceColor(action.value) };
       }
     }

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

@@ -28,11 +28,21 @@ export function classSharesToday(financials: Pick<TickerFinancials, "quote" | "f
   return count != null && Number.isFinite(count) && count > 0 ? count : null;
 }
 
+/** The day `classSharesToday` was counted (YYYY-MM-DD), when it is a dated 10-K or 10-Q cover count; null when undated. */
+export function classSharesAsOf(financials: Pick<TickerFinancials, "quote" | "fundamentals"> | null | undefined): string | null {
+  const fundamentals = financials?.fundamentals;
+  if (classSharesToday(financials) == null || !fundamentals?.sharesOutstandingAsOf) return null;
+  const receipt = fundamentals.shareBasis === "depositary_receipt"
+    || fundamentals.isDepositaryReceipt === true
+    || financials?.quote?.isDepositaryReceipt === true;
+  return receipt ? null : fundamentals.sharesOutstandingAsOf;
+}
+
 export async function loadHolderSnapshot(
   provider: DataProvider,
   symbol: string,
   exchange = "",
-): Promise<{ data: HolderData; marketCap?: number; sharesOutstanding?: number | null }> {
+): Promise<{ data: HolderData; marketCap?: number; sharesOutstanding?: number | null; sharesOutstandingAsOf?: string | null; price?: number }> {
   const [data, financials] = await Promise.all([
     loadHolderData(provider, symbol, exchange),
     provider.getTickerFinancials(symbol, exchange).catch(logFailure("holders.client", "Read holder reference financials failed", null)),
@@ -42,5 +52,7 @@ export async function loadHolderSnapshot(
     data,
     marketCap: holderStakeMarketCap(quote?.marketCap, quote?.currency, holderValueCurrency(data)),
     sharesOutstanding: classSharesToday(financials),
+    sharesOutstandingAsOf: classSharesAsOf(financials),
+    ...(quote?.price != null ? { price: quote.price } : {}),
   };
 }

package/src/plugins/builtin/holders/format.ts

@@ -1,9 +1,9 @@
 import type { HolderData, HolderRecord } from "../../../types/financials";
-import { formatCompact, formatPercent, formatPercentRaw } from "../../../utils/format";
+import { formatCompact, MISSING_VALUE } from "../../../utils/format";
 import type { HolderRow } from "./types";
 
 export function formatMoneyCompact(value: number | undefined, currency = "USD"): string {
-  if (value == null) return "-";
+  if (value == null) return MISSING_VALUE;
   if (currency === "USD") {
     const sign = value < 0 ? "-" : "";
     return `${sign}$${formatCompact(Math.abs(value))}`;
@@ -11,11 +11,6 @@ export function formatMoneyCompact(value: number | undefined, currency = "USD"):
   return `${formatCompact(value)} ${currency}`;
 }
 
-export function formatMaybePercent(value: number | undefined): string {
-  if (value == null) return "-";
-  return Math.abs(value) <= 1 ? formatPercent(value) : formatPercentRaw(value);
-}
-
 /**
  * The currency holder values are in. Gloom Cloud names it when it differs
  * from the listing's (dollars from 13F filings on a London line); an older
@@ -51,23 +46,39 @@ export function resolveHolderOwnershipPercent(row: Pick<HolderRecord, "percentHe
 }
 
 /**
- * A stake or a change in percent (0.59 for 0.59%), as reports carry it. A
- * source gives a fraction (0.0059) or, above 1, percent points; the pane reads
- * them the same way. Six significant digits drop a source's float noise.
+ * A holder's stake or quarter's change in percent, as the reports carry it.
+ * Every holder record gives both as a fraction: 0.0059 is a 0.59% stake,
+ * 1.086 a position that grew 108.6%, -0.6 one that fell 60%. Six significant
+ * digits drop a source's float noise.
  */
-export function holderPercent(value: number | null | undefined): number | null {
-  if (value == null || !Number.isFinite(value)) return null;
-  const percent = Math.abs(value) <= 1 ? value * 100 : value;
-  return Number(percent.toPrecision(6));
+export function holderPercent(fraction: number | null | undefined): number | null {
+  if (fraction == null || !Number.isFinite(fraction)) return null;
+  return Number((fraction * 100).toPrecision(6));
 }
 
 /** A stake in percent too small for two decimals reads "<0.01%", not a zero. */
 export function formatPercentHeld(percent: number | null | undefined): string {
-  if (percent == null) return "-";
+  if (percent == null) return MISSING_VALUE;
   if (percent > 0 && percent < 0.005) return "<0.01%";
   return `${percent.toFixed(2)}%`;
 }
 
+/**
+ * A change in percent, signed, to two decimals; from 1000% on to none, so a
+ * position that grew tenfold still fits its column.
+ */
+export function formatChangePercent(percent: number | null | undefined): string {
+  if (percent == null || !Number.isFinite(percent)) return MISSING_VALUE;
+  const fixed = Math.abs(percent).toFixed(Math.abs(percent) >= 1000 ? 0 : 2);
+  if (!/[1-9]/.test(fixed)) return `${fixed}%`;
+  return `${percent > 0 ? "+" : "-"}${fixed}%`;
+}
+
+/** A holder record's quarter's change, a fraction, as the pane shows it. */
+export function formatHolderChangePercent(fraction: number | null | undefined): string {
+  return formatChangePercent(holderPercent(fraction));
+}
+
 /** A stake too small for two decimals reads "<0.01%", not a zero. */
 export function formatHolderOwnershipPercent(value: number | undefined): string {
   return formatPercentHeld(holderPercent(value));
@@ -79,11 +90,11 @@ export function formatHolderOwnershipLine(row: HolderRow, marketCap: number | un
 }
 
 export function formatSignedCompact(value: number | undefined): string {
-  if (value == null) return "-";
+  if (value == null) return MISSING_VALUE;
   const sign = value > 0 ? "+" : "";
   return `${sign}${formatCompact(value)}`;
 }
 
 export function displayDate(value: string | undefined): string {
-  return value?.slice(0, 10) ?? "-";
+  return value?.slice(0, 10) ?? MISSING_VALUE;
 }

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

@@ -10,7 +10,7 @@ import type { HolderData } from "../../../types/financials";
 import { SEC_FILINGS } from "../shared/report-freshness";
 import type { BeneficialOwnersPayload } from "../../../api-client/beneficial-owners";
 import { fetchBeneficialOwners, type BeneficialOwnersRequest } from "./beneficial-client";
-import { resolveHeadlessIssuerListing } from "../shared/headless-market-data";
+import { resolveHeadlessInstrument, resolveHeadlessIssuerListing } from "../shared/headless-market-data";
 import type { BeneficialColumnId } from "./beneficial-model";
 import {
   beneficialCoverageNotices,
@@ -33,6 +33,15 @@ import {
   holderReportUnits,
 } from "./report-rows";
 import { REPORT_ROWS } from "../shared/headless-options";
+import {
+  HOLDER_ROWS_MAX,
+  indexedHoldersPartialNote,
+  indexedHolderUnits,
+  indexHolderTicker,
+  loadIndexedHolders,
+  withIndexedHolders,
+  type IndexedHolderList,
+} from "./index-holders";
 
 /** The same sort keys order the 13D/13G rows; `value` and `held` are the percent of class. */
 const BENEFICIAL_SORT_COLUMNS: Record<string, BeneficialColumnId> = {
@@ -50,6 +59,9 @@ interface HolderSnapshot {
   marketCap?: number;
   /** Today's shares outstanding, which a 13D/13G percent of class is set against. */
   sharesOutstanding?: number | null;
+  sharesOutstandingAsOf?: string | null;
+  /** The latest price, which values the index's holders when the source's rows give none. */
+  price?: number;
 }
 
 export interface HoldersHeadlessDependencies {
@@ -63,6 +75,12 @@ export interface HoldersHeadlessDependencies {
     request: BeneficialOwnersRequest,
     ctx: HeadlessPaneContext,
   ): Promise<BeneficialOwnersPayload>;
+  /** A US listing's largest `limit` 13F holders from the SEC holder index, as `fn 13F` pages them. */
+  loadIndexedHolders(
+    ticker: string,
+    limit: number,
+    ctx: HeadlessPaneContext,
+  ): Promise<IndexedHolderList>;
 }
 
 const defaultDependencies: HoldersHeadlessDependencies = {
@@ -75,6 +93,7 @@ const defaultDependencies: HoldersHeadlessDependencies = {
     client: ctx.apiClient,
     signal: ctx.signal,
   }),
+  loadIndexedHolders: (ticker, limit, ctx) => loadIndexedHolders(ticker, limit, ctx.signal, ctx.apiClient),
 };
 
 export function createHoldersHeadless(
@@ -108,11 +127,11 @@ export function createHoldersHeadless(
         key: "limit",
         shot: REPORT_ROWS,
         aliases: ["count", "rows"],
-        description: "Maximum holder rows.",
+        description: "Maximum holder rows, largest first. A US listing's 13F holders are every filer fn 13F lists; a listing abroad has only the source's largest few.",
         type: "integer",
         defaultValue: 25,
         minimum: 1,
-        maximum: 200,
+        maximum: HOLDER_ROWS_MAX,
       },
       {
         key: "view",
@@ -171,7 +190,7 @@ export function createHoldersHeadless(
           sharesOutstanding,
         });
         const limited = rows.slice(0, Number(args.options.limit));
-        const legend = beneficialReportLegend(limited, sharesOutstanding);
+        const legend = beneficialReportLegend(limited, sharesOutstanding, snapshot?.sharesOutstandingAsOf);
         return {
           columns: beneficialReportColumns(limited),
           rows: limited,
@@ -187,6 +206,7 @@ export function createHoldersHeadless(
             asOf: payload.asOf,
             coverage: payload.coverage,
             sharesOutstanding,
+            ...(snapshot?.sharesOutstandingAsOf ? { sharesOutstandingAsOf: snapshot.sharesOutstandingAsOf } : {}),
             notices: [
               [payload.companyName || symbol, ...beneficialListFacts(payload, form, rows.length, history)].join(" · "),
               ...(legend ? [legend] : []),
@@ -197,7 +217,25 @@ export function createHoldersHeadless(
           },
         };
       }
-      const { data, marketCap } = await dependencies.loadSnapshot(symbol, args, ctx);
+      const limit = Number(args.options.limit);
+      // Asked beside the source's list; a listing abroad (named in the key or saved with the ticker),
+      // or an index that cannot be read, keeps that list.
+      const exchange = (await resolveHeadlessInstrument(ctx, symbol)
+        .catch(logFailure("holders.headless", "Resolve the listing's venue for the 13F holder index failed", null)))?.exchange ?? "";
+      const indexTicker = indexHolderTicker(symbol, exchange);
+      const [snapshot, index] = await Promise.all([
+        dependencies.loadSnapshot(symbol, args, ctx),
+        indexTicker
+          ? dependencies.loadIndexedHolders(indexTicker, limit, ctx).catch(logFailure("holders.headless", "Load 13F holder index failed", null))
+          : null,
+      ]);
+      const { marketCap } = snapshot;
+      const indexed = !!index?.rows.length && indexHolderTicker(symbol, exchange, snapshot.data) != null;
+      const partialNote = indexed ? indexedHoldersPartialNote(index, limit) : null;
+      // Pages hold 25; another order ranks the largest `limit`, not whatever the last page held past them.
+      const data = indexed
+        ? withIndexedHolders(snapshot.data, indexTicker!, { ...index!, rows: index!.rows.slice(0, limit) }, indexedHolderUnits(snapshot.data, snapshot.price))
+        : snapshot.data;
       const currency = data.currency ?? "USD";
       // A London line's values can be dollars from the 13F filings; they are labelled and formatted as such.
       const valueCurrency = holderValueCurrency(data, currency)!;
@@ -206,15 +244,16 @@ export function createHoldersHeadless(
         direction: args.options.order === "asc" ? "asc" as const : "desc" as const,
       };
       const sorted = holderReportRows(data, { marketCap, sort });
-      const rows = sorted.slice(0, Number(args.options.limit));
+      const rows = sorted.slice(0, limit);
       const total = data.summary?.institutionsCount ?? null;
       const { notices, valueBasis, positionsBasis, changeReported } = holderReportNotices({
-        data, requested: symbol, shown: rows, reported: sorted.length, total, sort,
+        data, requested: symbol, shown: rows, reported: sorted.length, total, sort, indexed,
       });
       return {
         // A change column that is empty on every row says nothing; the notices explain it once.
         columns: holderReportColumns(rows, valueCurrency),
         rows,
+        ...(partialNote ? { complete: false, warnings: [partialNote] } : {}),
         metadata: {
           symbol: data.symbol || symbol,
           name: data.name ?? null,

package/src/plugins/builtin/holders/index-holders.ts

@@ -0,0 +1,264 @@
+import { apiClient } from "../../../api-client";
+import type { HolderData, HolderRecord } from "../../../types/financials";
+import type { TickerHoldings } from "../thirteenf/signals";
+import { logFailure } from "../../../utils/log-failure";
+import { nonUsHolderCaveat } from "./report-header";
+
+/**
+ * A US listing's 13F holders from the SEC 13F holder index, the list `fn 13F`
+ * pages through: every filer that reported the security for the latest
+ * quarter, largest first, 25 to a page. HDS shows them in the units of the
+ * source's own short list (each position at the latest price, the stake as a
+ * share of the class that list divides by), and keeps that short list for a
+ * listing abroad and whenever the index cannot be read.
+ */
+
+/** The most holder rows `fn HDS` and `holders` print. */
+export const HOLDER_ROWS_MAX = 200;
+
+/** One filer's position in the security, summed over the ticker's CUSIPs. */
+export interface IndexedHolder {
+  cik: string;
+  name: string;
+  shares: number;
+  /** Shares at the prior quarter end: 0 for a new position, undefined when unknown. */
+  previousShares?: number;
+}
+
+/** The index's holders loaded so far. */
+export interface IndexedHolderList {
+  rows: IndexedHolder[];
+  /** The report period the positions are as of. */
+  period: string;
+  /** Every filer that holds the security at the period end. */
+  holderCount: number;
+  hasMore: boolean;
+  nextOffset: number;
+  /** A later page failed: the rows are the ones loaded before it, short of the limit asked. */
+  partial?: boolean;
+}
+
+const usTicker = /^[A-Z0-9]{1,10}(\.[A-Z]{1,2})?$/;
+
+/**
+ * The ticker to ask the index for, or null when the listing is not a US
+ * line: a venue abroad (typed `SAN:EPA` or given apart), another currency,
+ * or a home line whose list the service priced from the filings.
+ */
+export function indexHolderTicker(
+  symbol: string | null | undefined,
+  exchange = "",
+  data?: Pick<HolderData, "exchange" | "currency" | "valueBasis"> | null,
+): string | null {
+  const [bare = "", typed = ""] = (symbol ?? "").trim().toUpperCase().split(":");
+  const ticker = bare.replace(/[/-]/g, ".");
+  if (!usTicker.test(ticker)) return null;
+  if (nonUsHolderCaveat(typed || exchange, null) != null) return null;
+  if (data && (data.valueBasis === "period_end_price" || nonUsHolderCaveat(data.exchange, data.currency ?? "USD") != null)) return null;
+  return ticker;
+}
+
+/**
+ * One page of the index's holders. Rows that exited during the quarter, and
+ * option or principal positions, are not holders of the shares; the pages
+ * list the period's holders before its exits, so the list ends where the
+ * holder count does.
+ */
+export function indexedHolderPage(holdings: TickerHoldings): IndexedHolderList {
+  const byCik = new Map<string, IndexedHolder & { previousKnown: boolean }>();
+  for (const row of holdings.rows) {
+    const type = row.type.trim().toUpperCase();
+    if (row.action === "exit" || (type && type !== "SH")) continue;
+    if (row.shares == null || !(row.shares > 0)) continue;
+    const previous = typeof row.previousShares === "number" ? row.previousShares : null;
+    const current = byCik.get(row.cik);
+    if (!current) {
+      byCik.set(row.cik, {
+        cik: row.cik,
+        name: row.fund,
+        shares: row.shares,
+        previousShares: previous ?? undefined,
+        previousKnown: previous != null,
+      });
+      continue;
+    }
+    // Two CUSIPs under one ticker (a re-issued one) are one position.
+    current.shares += row.shares;
+    current.previousKnown &&= previous != null;
+    current.previousShares = current.previousKnown ? (current.previousShares ?? 0) + previous! : undefined;
+  }
+  return {
+    rows: [...byCik.values()].map(({ previousKnown: _known, ...row }) => row),
+    period: holdings.period,
+    holderCount: holdings.holderCount,
+    hasMore: holdings.hasMore && holdings.nextOffset < holdings.holderCount,
+    nextOffset: holdings.nextOffset,
+  };
+}
+
+/** Rows the service gives a page, as `fn 13F` asks for them. */
+const INDEX_PAGE_ROWS = 25;
+/**
+ * Pages one list reads at most: twice what the most rows take, for pages
+ * whose options and exits leave fewer holders, and never without end.
+ */
+const INDEX_PAGES_MAX = Math.ceil(HOLDER_ROWS_MAX / INDEX_PAGE_ROWS) * 2;
+
+/** The client the pages come through; headless reports pass their own. */
+export type IndexedHolderClient = Pick<typeof apiClient, "getCloudSec13F">;
+
+/** One page of 25, as `fn 13F` asks for it, so the two share the service's copy. */
+export async function loadIndexedHolderPage(
+  ticker: string,
+  offset: number,
+  signal?: AbortSignal,
+  client: IndexedHolderClient = apiClient,
+): Promise<IndexedHolderList> {
+  signal?.throwIfAborted();
+  const holdings = await client.getCloudSec13F("ticker-holdings", { tickers: ticker, offset, limit: INDEX_PAGE_ROWS }, { signal }) as TickerHoldings;
+  signal?.throwIfAborted();
+  if (!Array.isArray(holdings?.rows) || typeof holdings.period !== "string") throw new Error(`13F holders of ${ticker} are unreadable`);
+  const page = indexedHolderPage(holdings);
+  // A page that does not move the offset on ends the list, or it would be asked for again and again.
+  return page.nextOffset > offset ? page : { ...page, hasMore: false };
+}
+
+/** Later pages after the first; a page of another period starts the list over. */
+function appendIndexedHolders(current: IndexedHolderList, page: IndexedHolderList): IndexedHolderList {
+  if (current.period !== page.period) return page;
+  const seen = new Set(current.rows.map((row) => row.cik));
+  return { ...page, rows: [...current.rows, ...page.rows.filter((row) => !seen.has(row.cik))] };
+}
+
+/**
+ * The largest `limit` holders, paging as far as that takes, never more than
+ * `INDEX_PAGES_MAX` pages. A later page that fails keeps the holders already
+ * loaded, marked partial; only a first page that fails leaves the source's list.
+ */
+export async function loadIndexedHolders(
+  ticker: string,
+  limit: number,
+  signal?: AbortSignal,
+  client: IndexedHolderClient = apiClient,
+): Promise<IndexedHolderList> {
+  let list = await loadIndexedHolderPage(ticker, 0, signal, client);
+  for (let pages = 1; list.hasMore && list.rows.length < limit && pages < INDEX_PAGES_MAX; pages += 1) {
+    const offset = list.nextOffset;
+    let page: IndexedHolderList;
+    try {
+      page = await loadIndexedHolderPage(ticker, offset, signal, client);
+    } catch (error) {
+      if (signal?.aborted) throw error;
+      logFailure("holders.index", "Read a later page of the 13F holder index failed", null)(error);
+      return { ...list, partial: true };
+    }
+    list = appendIndexedHolders(list, page);
+  }
+  return list;
+}
+
+/** What a list cut short by a failed page says, when it holds fewer rows than were asked for. */
+export function indexedHoldersPartialNote(list: IndexedHolderList | null | undefined, limit: number): string | null {
+  if (!list?.partial || list.rows.length >= limit) return null;
+  return `13F holders past the largest ${list.rows.length} could not be read this time.`;
+}
+
+/** How the source's own rows value and divide a position, which the index's rows take on. */
+export interface IndexedHolderUnits {
+  /** The price a position's shares are valued at. */
+  price?: number;
+  /**
+   * The share count a stake is a share of. The source divides by the class
+   * the line trades (PBR's receipts stand for the common shares alone), not
+   * by every share the company has.
+   */
+  classShares?: number;
+}
+
+function median(values: number[]): number | undefined {
+  if (values.length === 0) return undefined;
+  const sorted = [...values].sort((left, right) => left - right);
+  const middle = Math.floor(sorted.length / 2);
+  return sorted.length % 2 ? sorted[middle] : (sorted[middle - 1]! + sorted[middle]!) / 2;
+}
+
+/**
+ * The units of the source's list: its rows' price (shares times the latest
+ * price), else the quote's, and the count its stakes divide by. The stakes
+ * are rounded to four places, so the count is taken over all of them, where
+ * the largest weigh most.
+ */
+export function indexedHolderUnits(data: HolderData | null | undefined, quotePrice?: number | null): IndexedHolderUnits {
+  const rows = (data?.holders ?? []).filter((row) => row.ownerType === "institution" && row.shares != null && row.shares > 0);
+  const price = median(rows.flatMap((row) => (row.value != null && row.value > 0 ? [row.value / row.shares!] : [])))
+    ?? (quotePrice != null && Number.isFinite(quotePrice) && quotePrice > 0 ? quotePrice : undefined);
+  const staked = rows.filter((row) => row.percentHeld != null && row.percentHeld > 0);
+  const held = staked.reduce((sum, row) => sum + row.percentHeld!, 0);
+  const classShares = held > 0 ? staked.reduce((sum, row) => sum + row.shares!, 0) / held : undefined;
+  return {
+    ...(price != null ? { price } : {}),
+    ...(classShares != null && Number.isFinite(classShares) ? { classShares } : {}),
+  };
+}
+
+/** The source's rows of the period by their shares, where only one row has that many. */
+function sourceRowsByShares(source: readonly HolderRecord[], period: string): Map<number, HolderRecord> {
+  const counts = new Map<number, number>();
+  for (const row of source) if (row.reportDate === period && row.shares != null) counts.set(row.shares, (counts.get(row.shares) ?? 0) + 1);
+  return new Map(source.flatMap((row) => row.reportDate === period && row.shares != null && counts.get(row.shares) === 1 ? [[row.shares, row]] : []));
+}
+
+/**
+ * The index's filers as holder rows. A filer whose position is exactly one of
+ * the source's rows keeps that row's value and stake, so the largest holders
+ * read as they did; the others are valued and divided in the same units.
+ */
+function indexedHolderRecords(
+  rows: readonly IndexedHolder[],
+  period: string,
+  units: IndexedHolderUnits,
+  source: readonly HolderRecord[] = [],
+): HolderRecord[] {
+  const known = sourceRowsByShares(source, period);
+  return rows.map((row) => {
+    const change = row.previousShares == null ? undefined : row.shares - row.previousShares;
+    const same = known.get(row.shares);
+    const value = same?.value ?? (units.price != null ? Math.round(row.shares * units.price) : undefined);
+    const percentHeld = same?.percentHeld ?? (units.classShares != null ? row.shares / units.classShares : undefined);
+    return {
+      ownerType: "institution",
+      // The source's spelling of the same holder, not the filer's capitals.
+      name: same?.name ?? row.name,
+      cik: row.cik,
+      reportDate: period,
+      shares: row.shares,
+      ...(value != null ? { value } : {}),
+      ...(percentHeld != null ? { percentHeld } : {}),
+      ...(change != null ? { changeShares: change } : {}),
+      // A fraction of the prior position, as every holder record carries it; a new one has none.
+      ...(change != null && row.previousShares! > 0
+        ? { changePercent: Math.round((change / row.previousShares!) * 1e6) / 1e6 }
+        : {}),
+    };
+  });
+}
+
+/**
+ * The holder list with the index's filers in place of the source's few: the
+ * listing's facts and units as the source gave them, the index's period and
+ * count.
+ */
+export function withIndexedHolders(
+  data: HolderData | null | undefined,
+  symbol: string,
+  list: IndexedHolderList,
+  units: IndexedHolderUnits,
+): HolderData {
+  return {
+    ...(data ?? { symbol, currency: "USD" }),
+    asOf: list.period,
+    holders: indexedHolderRecords(list.rows, list.period, units, data?.holders),
+    summary: { ...data?.summary, institutionsCount: list.holderCount },
+    ...(units.price != null ? { valueBasis: "latest_price" as const } : {}),
+  };
+}