gloomberb 0.13.2 → 0.14.0

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

@@ -8,6 +8,7 @@ import type {
 } from "./types";
 import type { PluginPersistence } from "../../../types/plugin";
 import { apiClient } from "../../../api-client";
+import { ApiRequestError } from "../../../api-client/errors";
 import { httpFetch } from "../../../utils/http-transport";
 
 const FORMS_13F_BASE_URL = "https://forms13f.com/api/v1";
@@ -24,20 +25,29 @@ const FORMS_13F_CACHE_POLICY = {
   expireMs: 30 * 24 * 60 * 60_000,
 } as const;
 
-interface Forms13FRequestOptions {
-  cache?: boolean;
+export interface Forms13FReadOptions {
+  onWarning?: (warning: string) => void;
   forceRefresh?: boolean;
+}
+
+interface Forms13FRequestOptions extends Forms13FReadOptions {
+  cache?: boolean;
   signal?: AbortSignal;
 }
 
 let forms13FPersistence: PluginPersistence | null = null;
+const failedRefreshes = new Set<string>();
+const activeRequests = new Map<string, object>();
 
 export function attachThirteenFApiPersistence(persistence: PluginPersistence) {
+  if (forms13FPersistence !== persistence) resetThirteenFApiPersistence();
   forms13FPersistence = persistence;
 }
 
 export function resetThirteenFApiPersistence() {
   forms13FPersistence = null;
+  failedRefreshes.clear();
+  activeRequests.clear();
 }
 
 function padCik(value: string): string {
@@ -89,25 +99,6 @@ function cacheKey(path: string, params: URLSearchParams): string {
   return query ? `${path}?${query}` : path;
 }
 
-function readApiCache<T>(
-  key: string,
-  options: { allowExpired?: boolean } = {},
-): T | null {
-  return forms13FPersistence?.getResource<T>(CACHE_KIND, key, {
-    sourceKey: CACHE_SOURCE,
-    schemaVersion: CACHE_SCHEMA_VERSION,
-    allowExpired: options.allowExpired,
-  })?.value ?? null;
-}
-
-function writeApiCache<T>(key: string, value: T): void {
-  forms13FPersistence?.setResource(CACHE_KIND, key, value, {
-    sourceKey: CACHE_SOURCE,
-    schemaVersion: CACHE_SCHEMA_VERSION,
-    cachePolicy: FORMS_13F_CACHE_POLICY,
-  });
-}
-
 async function fetchForms13F<T>(
   path: string,
   params: Record<string, string | number | undefined>,
@@ -120,31 +111,57 @@ async function fetchForms13F<T>(
   }
 
   const key = cacheKey(path, searchParams);
-  if (options.cache !== false && !options.forceRefresh) {
-    const cached = readApiCache<T>(key);
-    if (cached) return cached;
-  }
-
-  let value: T;
+  const store = forms13FPersistence;
+  const cacheOptions = { sourceKey: CACHE_SOURCE, schemaVersion: CACHE_SCHEMA_VERSION };
+  const cached = options.cache !== false ? store?.getResource<T>(CACHE_KIND, key, cacheOptions) : null;
+  if (!options.forceRefresh && !failedRefreshes.has(key) && cached && !cached.stale) return cached.value;
+
+  const request = {};
+  activeRequests.set(key, request);
+  const current = () => forms13FPersistence === store && activeRequests.get(key) === request;
   try {
-    value = await apiClient.getCloudSec13F(path, params) as T;
-  } catch {
-    const url = `${FORMS_13F_BASE_URL}${path}?${searchParams.toString()}`;
-    const response = await httpFetch(url, {
-      headers: { Accept: "application/json" },
-      signal: options.signal,
-    });
-    if (!response.ok) {
-      const stale = options.cache !== false ? readApiCache<T>(key, { allowExpired: true }) : null;
-      if (stale) return stale;
-      throw new Error(`Forms13F ${response.status} for ${path}`);
+    options.signal?.throwIfAborted();
+    let value: T;
+    try {
+      value = await apiClient.getCloudSec13F(path, params) as T;
+    } catch {
+      options.signal?.throwIfAborted();
+      const url = `${FORMS_13F_BASE_URL}${path}?${searchParams.toString()}`;
+      const response = await httpFetch(url, {
+        headers: { Accept: "application/json" },
+        signal: options.signal,
+      });
+      if (!response.ok) throw new ApiRequestError(`Forms13F ${response.status} for ${path}`, response.status);
+      value = await response.json() as T;
     }
-    value = await response.json() as T;
-  }
-  if (value != null && options.cache !== false) {
-    writeApiCache(key, value);
+    options.signal?.throwIfAborted();
+    if (current()) {
+      failedRefreshes.delete(key);
+      if (value != null && options.cache !== false) {
+        store?.setResource(CACHE_KIND, key, value, { ...cacheOptions, cachePolicy: FORMS_13F_CACHE_POLICY });
+      }
+    }
+    return value;
+  } catch (error) {
+    options.signal?.throwIfAborted();
+    if (current()) failedRefreshes.add(key);
+    if (error instanceof ApiRequestError && error.status !== undefined && error.status >= 400 && error.status < 500
+      && error.status !== 408 && error.status !== 429) {
+      if (current()) store?.deleteResource(CACHE_KIND, key, { sourceKey: CACHE_SOURCE });
+      throw error;
+    }
+    const retained = options.cache !== false
+      ? store?.getResource<T>(CACHE_KIND, key, { ...cacheOptions, allowExpired: true }) : null;
+    // A caller may retain old research only when it can surface its provenance.
+    if (!retained || !options.onWarning) throw error;
+    const retrieved = new Date(retained.fetchedAt);
+    const age = Number.isFinite(retrieved.getTime()) ? `retrieved ${retrieved.toISOString()}` : "with unavailable retrieval time";
+    const reason = (error instanceof Error ? error.message : String(error)).trim() || "Request failed";
+    options.onWarning(`${key}: refresh failed: ${reason}. Retained data ${age}.`);
+    return retained.value;
+  } finally {
+    if (activeRequests.get(key) === request) activeRequests.delete(key);
   }
-  return value;
 }
 
 function mapFund(raw: any): ThirteenFFund | null {
@@ -159,17 +176,18 @@ export function mapForm(raw: any): ThirteenFFormSummary | null {
   const accessionNumber = normalizeAccessionNumber(raw.accession_number, raw.url);
   const periodOfReport = stringOrEmpty(raw.period_of_report);
   if (!cik || !accessionNumber || !periodOfReport) return null;
+  const submissionType = stringOrEmpty(raw.submission_type || raw.form_type);
   return {
     url: stringOrEmpty(raw.url),
     accessionNumber,
-    submissionType: stringOrEmpty(raw.submission_type || raw.form_type),
+    submissionType,
     periodOfReport,
     filedAsOfDate: stringOrEmpty(raw.filed_as_of_date),
     cik,
     companyName: stringOrEmpty(raw.company_name),
     tableValueTotal: numberOrNull(raw.table_value_total),
     tableEntryTotal: numberOrNull(raw.table_entry_total),
-    isAmendment: boolOrFalse(raw.is_amendment) || stringOrEmpty(raw.submission_type).includes("/A"),
+    isAmendment: boolOrFalse(raw.is_amendment) || submissionType.includes("/A"),
     amendmentType: stringOrEmpty(raw.amendment_type) || undefined,
   };
 }
@@ -225,13 +243,13 @@ export async function searchThirteenFFunds(
   query: string,
   limit = 50,
   signal?: AbortSignal,
-  options: { forceRefresh?: boolean; offset?: number } = {},
+  options: Forms13FReadOptions & { offset?: number } = {},
 ): Promise<ThirteenFFund[]> {
   const raw = await fetchForms13F<unknown>("/funds", {
     name: query,
     offset: options.offset ?? 0,
     limit,
-  }, { signal, forceRefresh: options.forceRefresh });
+  }, { ...options, signal });
   return arrayResponse(raw).map(mapFund).filter((fund): fund is ThirteenFFund => !!fund);
 }
 
@@ -239,13 +257,13 @@ export async function listTopThirteenFFunds(
   quarter: string,
   limit = 50,
   signal?: AbortSignal,
-  options: { forceRefresh?: boolean; offset?: number } = {},
+  options: Forms13FReadOptions & { offset?: number } = {},
 ): Promise<ThirteenFTopFund[]> {
   const raw = await fetchForms13F<unknown>("/topfunds", {
     quarter,
     limit,
     offset: options.offset ?? 0,
-  }, { signal, forceRefresh: options.forceRefresh });
+  }, { ...options, signal });
   return arrayResponse(raw).map(mapTopFund).filter((fund): fund is ThirteenFTopFund => !!fund);
 }
 
