gloomberb 0.16.4 → 0.16.6

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

@@ -6,16 +6,30 @@ import type {
 } from "../../../types/plugin";
 import { formatShortDate } from "../../../utils/datetime-format";
 import { normalizeCik } from "./api";
-import { buildFundOverlap, overlapPeriod } from "./overlap";
+import { buildFundOverlap, buildManagerEtfOverlap, overlapPeriod } from "./overlap";
+import type { FundMembersPayload, MemberFundsPayload } from "../../../api-client/members";
+import { fetchFunds, fetchMembers } from "../members/client";
+import { coveredFund } from "../members/model";
 import { appendTickerHoldings, loadCrowding, loadTickerHoldings, type CrowdingRow, type TickerHoldings } from "./signals";
 import {
   AS_FILED_VALUE,
   compareCrowding,
   crowdingForTicker,
   cutText,
-  periodText,
+  filedPeriodText,
+  filingDayText,
+  filingLagDays,
+  isOptionType,
+  isStaleFiling,
+  markedPositionType,
+  OPTION_ROWS_NOTE,
+  restatedValuesText,
+  staleFilingText,
+  staleFundsText,
   summarizeTickerHoldings,
+  THIRTEENF_LIMITS,
   THIRTEENF_MAX_LIMIT,
+  THIRTEENF_OPTIONS_NOTE,
 } from "./report-notes";
 import {
   loadBrowserRows,
@@ -31,9 +45,9 @@ import {
   buildTimelineRows,
   inferBrowserTabFromQuery,
   hasComparable13FQuarter,
-  THIRTEENF_OPTIONS_NOTE,
   isCikQuery,
   positionType,
+  quartersBehindLatest,
   sortBrowserRows,
   sortHoldingRows,
   sortTimelineRows,
@@ -87,9 +101,16 @@ const BROWSER_COLUMNS: HeadlessPaneColumn[] = [
   },
 ];
 
+/** What a 13F position report notes after its table: the filing's limits, and what the option marker means when option rows are shown. */
+function positionNotes(rows: readonly { type?: unknown }[]): string[] {
+  return [THIRTEENF_LIMITS, ...(rows.some((row) => isOptionType(row.type)) ? [OPTION_ROWS_NOTE] : [])];
+}
+
+const TYPE_COLUMN: HeadlessPaneColumn = { key: "type", header: "Type", textFormat: markedPositionType };
+
 const HOLDING_COLUMNS: HeadlessPaneColumn[] = [
   { key: "ticker", header: "Ticker" },
-  { key: "type", header: "Type" },
+  TYPE_COLUMN,
   { key: "issuer", header: "Issuer" },
   {
     key: "value",
@@ -175,9 +196,13 @@ export interface ThirteenFHeadlessDependencies {
     args: HeadlessPaneLoadArgs,
     ctx: HeadlessPaneContext,
   ): Promise<FundDetailData>;
+  /** The ETFs whose holdings files MEMB serves. */
+  loadEtfFunds?(ctx: HeadlessPaneContext): Promise<MemberFundsPayload["funds"]>;
+  /** One covered ETF's holdings file, as `fn MEMB` reads it. */
+  loadEtfHoldings?(ticker: string, ctx: HeadlessPaneContext): Promise<FundMembersPayload>;
 }
 
-const defaultDependencies: ThirteenFHeadlessDependencies = {
+const defaultDependencies: Required<ThirteenFHeadlessDependencies> = {
   loadBrowser: (tab, query, limit, _args, ctx) => loadBrowserRows(
     tab,
     query,
@@ -185,6 +210,8 @@ const defaultDependencies: ThirteenFHeadlessDependencies = {
     { limit },
   ),
   loadDetail: (cik, name, _args, ctx) => loadFundDetail(cik, name, ctx.signal),
+  loadEtfFunds: async (ctx) => (await fetchFunds(ctx.apiClient)).funds,
+  loadEtfHoldings: (ticker, ctx) => fetchMembers(ticker, ctx.apiClient),
 };
 
 const VIEW_TITLES: Record<string, string> = {
@@ -217,18 +244,22 @@ function browserTab(view: HeadlessThirteenFView, query: string): ThirteenFBrowse
   return inferBrowserTabFromQuery(query);
 }
 
-async function resolveFund(
+/**
+ * The manager a fund name or CIK names: a CIK as given, else the one fund
+ * whose name matches exactly, else the only match. `search` lists funds by
+ * name, as the 13F browser does.
+ */
+async function findThirteenFFund(
   query: string,
-  args: HeadlessPaneLoadArgs,
-  ctx: HeadlessPaneContext,
-  dependencies: ThirteenFHeadlessDependencies,
-): Promise<{ cik: string; name: string }> {
-  if (!query) throw new Error("13F holdings and filings require a fund name or CIK.");
+  search: (query: string, limit: number) => Promise<BrowserLoadResult>,
+  { exactOnly = false }: { exactOnly?: boolean } = {},
+): Promise<{ cik: string; name: string } | null> {
   if (isCikQuery(query)) return { cik: normalizeCik(query), name: query };
   // A small output limit must not hide other matching managers during lookup.
-  const result = await dependencies.loadBrowser("funds", query, 25, args, ctx);
+  const result = await search(query, 25);
   const candidates = [...new Map(result.rows.map((row) => [row.cik, row])).values()];
   const exact = candidates.filter((row) => row.name.toLocaleLowerCase() === query.toLocaleLowerCase());
+  if (exactOnly) return exact.length === 1 ? { cik: exact[0]!.cik, name: exact[0]!.name } : null;
   const fund = exact.length === 1 ? exact[0]
     : candidates.length === 1 && !result.hasMore ? candidates[0] : undefined;
   if (candidates.length === 0) throw new Error(`No 13F fund found for "${query}".`);
@@ -239,12 +270,67 @@ async function resolveFund(
   return { cik: fund.cik, name: fund.name };
 }
 
+async function resolveFund(
+  query: string,
+  args: HeadlessPaneLoadArgs,
+  ctx: HeadlessPaneContext,
+  dependencies: ThirteenFHeadlessDependencies,
+): Promise<{ cik: string; name: string }> {
+  if (!query) throw new Error("13F holdings and filings require a fund name or CIK.");
+  return (await findThirteenFFund(query, (text, limit) => dependencies.loadBrowser("funds", text, limit, args, ctx)))!;
+}
+
+/** A word that reads as a ticker (SPY, BRK.B), not a manager's name or a CIK. */
+const TICKER_WORD = /^\$?[A-Za-z]{1,5}(?:[.-][A-Za-z])?$/;
+
+type OverlapComparison =
+  | { kind: "fund"; cik: string; name: string }
+  | { kind: "etf"; symbol: string; ticker: string; name: string };
+
+/** "IVV (also SPY, SPX), IJH": the covered funds and the aliases each answers to. */
+const coveredEtfs = (funds: MemberFundsPayload["funds"]) => funds
+  .map((fund) => fund.aliases.length ? `${fund.ticker} (also ${fund.aliases.join(", ")})` : fund.ticker).join(", ");
+
+/**
+ * What `--compare` names. A ticker-like word is an ETF when MEMB has its
+ * holdings file, else a 13F manager only by its exact name; it is never
+ * matched to a manager by a partial name (SPY is not Spyglass Capital).
+ * Anything else, a CIK or a longer name, is a 13F manager as before.
+ */
+async function resolveComparison(
+  text: string,
+  args: HeadlessPaneLoadArgs,
+  ctx: HeadlessPaneContext,
+  dependencies: Required<ThirteenFHeadlessDependencies>,
+): Promise<OverlapComparison> {
+  if (isCikQuery(text) || !TICKER_WORD.test(text)) return { kind: "fund", ...await resolveFund(text, args, ctx, dependencies) };
+  const symbol = text.replace(/^\$/, "").toUpperCase();
+  let funds: MemberFundsPayload["funds"] | null = null;
+  let failure = "";
+  try {
+    funds = await dependencies.loadEtfFunds(ctx);
+  } catch (error) {
+    if (ctx.signal.aborted) throw error;
+    failure = error instanceof Error ? error.message : String(error);
+  }
+  const etf = funds ? coveredFund(funds, symbol) : undefined;
+  if (etf) return { kind: "etf", symbol, ticker: etf.ticker, name: etf.name };
+  const manager = await findThirteenFFund(text, (query, limit) => dependencies.loadBrowser("funds", query, limit, args, ctx), { exactOnly: true });
+  if (manager) return { kind: "fund", ...manager };
+  const etfs = funds ? `${symbol} is not an ETF MEMB covers (covered: ${coveredEtfs(funds)})` : `${symbol} could not be checked against MEMB's ETFs (${failure})`;
+  throw new Error(`${etfs}, and no 13F manager is named "${text}". For a manager, use its CIK or full name.`);
+}
+
+const percentText = (value: number) => `${(value * 100).toFixed(1)}%`;
+
 export function createThirteenFHeadless(
-  dependencies: ThirteenFHeadlessDependencies = defaultDependencies,
+  overrides: ThirteenFHeadlessDependencies = defaultDependencies,
 ): HeadlessPaneDefinition<"rows"> {
+  const dependencies: Required<ThirteenFHeadlessDependencies> = { ...defaultDependencies, ...overrides };
   return {
     shape: "rows",
     freshness: { ...SEC_FILINGS, basis: "13F filings", observedKey: "filedAsOfDate" },
+    discovery: { limitations: [THIRTEENF_LIMITS] },
     argument: {
       kind: "free-text",
       placeholder: "fund, ticker, or CIK",
@@ -252,9 +338,10 @@ export function createThirteenFHeadless(
       optional: true,
     },
     options: [
-      { key: "rank", description: "Crowding order.", type: "enum", values: [{ value: "new" }, { value: "exits" }, { value: "increases" }, { value: "decreases" }], defaultValue: "new" },
-      { key: "compare", description: "Second fund name or CIK for overlap.", type: "string" },
-      { key: "offset", description: "Fund offset for ticker-holdings.", type: "integer", defaultValue: 0, minimum: 0, maximum: 100000 },
+      // No defaults on view-specific options, so a flag the view does not use can be named as ignored.
+      { key: "rank", description: "Crowding order (crowding view; new when left out).", type: "enum", values: [{ value: "new" }, { value: "exits" }, { value: "increases" }, { value: "decreases" }] },
+      { key: "compare", description: "Second fund name or CIK, or an ETF ticker MEMB covers such as SPY; implies the overlap view.", type: "string" },
+      { key: "offset", description: "Fund offset for ticker-holdings (0 when left out).", type: "integer", minimum: 0, maximum: 100000 },
       {
         key: "view",
         description: "Fund browser mode or detail tab.",
@@ -287,20 +374,80 @@ export function createThirteenFHeadless(
     async load(args, ctx) {
       const query = typeof args.argument === "string" ? args.argument.trim() : "";
       const requestedView = String(args.options.view) as HeadlessThirteenFView;
+      const compare = typeof args.options.compare === "string" ? args.options.compare.trim() : "";
+      if (compare && requestedView !== "auto" && requestedView !== "overlap") {
+        throw new Error(`--compare is for the overlap view; --view ${requestedView} does not use it. Drop --view, or use --view overlap.`);
+      }
       // A ticker's holders with their positions, not the holders' whole books.
-      const view = requestedView !== "auto" ? requestedView
-        : isCikQuery(query) ? "holdings"
-          : inferBrowserTabFromQuery(query) === "byTicker" ? "ticker-holdings"
-            : requestedView;
+      const view = compare ? "overlap"
+        : requestedView !== "auto" ? requestedView
+          : isCikQuery(query) ? "holdings"
+            : inferBrowserTabFromQuery(query) === "byTicker" ? "ticker-holdings"
+              : requestedView;
+      // A flag the view does not use is named, never dropped without a word.
+      const flagNotices = [
+        compare && requestedView === "auto" ? "--compare implies --view overlap" : "",
+        args.options.rank != null && view !== "crowding" ? "--rank orders --view crowding only; ignored here" : "",
+        args.options.offset != null && view !== "ticker-holdings" ? "--offset pages a ticker's holders only; ignored here" : "",
+        query && (view === "latest" || view === "performance") ? `--view ${view} lists every manager; "${query}" is not used` : "",
+      ].filter(Boolean);
       const limit = Number(args.options.limit);
       if (view === "overlap") {
+        if (!compare) throw new Error(`13F overlap compares two holdings: add --compare <fund name, CIK or ETF ticker>, as in fn 13F ${query || "<fund or CIK>"} --compare SPY.`);
+        if (!query) throw new Error("13F overlap needs a fund name or CIK first: fn 13F <fund or CIK> --compare <fund, CIK or ETF ticker>.");
         const fund = await resolveFund(query, args, ctx, dependencies);
-        const other = await resolveFund(String(args.options.compare ?? ""), args, ctx, dependencies);
+        const other = await resolveComparison(compare, args, ctx, dependencies);
+        if (other.kind === "etf") {
+          const [first, etf] = await Promise.all([dependencies.loadDetail(fund.cik, fund.name, args, ctx), dependencies.loadEtfHoldings(other.ticker, ctx)]);
+          const overlap = buildManagerEtfOverlap(first, etf.members);
+          const period = first.latestForm?.periodOfReport ?? null;
+          const filed = first.latestForm?.filedAsOfDate ?? null;
+          const rows = overlap?.rows ?? [];
+          const cut = cutText(rows.length, limit, "positions");
+          const missing = overlap?.missing ?? [];
+          const missingNames = missing.slice(0, 5).map((row) => `${row.ticker || row.issuer} ${weight(row.weight)}`).join(", ");
+          const leftOut = overlap ? [overlap.leftOut.options ? `${overlap.leftOut.options} option line${overlap.leftOut.options === 1 ? "" : "s"}` : "", overlap.leftOut.principal ? `${overlap.leftOut.principal} principal-amount line${overlap.leftOut.principal === 1 ? "" : "s"}` : ""].filter(Boolean) : [];
+          const etfWeight = (value: unknown, row: Record<string, unknown>) => row.etfWeight == null ? "no ticker" : value === 0 ? "not held" : weight(value);
+          return {
+            columns: [{ key: "ticker", header: "Ticker" }, { key: "issuer", header: "Issuer" }, { key: "weight", header: "13F weight", align: "right", format: weight }, { key: "etfWeight", header: `${other.symbol} weight`, align: "right", format: etfWeight }, { key: "shared", header: "Shared", align: "right", format: weight }],
+            rows: rows.slice(0, limit).map((row) => ({ ...row })),
+            errors: [
+              ...(first.warnings ?? []),
+              ...(first.latestReport?.complete === false ? [`The 13F for ${period} did not load completely; weights cover the lines that did.`] : []),
+              ...(etf.stale ? [`The ${other.ticker} holdings file is stale.`] : []),
+              ...(!overlap ? ["No share positions or ETF weights to compare."] : []),
+            ],
+            freshness: { source: "SEC EDGAR and Gloom Cloud", ...(period ? { asOf: period } : {}) },
+            metadata: {
+              view, comparedWith: "etf", firstFund: first.name, cik: first.cik, secondFund: other.symbol,
+              etf: { symbol: other.symbol, ticker: other.ticker, name: other.name, asOf: etf.asOf },
+              comparedPeriod: period, filed,
+              overlap: overlap?.overlap ?? null, activeShare: overlap?.activeShare ?? null,
+              missing: missing.map((row) => ({ ticker: row.ticker || null, issuer: row.issuer, weight: row.weight, reason: row.etfWeight == null ? "no ticker" : "not held" })),
+              missingWeight: overlap?.missingWeight ?? null,
+              leftOut: overlap?.leftOut ?? null,
+              shown: Math.min(rows.length, limit), total: rows.length, truncated: rows.length > limit,
+              notices: [
+                ...flagNotices,
+                `${other.symbol} read as an ETF: ${other.name} holdings${other.ticker !== other.symbol ? ` (${other.ticker} file)` : ""}, as fn MEMB ${other.symbol} shows`,
+                ...(overlap ? [`Overlap ${percentText(overlap.overlap)} (sum of the smaller weight per name) | Active share ${percentText(overlap.activeShare)}`] : []),
+                [
+                  period ? `Quarter compared: ${filingDayText(period)}${filed ? `, filed ${filingDayText(filed)}` : ""}` : "",
+                  `${other.symbol} holdings as of ${filingDayText(etf.asOf.slice(0, 10))}`,
+                  leftOut.length ? `13F weights leave out ${leftOut.join(" and ")}` : "",
+                ].filter(Boolean).join(" | "),
+                ...(overlap ? [missing.length ? `Not in ${other.symbol}: ${missing.length} of ${rows.length} positions, ${percentText(overlap.missingWeight)} of the 13F | ${missingNames}${missing.length > 5 ? ", ..." : ""}` : `${other.symbol} holds every position in the 13F`] : []),
+                ...(cut ? [`${cut[0]!.toUpperCase()}${cut.slice(1)}`] : []),
+              ].filter(Boolean),
+            },
+          };
+        }
         const [first, second] = await Promise.all([dependencies.loadDetail(fund.cik, fund.name, args, ctx), dependencies.loadDetail(other.cik, other.name, args, ctx)]);
         const comparedPeriod = overlapPeriod(first, second);
         const rows = buildFundOverlap(first, second);
         const cut = cutText(rows.length, limit, "positions");
-        return { columns: [{ key: "ticker", header: "Ticker" }, { key: "type", header: "Type" }, { key: "issuer", header: "Issuer" }, { key: "weight", header: "First weight", align: "right", format: weight }, { key: "comparedWeight", header: "Second weight", align: "right", format: weight }], rows: rows.slice(0, limit).map(row => ({ ...row })), errors: [...(first.warnings ?? []), ...(second.warnings ?? []), ...(!comparedPeriod ? ["No reporting quarter is loaded for both funds."] : [])], metadata: { view, firstFund: first.name, secondFund: second.name, firstPeriod: first.latestForm?.periodOfReport ?? null, secondPeriod: second.latestForm?.periodOfReport ?? null, comparedPeriod, shown: Math.min(rows.length, limit), total: rows.length, truncated: rows.length > limit, notices: [[comparedPeriod ? `Quarter compared: ${comparedPeriod}` : "", cut].filter(Boolean).join(" | ")].filter(Boolean) } };
+        const read = `${compare} read as the 13F manager ${second.name} (CIK ${second.cik})`;
+        return { columns: [{ key: "ticker", header: "Ticker" }, { key: "type", header: "Type" }, { key: "issuer", header: "Issuer" }, { key: "weight", header: "First weight", align: "right", format: weight }, { key: "comparedWeight", header: "Second weight", align: "right", format: weight }], rows: rows.slice(0, limit).map(row => ({ ...row })), errors: [...(first.warnings ?? []), ...(second.warnings ?? []), ...(!comparedPeriod ? ["No reporting quarter is loaded for both funds."] : [])], metadata: { view, comparedWith: "fund", firstFund: first.name, secondFund: second.name, firstPeriod: first.latestForm?.periodOfReport ?? null, secondPeriod: second.latestForm?.periodOfReport ?? null, comparedPeriod, shown: Math.min(rows.length, limit), total: rows.length, truncated: rows.length > limit, notices: [...flagNotices, read, [comparedPeriod ? `Quarter compared: ${comparedPeriod}` : "", cut].filter(Boolean).join(" | ")].filter(Boolean) } };
       }
       if (view === "crowding") {
         const { rows: sourceRows, ...metadata } = await loadCrowding(ctx.signal);
@@ -314,7 +461,7 @@ export function createThirteenFHeadless(
         const columns: HeadlessPaneColumn[] = [{ key: "ticker", header: "Ticker" }, { key: "issuer", header: "Issuer" }, { key: "type", header: "Type" }, { key: "holderCount", header: "Funds", align: "right" }, { key: "newCount", header: "New", align: "right" }, { key: "exitCount", header: "Exits", align: "right" }, { key: "weightChange", header: "Weight change", align: "right", format: weightPoints }, { key: "comparedFunds", header: "Compared", align: "right" }, { key: "totalValue", header: "Value (USD)", align: "right", format: money }];
         const cut = cutText(rows.length, limit, "securities");
         return { columns: focus ? [{ key: "rank", header: "Rank", align: "right" }, ...columns] : columns, rows: rows.slice(0, limit).map(row => ({ ...row })),
-          metadata: { ...metadata, view, rank, ...(ticker ? { ticker, found: rows.length > 0, rankedSecurities: ranked.length } : {}), shown: Math.min(rows.length, limit), total: rows.length, truncated: rows.length > limit, notices: [[sample, cut].filter(Boolean).join(" | "), ...(focus ? [focus.notice] : [])] },
+          metadata: { ...metadata, view, rank, ...(ticker ? { ticker, found: rows.length > 0, rankedSecurities: ranked.length } : {}), shown: Math.min(rows.length, limit), total: rows.length, truncated: rows.length > limit, notices: [...flagNotices, [sample, cut].filter(Boolean).join(" | "), ...(focus ? [focus.notice] : [])] },
           freshness: { asOf: metadata.period }, errors: metadata.warnings };
       }
       let holdings: TickerHoldings | null = null;
@@ -336,9 +483,11 @@ export function createThirteenFHeadless(
         const { rows, ...metadata } = holdings;
         const offset = Number(args.options.offset ?? 0);
         const summary = summarizeTickerHoldings({ ...metadata, offset, limit, loaded: rows });
+        const shown = rows.slice(0, limit).map(row => ({ ...row }));
         return {
-          columns: [{ key: "fund", header: "Fund" }, { key: "cik", header: "CIK" }, { key: "type", header: "Type" }, { key: "value", header: "Value (USD)", align: "right", format: money }, { key: "shares", header: "Shares", align: "right", format: shares }, { key: "weight", header: "13F weight", align: "right", format: weight }, { key: "action", header: "Action" }],
-          rows: rows.slice(0, limit).map(row => ({ ...row })),
+          columns: [{ key: "fund", header: "Fund" }, { key: "cik", header: "CIK" }, TYPE_COLUMN, { key: "value", header: "Value (USD)", align: "right", format: money }, { key: "shares", header: "Shares", align: "right", format: shares }, { key: "weight", header: "13F weight", align: "right", format: weight }, { key: "action", header: "Action" }],
+          rows: shown,
+          notes: positionNotes(shown),
           metadata: {
             ...metadata,
             view,
@@ -353,7 +502,7 @@ export function createThirteenFHeadless(
             totalValue: summary.shownValue,
             valueScope: "shown funds",
             valueBasis: "as reported at period end",
-            notices: summary.notices,
+            notices: [...flagNotices, ...summary.notices],
           },
           freshness: { asOf: metadata.period },
           errors: metadata.warnings,
@@ -370,6 +519,8 @@ export function createThirteenFHeadless(
             .slice(0, limit)
             .map((row) => ({ ...row }));
           const cut = cutText(all.length, limit, "filings");
+          const shownFilings = new Set(rows.map((row) => row.accessionNumber));
+          const restated = restatedValuesText(detail.forms.filter((form) => shownFilings.has(form.accessionNumber)));
           return {
             columns: FILING_COLUMNS,
             rows,
@@ -382,7 +533,7 @@ export function createThirteenFHeadless(
               shown: rows.length,
               total: all.length,
               truncated: all.length > limit,
-              notices: [[`CIK ${detail.cik}`, cut].filter(Boolean).join(" | ")],
+              notices: [...flagNotices, [`CIK ${detail.cik}`, cut].filter(Boolean).join(" | "), ...(restated ? [restated] : [])],
             },
           };
         }
@@ -391,7 +542,17 @@ export function createThirteenFHeadless(
           DEFAULT_HOLDING_SORT,
         );
         const previousPeriod = detail.previousForm?.periodOfReport ?? null;
+        const comparable = hasComparable13FQuarter(detail);
+        const filed = detail.latestForm?.filedAsOfDate || null;
+        const quartersBehind = quartersBehindLatest(latestPeriod);
         const cut = cutText(all.length, limit, "positions, exits included");
+        // Values, weights and Est P&L read both compared quarters' filings.
+        const reportForms = (report: typeof detail.latestReport, form: typeof detail.latestForm) =>
+          report?.filings ?? (form ? [form] : []);
+        const restated = restatedValuesText([
+          ...reportForms(detail.latestReport, detail.latestForm),
+          ...(comparable ? reportForms(detail.previousReport, detail.previousForm) : []),
+        ]);
         const rows = all
           .slice(0, limit)
           .map((row) => ({
@@ -403,22 +564,33 @@ export function createThirteenFHeadless(
           columns: HOLDING_COLUMNS,
           rows,
           ...(detail.warnings?.length ? { errors: detail.warnings } : {}),
-          // Positions as of the quarter they report; the rows carry no filing date.
-          ...(latestPeriod ? { freshness: { asOf: latestPeriod } } : {}),
+          notes: positionNotes(rows),
+          // Dated by the filing that made the positions public, with the quarter they report beside it.
+          ...(latestPeriod ? { freshness: {
+            asOf: filed ?? latestPeriod,
+            basis: `13F filing for the quarter ended ${filingDayText(latestPeriod)}`,
+          } } : {}),
           metadata: {
             view,
             cik: detail.cik,
             fund: detail.name,
             latestPeriod,
+            latestFiled: filed,
+            filingLagDays: filingLagDays(latestPeriod, filed),
+            quartersBehind,
             previousPeriod,
             shown: rows.length,
             total: all.length,
             truncated: all.length > limit,
             notices: [
-              [`CIK ${detail.cik}`, periodText(latestPeriod, hasComparable13FQuarter(detail) ? previousPeriod : null), AS_FILED_VALUE].filter(Boolean).join(" | "),
+              ...flagNotices,
+              [`CIK ${detail.cik}`, filedPeriodText(latestPeriod, filed, comparable ? previousPeriod : null)].filter(Boolean).join(" | "),
+              AS_FILED_VALUE,
+              ...(restated ? [restated] : []),
+              ...(isStaleFiling(quartersBehind) ? [staleFilingText(quartersBehind)] : []),
               ...(cut ? [`${cut[0]!.toUpperCase()}${cut.slice(1)}`] : []),
             ],
-            comparisonAvailable: hasComparable13FQuarter(detail),
+            comparisonAvailable: comparable,
             currentFilings: detail.latestReport?.filings.map((form) => form.accessionNumber) ?? [],
             previousFilings: detail.previousReport?.filings.map((form) => form.accessionNumber) ?? [],
             currentReportedValue: detail.latestReport?.complete ? detail.latestReport.tableValueTotal : null,
@@ -432,11 +604,18 @@ export function createThirteenFHeadless(
       const tab = browserTab(view === "ticker-holdings" ? requestedView : view, query);
       const result = await dependencies.loadBrowser(tab, query, limit, args, ctx);
       const more = result.hasMore || result.rows.length > limit;
+      const browserRows = sortBrowserRows(result.rows, browserSortFor(DEFAULT_BROWSER_SORT, tab)).slice(0, limit);
+      // A search finds managers that stopped filing; say which, since the Period column alone reads like any other.
+      const stale = tab === "funds"
+        ? browserRows.flatMap((row) => {
+          const quarters = quartersBehindLatest(row.periodOfReport);
+          return isStaleFiling(quarters) ? [{ name: row.name, quarters }] : [];
+        })
+        : [];
       return {
         columns: result.rows[0]?.priorReturns?.length ? [...BROWSER_COLUMNS.filter(column => !["filedAsOfDate", "tableEntryTotal"].includes(column.key)), ...result.rows[0].priorReturns.map((point, index) => ({ key: `return${index + 1}`, header: point.quarter, align: "right" as const, format: (value: unknown) => formatRawPercentMaybe(typeof value === "number" ? value : null) }))]
           : tab === "performance" ? BROWSER_COLUMNS : BROWSER_COLUMNS.filter(column => column.key !== "estQuarterReturn"),
-        rows: sortBrowserRows(result.rows, browserSortFor(DEFAULT_BROWSER_SORT, tab))
-          .slice(0, limit)
+        rows: browserRows
           .map((row) => ({ ...row, ...Object.fromEntries((row.priorReturns ?? []).map((point, index) => [`return${index + 1}`, point.value])) })),
         ...(result.warning ? { errors: [result.warning] } : {}),
         metadata: {
@@ -447,9 +626,11 @@ export function createThirteenFHeadless(
           hasMore: result.hasMore ?? false,
           shown: Math.min(result.rows.length, limit),
           truncated: more,
-          notices: more
-            ? [[`Showing the first ${Math.min(result.rows.length, limit)}`, limit < THIRTEENF_MAX_LIMIT ? `more: --limit ${THIRTEENF_MAX_LIMIT}` : ""].filter(Boolean).join(" | ")]
-            : [],
+          notices: [
+            ...flagNotices,
+            ...(more ? [[`Showing the first ${Math.min(result.rows.length, limit)}`, limit < THIRTEENF_MAX_LIMIT ? `more: --limit ${THIRTEENF_MAX_LIMIT}` : ""].filter(Boolean).join(" | ")] : []),
+            ...(stale.length ? [staleFundsText(stale)] : []),
+          ],
         },
       };
     },

package/src/plugins/builtin/thirteenf/model.ts

@@ -26,7 +26,6 @@ import type {
 
 export const THIRTEENF_PANE_ID = "thirteenf-funds";
 export const THIRTEENF_TEMPLATE_ID = "thirteenf-funds-pane";
-export const THIRTEENF_OPTIONS_NOTE = "Option values and shares refer to the underlying; 13F % is share of reported value.";
 
 export const FUND_DETAIL_TABS: Array<{ label: string; value: ThirteenFDetailTab }> = [
   { label: "Holdings", value: "holdings" },
@@ -96,6 +95,45 @@ export function latestLikely13FQuarter(now = new Date()): string {
   return "";
 }
 
+function quarterIndex(period: string): number | null {
+  const match = /^(\d{4})-(\d{2})-\d{2}$/.exec(period) ?? /^(\d{4})Q([1-4])$/.exec(period);
+  if (!match) return null;
+  const year = Number(match[1]);
+  const part = Number(match[2]);
+  return year * 4 + (period.includes("Q") ? part - 1 : Math.floor((part - 1) / 3));
+}
+
+/**
+ * How many quarters a fund's latest report period trails the latest quarter
+ * filers have had time to report (`latestLikely13FQuarter`); 0 when it is
+ * current or ahead, null without a readable period.
+ */
+export function quartersBehindLatest(period: string | null | undefined, now = new Date()): number | null {
+  const latest = quarterIndex(latestLikely13FQuarter(now));
+  const own = period ? quarterIndex(period) : null;
+  return latest == null || own == null ? null : Math.max(0, latest - own);
+}
+
+/**
+ * The fund search lists a manager once for each name it has filed under
+ * ("PERSHING SQUARE HOLDCO, L.P." and "PERSHING SQUARE INC." share a CIK).
+ * One row per CIK: a renamed manager takes the name on its latest loaded
+ * filing, else the longest of its names.
+ */
+export function oneFundPerCik(
+  funds: readonly ThirteenFFund[],
+  reports?: ReadonlyMap<string, ThirteenFPeriodReport>,
+): ThirteenFFund[] {
+  const byCik = new Map<string, ThirteenFFund[]>();
+  for (const fund of funds) byCik.set(fund.cik, [...(byCik.get(fund.cik) ?? []), fund]);
+  return [...byCik.values()].map((names) => {
+    if (names.length === 1) return names[0]!;
+    const filed = reports?.get(names[0]!.cik)?.filings.at(-1)?.companyName;
+    const longest = names.reduce((best, fund) => (fund.name.length > best.name.length ? fund : best));
+    return { ...longest, name: filed || longest.name };
+  });
+}
+
 export function buildBrowserRows(options: {
   funds?: ThirteenFFund[];
   topFunds?: ThirteenFTopFund[];

package/src/plugins/builtin/thirteenf/overlap.ts

@@ -34,6 +34,81 @@ function atPeriod(data: FundDetailData, period: string): FundDetailData | null {
   return { ...data, latestForm: data.previousForm, latestReport: data.previousReport, latestHoldings: data.previousHoldings, previousForm: null, previousReport: undefined, previousHoldings: [] };
 }
 
+/** One line of an ETF's holdings file, as MEMB lists it: weight is a fraction of the fund. */
+export interface EtfHoldingLine {
+  symbol: string | null;
+  weight: number | null;
+}
+
+interface ManagerEtfRow {
+  id: string;
+  ticker: string;
+  issuer: string;
+  /** Share of the manager's 13F share positions. */
+  weight: number;
+  /** Share of the ETF: 0 when it does not hold the name, null when the 13F line has no ticker to match. */
+  etfWeight: number | null;
+  /** The smaller of the two weights: how much of this position the ETF already holds. */
+  shared: number;
+}
+
+export interface ManagerEtfOverlap {
+  /** The manager's share positions, largest first. */
+  rows: ManagerEtfRow[];
+  /** Sum of the smaller weight per name. */
+  overlap: number;
+  /** Half the summed absolute weight differences over every name either holds. */
+  activeShare: number;
+  /** The manager's positions the ETF does not hold, or that have no ticker to match, largest first. */
+  missing: ManagerEtfRow[];
+  missingWeight: number;
+  /** 13F lines left out of the weights: options, and principal amounts that are not shares. */
+  leftOut: { options: number; principal: number };
+}
+
+/** BRK.B in a 13F and BRK-B in a holdings file are one share class. */
+const symbolKey = (symbol: string) => symbol.trim().toUpperCase().replace(/[./\s]+/g, "-");
+
+/**
+ * A manager's latest 13F against an ETF's holdings file. The manager's weights
+ * cover its share positions (options and principal amounts left out), the
+ * ETF's its whole file (cash and lines without a ticker included), so both sum
+ * to one and active share is one minus the overlap.
+ */
+export function buildManagerEtfOverlap(manager: FundDetailData, etf: readonly EtfHoldingLine[]): ManagerEtfOverlap | null {
+  const lines = buildFundHoldingRows(manager).filter((row) => row.action !== "exit" && row.value != null && row.value > 0);
+  const leftOut = { options: 0, principal: 0 };
+  const positions = new Map<string, { id: string; ticker: string; issuer: string; value: number }>();
+  for (const row of lines) {
+    if (row.putCall) { leftOut.options += 1; continue; }
+    if (row.shareType.toUpperCase() === "PRN") { leftOut.principal += 1; continue; }
+    const key = row.ticker ? symbolKey(row.ticker) : `cusip:${row.cusip || row.id}`;
+    const position = positions.get(key);
+    if (position) position.value += row.value!;
+    else positions.set(key, { id: row.id, ticker: row.ticker, issuer: row.issuer, value: row.value! });
+  }
+  const total = [...positions.values()].reduce((sum, row) => sum + row.value, 0);
+  const etfWeights = new Map<string, number>();
+  let etfTotal = 0;
+  for (const line of etf) {
+    if (line.weight == null || !Number.isFinite(line.weight) || line.weight <= 0) continue;
+    etfTotal += line.weight;
+    if (line.symbol) etfWeights.set(symbolKey(line.symbol), (etfWeights.get(symbolKey(line.symbol)) ?? 0) + line.weight);
+  }
+  if (!(total > 0) || !(etfTotal > 0)) return null;
+  const rows = [...positions].map(([key, row]): ManagerEtfRow => {
+    const weight = row.value / total;
+    const etfWeight = row.ticker ? (etfWeights.get(key) ?? 0) / etfTotal : null;
+    return { id: row.id, ticker: row.ticker, issuer: row.issuer, weight, etfWeight, shared: Math.min(weight, etfWeight ?? 0) };
+  }).sort((a, b) => b.weight - a.weight);
+  const overlap = rows.reduce((sum, row) => sum + row.shared, 0);
+  // The ETF's weight in names the manager does not hold, cash and untickered lines included.
+  const etfOnly = 1 - rows.reduce((sum, row) => sum + (row.etfWeight ?? 0), 0);
+  const activeShare = (rows.reduce((sum, row) => sum + Math.abs(row.weight - (row.etfWeight ?? 0)), 0) + Math.max(0, etfOnly)) / 2;
+  const missing = rows.filter((row) => !row.etfWeight);
+  return { rows, overlap, activeShare, missing, missingWeight: missing.reduce((sum, row) => sum + row.weight, 0), leftOut };
+}
+
 export function buildFundOverlap(first: FundDetailData, second: FundDetailData): FundOverlapRow[] {
   const period = overlapPeriod(first, second);
   const left = period ? atPeriod(first, period) : null;

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

@@ -46,12 +46,14 @@ import {
   buildTimelineColumns,
   buildTimelineRows,
   inferBrowserTabFromQuery,
+  quartersBehindLatest,
   selectedIndexById,
   sortBrowserRows,
   sortFilingPositionRows,
   sortHoldingRows,
   sortTimelineRows,
 } from "./model";
+import { isOptionType, isStaleFiling, quartersOldText } from "./report-notes";
 import {
   renderBrowserCell,
   renderFilingPositionCell,
@@ -479,15 +481,22 @@ export function FundDetailView({
     }
   });
 
+  const quartersBehind = quartersBehindLatest(data?.latestForm?.periodOfReport);
+  const staleFiling = isStaleFiling(quartersBehind);
   const holdingStats: StatItem[] = [
     { id: "reported", label: "Reported", value: data?.latestForm?.periodOfReport ?? "--",
-      detail: `filed ${data?.latestForm?.filedAsOfDate || "--"}${data?.latestForm && amendmentKind(data.latestForm) === "restatement" ? ", restated" : ""}` },
+      detail: `filed ${data?.latestForm?.filedAsOfDate || "--"}${data?.latestForm && amendmentKind(data.latestForm) === "restatement" ? ", restated" : ""}${staleFiling ? `, ${quartersOldText(quartersBehind)}` : ""}`,
+      ...(staleFiling ? { tone: "warning" as const } : {}) },
     data && hasComparable13FQuarter(data)
       ? { id: "compared", label: "Compared with", value: data.previousForm!.periodOfReport }
       : { id: "compared", label: "Compared with", value: "No prior quarter", tone: "muted" },
     ...(data?.latestReport && data.latestReport.filings.length > 1
       ? [{ id: "combined", label: "Combined", value: `${data.latestReport.filings.length} filings` }]
       : []),
+    // The value basis of option rows, like a unit: only for a fund that holds them.
+    ...(holdingRows.some((row) => isOptionType(row.putCall))
+      ? [{ id: "options", label: "CALL/PUT", value: "underlying value", tone: "muted" as const }]
+      : []),
   ];
 
   usePaneNoticeFooter({