@@ -254,14 +272,14 @@ export async function listThirteenFFilings(
   to: string,
   limit = 100,
   signal?: AbortSignal,
-  options: { forceRefresh?: boolean; offset?: number } = {},
+  options: Forms13FReadOptions & { offset?: number } = {},
 ): Promise<ThirteenFFormSummary[]> {
   const raw = await fetchForms13F<unknown>("/filings", {
     from,
     to,
     limit,
     offset: options.offset ?? 0,
-  }, { signal, forceRefresh: options.forceRefresh });
+  }, { ...options, signal });
   return arrayResponse(raw).map(mapForm).filter((form): form is ThirteenFFormSummary => !!form);
 }
 
@@ -271,7 +289,7 @@ export async function listThirteenFForms(
   to: string,
   limit = 12,
   signal?: AbortSignal,
-  options: { forceRefresh?: boolean; offset?: number } = {},
+  options: Forms13FReadOptions & { offset?: number } = {},
 ): Promise<ThirteenFFormSummary[]> {
   const raw = await fetchForms13F<unknown>("/forms", {
     cik: normalizeCik(cik),
@@ -279,7 +297,7 @@ export async function listThirteenFForms(
     to,
     limit,
     offset: options.offset ?? 0,
-  }, { signal, forceRefresh: options.forceRefresh });
+  }, { ...options, signal });
   return arrayResponse(raw).map(mapForm).filter((form): form is ThirteenFFormSummary => !!form);
 }
 
@@ -287,7 +305,7 @@ export async function listThirteenFFormHoldingsPage(
   cik: string,
   accessionNumber: string,
   signal?: AbortSignal,
-  options: { forceRefresh?: boolean; offset?: number; limit?: number } = {},
+  options: Forms13FReadOptions & { offset?: number; limit?: number } = {},
 ): Promise<{ rows: ThirteenFHoldingRecord[]; hasMore: boolean }> {
   const offset = Math.max(0, options.offset ?? 0);
   const limit = Math.max(1, options.limit ?? FORM_PAGE_LIMIT);
@@ -296,7 +314,7 @@ export async function listThirteenFFormHoldingsPage(
     accession_number: accessionNumber,
     limit,
     offset,
-  }, { signal, forceRefresh: options.forceRefresh });
+  }, { ...options, signal });
   const rows = arrayResponse(raw).map(mapHolding).filter((holding): holding is ThirteenFHoldingRecord => !!holding);
   return { rows, hasMore: rows.length >= limit && offset + rows.length < MAX_FORM_ROWS };
 }
@@ -305,7 +323,7 @@ export async function listThirteenFFormHoldings(
   cik: string,
   accessionNumber: string,
   signal?: AbortSignal,
-  options: { forceRefresh?: boolean } = {},
+  options: Forms13FReadOptions = {},
 ): Promise<ThirteenFHoldingRecord[]> {
   const rows: ThirteenFHoldingRecord[] = [];
   for (let offset = 0; offset < MAX_FORM_ROWS; offset += FORM_PAGE_LIMIT) {
@@ -323,7 +341,7 @@ export async function listThirteenFFormHoldings(
 export async function lookupThirteenFTickers(
   tickers: string[],
   signal?: AbortSignal,
-  options: { forceRefresh?: boolean } = {},
+  options: Forms13FReadOptions = {},
 ): Promise<ThirteenFTickerInfo[]> {
   const cleanTickers = tickers
     .map((ticker) => ticker.trim().toUpperCase())
@@ -333,7 +351,7 @@ export async function lookupThirteenFTickers(
   const raw = await fetchForms13F<unknown>("/tickers", {
     cusips: "",
     tickers: cleanTickers,
-  }, { signal, forceRefresh: options.forceRefresh });
+  }, { ...options, signal });
   return arrayResponse(raw).map(mapTickerInfo).filter((ticker): ticker is ThirteenFTickerInfo => !!ticker);
 }
 
@@ -341,12 +359,12 @@ export async function lookupThirteenFHoldersByCusip(
   cusip: string,
   periodOfReport: string,
   signal?: AbortSignal,
-  options: { forceRefresh?: boolean } = {},
+  options: Forms13FReadOptions = {},
 ): Promise<ThirteenFTickerHolders> {
   const raw = objectResponse(await fetchForms13F<unknown>("/holders", {
     cusip,
     period_of_report: periodOfReport,
-  }, { signal, forceRefresh: options.forceRefresh }));
+  }, { ...options, signal }));
   return {
     cusip: stringOrEmpty(raw.cusip) || cusip,
     periodOfReport: stringOrEmpty(raw.period_of_report) || periodOfReport,
@@ -355,31 +373,3 @@ export async function lookupThirteenFHoldersByCusip(
       : [],
   };
 }
-
-export async function loadLatestFormsForFunds(
-  funds: ThirteenFFund[],
-  options: { from: string; to: string; signal?: AbortSignal; concurrency?: number; forceRefresh?: boolean },
-): Promise<Map<string, ThirteenFFormSummary>> {
-  const forms = new Map<string, ThirteenFFormSummary>();
-  const concurrency = options.concurrency ?? 6;
-  let index = 0;
-
-  async function worker() {
-    while (index < funds.length) {
-      const fund = funds[index++];
-      if (!fund) continue;
-      try {
-        const fundForms = await listThirteenFForms(fund.cik, options.from, options.to, 1, options.signal, {
-          forceRefresh: options.forceRefresh,
-        });
-        const latest = fundForms[0];
-        if (latest) forms.set(fund.cik, latest);
-      } catch {
-        // A missing form should not hide the fund row.
-      }
-    }
-  }
-
-  await Promise.all(Array.from({ length: Math.min(concurrency, funds.length) }, () => worker()));
-  return forms;
-}

package/src/plugins/builtin/thirteenf/data.test.ts

@@ -5,7 +5,8 @@ import {
   attachThirteenFApiPersistence,
   resetThirteenFApiPersistence,
 } from "./api";
-import { loadBrowserRows } from "./data";
+import { loadBrowserRows, loadFilingPositions, loadFundDetail } from "./data";
+import { buildFundHoldingRows, hasComparable13FQuarter } from "./model";
 
 afterEach(() => {
   setHttpFetchTransport(null);
@@ -13,6 +14,147 @@ afterEach(() => {
 });
 
 describe("13F data cache", () => {
+  test("all browser entry points reconcile additions and restatements without borrowing another period", async () => {
+    const forms: any[] = [
+      { accession_number: "addition", period_of_report: "2026-06-30", table_value_total: 50, table_entry_total: 1,
+        filed_as_of_date: "2026-08-20", submission_type: "13F-HR/A", amendment_type: "NEW HOLDINGS" },
+      { accession_number: "original", period_of_report: "2026-06-30", table_value_total: 100, table_entry_total: 2,
+        filed_as_of_date: "2026-08-14", submission_type: "13F-HR" },
+    ];
+    let latestFilings = forms;
+    setHttpFetchTransport(async (url) => {
+      const request = new URL(String(url));
+      const path = request.pathname.split("/").at(-1);
+      const withManager = (rows: any[]) => rows.map((form) => ({ ...form, cik: "1067983", company_name: "Fund" }));
+      if (path === "forms") return json(withManager(forms.slice(Number(request.searchParams.get("offset") ?? 0), Number(request.searchParams.get("limit")))));
+      if (path === "filings") return json(withManager(latestFilings));
+      if (path === "funds") return json([{ cik: "1067983", name: "Fund" }]);
+      if (path === "topfunds") return json([{ cik: "1067983", name: "Fund", period_of_report: "2026-06-30", pnl: 4 }]);
+      if (path === "tickers") return json([{ cusip: "111111111", ticker: "AAA" }]);
+      if (path === "holders") return json({ period_of_report: "2026-06-30", ciks: ["1067983"] });
+      return json([]);
+    });
+    for (const [tab, query] of [["performance", ""], ["funds", "Fund"], ["funds", "1067983"], ["byTicker", "AAA"], ["latest", "latest"]] as const) {
+      expect((await loadBrowserRows(tab, query)).rows[0]).toMatchObject({ tableValueTotal: 150, tableEntryTotal: 3 });
+    }
+    forms.unshift({ ...forms[1], accession_number: "newer-quarter", period_of_report: "2026-09-30", table_value_total: 900, table_entry_total: 9 });
+    expect((await loadBrowserRows("performance", "")).rows[0]).toMatchObject({ periodOfReport: "2026-06-30", estQuarterReturn: 4, tableValueTotal: 150, tableEntryTotal: 3 });
+    forms.shift();
+    forms.unshift({ ...forms[0], accession_number: "restatement", amendment_type: "RESTATEMENT", filed_as_of_date: "2026-08-21", table_value_total: 20, table_entry_total: 1 });
+    expect((await loadBrowserRows("funds", "Fund")).rows[0]).toMatchObject({ tableValueTotal: 20, tableEntryTotal: 1 });
+    forms[0].amendment_type = undefined;
+    expect((await loadBrowserRows("funds", "Fund")).rows[0]).toMatchObject({ tableValueTotal: null, tableEntryTotal: null });
+    forms.splice(0, 1);
+    forms.pop();
+    expect((await loadBrowserRows("funds", "Fund")).rows[0]).toMatchObject({ tableValueTotal: null, tableEntryTotal: null });
+    latestFilings = [{ ...forms[0], period_of_report: "2026-03-31" }];
+    expect((await loadBrowserRows("latest", "latest")).rows[0]).toMatchObject({ periodOfReport: "2026-03-31", tableValueTotal: null, tableEntryTotal: null });
+  });
+
+  test("a missing prior report preserves current holdings and restores comparisons after refresh", async () => {
+    let failure: "previous" | "current" | null = "previous";
+    setHttpFetchTransport(async (url) => {
+      const request = new URL(String(url));
+      if (request.pathname.endsWith("/forms")) return json([
+        { accession_number: "current", period_of_report: "2026-06-30", table_value_total: 100, table_entry_total: 1, filed_as_of_date: "2026-08-14", submission_type: "13F-HR", cik: "1067983" },
+        { accession_number: "previous", period_of_report: "2026-03-31", table_value_total: 90, table_entry_total: 1, filed_as_of_date: "2026-05-14", submission_type: "13F-HR", cik: "1067983" },
+      ]);
+      const accession = request.searchParams.get("accession_number");
+      if (accession === failure) return new Response("unavailable", { status: 503 });
+      return json([{ accession_number: accession, cik: "1067983", cusip: "111111111", value: accession === "current" ? 100 : 90, ssh_prnamt: 10 }]);
+    });
+    const partial = await loadFundDetail("1067983", "Fund");
+    expect(partial.latestReport).toMatchObject({ complete: true, tableValueTotal: 100 });
+    expect(partial.previousReport?.complete).toBe(false);
+    expect(partial.warnings).toEqual(["2026-03-31: holdings unavailable; comparison unavailable."]);
+    expect(buildFundHoldingRows(partial)[0]).toMatchObject({ value: 100, weight: 1, previousValue: null, estimatedPnl: null, action: "unknown", sharesChange: null });
+    failure = null;
+    const recovered = await loadFundDetail("1067983", "Fund", undefined, { forceRefresh: true });
+    expect(hasComparable13FQuarter(recovered)).toBe(true);
+    expect(buildFundHoldingRows(recovered)[0]).toMatchObject({ value: 100, previousValue: 90, action: "held", sharesChange: 0 });
+    failure = "current";
+    await expect(loadFundDetail("1067983", "Fund", undefined, { forceRefresh: true })).rejects.toThrow("Forms13F 503");
+  });
+
+  test("one failed holder enhancement retains every source CIK and healthy metadata", async () => {
+    setHttpFetchTransport(async (url) => {
+      const request = new URL(String(url));
+      const path = request.pathname.split("/").at(-1);
+      if (path === "tickers") return json([{ cusip: "111111111", ticker: "AAA" }]);
+      if (path === "holders") return json({ period_of_report: "2026-06-30", ciks: ["1", "2"] });
+      if (path === "forms" && request.searchParams.get("cik") === "0000000002") return new Response("unavailable", { status: 503 });
+      return json([{ accession_number: "healthy", cik: "1", company_name: "Healthy Fund", period_of_report: "2026-06-30", filed_as_of_date: "2026-08-14", submission_type: "13F-HR", table_value_total: 100, table_entry_total: 1 }]);
+    });
+    const result = await loadBrowserRows("byTicker", "AAA");
+    expect(result.rows).toHaveLength(2);
+    expect(result.rows[0]).toMatchObject({ cik: "0000000001", name: "Healthy Fund", tableValueTotal: 100 });
+    expect(result.rows[1]).toMatchObject({ cik: "0000000002", name: "0000000002" });
+    expect(result.rows[1]?.tableValueTotal).toBeUndefined();
+    expect(result.warning).toBe("0000000002: filing metadata unavailable.");
+  });
+
+  test("keeps performance returns and latest filing metadata in their own reporting periods", async () => {
+    let reportedPeriod = "2026-09-30";
+    setHttpFetchTransport(async (url) => {
+      const path = new URL(String(url)).pathname;
+      if (path.endsWith("/funds")) return json([{ cik: "1067983", name: "Fund" }]);
+      if (path.endsWith("/topfunds")) return json([{
+        cik: "1067983", name: "Fund", period_of_report: "2026-06-30", pnl: 12,
+      }]);
+      if (path.endsWith("/forms")) return json([{
+        accession_number: "filing", cik: "1067983", company_name: "Fund", submission_type: "13F-HR",
+        period_of_report: reportedPeriod, filed_as_of_date: "2026-10-15", table_value_total: 100, table_entry_total: 2,
+      }]);
+      return json([]);
+    });
+    const performance = await loadBrowserRows("performance", "");
+    expect(performance.rows[0]).toMatchObject({ periodOfReport: "2026-06-30", estQuarterReturn: 12 });
+    expect(performance.rows[0]?.tableValueTotal).toBeUndefined();
+    expect(performance.rows[0]?.filedAsOfDate).toBeUndefined();
+    expect(performance.rows[0]?.tableEntryTotal).toBeUndefined();
+
+    const funds = await loadBrowserRows("funds", "Fund");
+    expect(funds.rows[0]).toMatchObject({ periodOfReport: "2026-09-30", tableValueTotal: 100, estQuarterReturn: null });
+
+    reportedPeriod = "2026-06-30";
+    for (const tab of ["performance", "funds"] as const) {
+      const matching = await loadBrowserRows(tab, "Fund");
+      expect(matching.rows[0]).toMatchObject({ periodOfReport: "2026-06-30", tableValueTotal: 100, estQuarterReturn: 12 });
+    }
+  });
+
+  test("loads all additive filings, uses their combined denominator, and detects truncated holdings", async () => {
+    const fetched: string[] = [];
+    const forms = [
+      { accession_number: "base", period_of_report: "2026-06-30", table_value_total: 100,
+        table_entry_total: 1, filed_as_of_date: "2026-08-14", submission_type: "13F-HR" },
+      { accession_number: "addition", period_of_report: "2026-06-30", table_value_total: 50,
+        table_entry_total: 1, filed_as_of_date: "2026-08-20", submission_type: "13F-HR/A", amendment_type: "NEW HOLDINGS" },
+      { accession_number: "previous", period_of_report: "2026-03-31", table_value_total: 120,
+        table_entry_total: 1, filed_as_of_date: "2026-05-14", submission_type: "13F-HR" },
+    ];
+    setHttpFetchTransport(async (url) => {
+      const parsed = new URL(String(url));
+      if (parsed.pathname.endsWith("/forms")) return json(forms.map((form) => ({ ...form, cik: "1067983" })));
+      const accession = parsed.searchParams.get("accession_number")!;
+      fetched.push(accession);
+      return json([{ accession_number: accession, cik: "1067983", cusip: accession === "addition" ? "222222222" : "111111111",
+        ticker: accession === "addition" ? "NEW" : "OLD", value: accession === "addition" ? 50 : 100, ssh_prnamt: 10 }]);
+    });
+    const detail = await loadFundDetail("1067983", "Fund");
+    expect(fetched.sort()).toEqual(["addition", "base", "previous"]);
+    expect(detail.forms).toHaveLength(3);
+    expect(detail.latestReport).toMatchObject({ complete: true, tableValueTotal: 150 });
+    expect(hasComparable13FQuarter(detail)).toBe(true);
+    expect(buildFundHoldingRows(detail).find((row) => row.ticker === "NEW"))
+      .toMatchObject({ weight: 1 / 3, value: 50, action: "new" });
+    forms[0]!.table_entry_total = 2;
+    const partial = await loadFundDetail("1067983", "Fund", undefined, { forceRefresh: true });
+    expect(partial.warnings?.[0]).toContain("loaded 1 of 2");
+    expect(hasComparable13FQuarter(partial)).toBe(false);
+    expect(buildFundHoldingRows(partial).every((row) => row.action === "unknown" && row.weight === null)).toBe(true);
+  });
+
   test("reuses the built-in plugin resource cache across browser row loads", async () => {
     attachThirteenFApiPersistence(new MemoryPluginPersistence());
     let requestCount = 0;
@@ -93,3 +235,37 @@ function json(value: unknown): Response {
     headers: { "Content-Type": "application/json" },
   });
 }
+
+
+test("browser, reconciled report and individual filing expose failed-refresh cache provenance without changing filing dates", async () => {
+  attachThirteenFApiPersistence(new MemoryPluginPersistence());
+  let fail = false;
+  setHttpFetchTransport(async url => {
+    if (fail) throw new Error("Controlled network outage");
+    if (new URL(String(url)).pathname.endsWith("/forms")) return json([{
+      accession_number: "0001067983-26-000001", cik: "1067983", company_name: "Fund",
+      period_of_report: "2026-06-30", filed_as_of_date: "2026-08-14", submission_type: "13F-HR",
+      table_value_total: 100, table_entry_total: 1,
+    }]);
+    return json([{ accession_number: "0001067983-26-000001", cik: "1067983", cusip: "111111111", value: 100, ssh_prnamt: 10 }]);
+  });
+  const browser = await loadBrowserRows("funds", "1067983");
+  const detail = await loadFundDetail("1067983", "Fund");
+  const filing = await loadFilingPositions("1067983", "0001067983-26-000001");
+  fail = true;
+  const retainedBrowser = await loadBrowserRows("funds", "1067983", undefined, { forceRefresh: true });
+  const retainedDetail = await loadFundDetail("1067983", "Fund", undefined, { forceRefresh: true });
+  const retainedFiling = await loadFilingPositions("1067983", "0001067983-26-000001", undefined, { forceRefresh: true });
+  expect(retainedBrowser.rows).toEqual(browser.rows);
+  expect(retainedDetail.latestForm).toEqual(detail.latestForm);
+  expect(retainedDetail.latestHoldings).toEqual(detail.latestHoldings);
+  expect(retainedFiling.rows).toEqual(filing.rows);
+  for (const warning of [retainedBrowser.warning, ...retainedDetail.warnings!, ...retainedFiling.warnings]) {
+    expect(warning).toContain("Controlled network outage");
+    expect(warning).toMatch(/retrieved \d{4}-\d{2}-\d{2}T/);
+  }
+  fail = false;
+  expect((await loadBrowserRows("funds", "1067983")).warning).toBeUndefined();
+  expect((await loadFundDetail("1067983", "Fund")).warnings).toEqual([]);
+  expect((await loadFilingPositions("1067983", "0001067983-26-000001")).warnings).toEqual([]);
+});