gloomberb 0.14.0 → 0.15.0

package/src/sources/reported-operating-results.test.ts

@@ -0,0 +1,286 @@
+import { expect, test } from "bun:test";
+import type { FinancialStatement, TickerFinancials } from "../types/financials";
+import { coalesceFinancialPeriodAliases, mergeFinancialStatementRows, statementFieldAvailability } from "../utils/financial-statements";
+import { normalizeStatementOperatingResult, operatingResultDisagrees, providerOperatingObservation, reportedOperatingCohort } from "../utils/operating-result";
+import { parseCompanyFactsFinancialStatements, SecEdgarClient } from "./sec-edgar";
+import { buildYahooStatements, parseYahooTimeseries } from "./yahoo-finance/financials";
+import { YahooFinanceClient } from "./yahoo-finance";
+import { mapCloudFinancials } from "./gloomberb-cloud/normalizers";
+import sec from "./fixtures/sec-operating-expenses.json";
+import yahoo from "./fixtures/shop-operating-provider.json";
+import liveSubmissions from "./fixtures/shop-submissions-20260922.json";
+import { canAggregateOperatingField } from "../utils/operating-result-aggregation";
+import { readFileSync } from "node:fs";
+
+const metrics = parseYahooTimeseries(yahoo.timeseries.result);
+const source = () => parseCompanyFactsFinancialStatements(sec.shop);
+const provider = (period: "annual" | "quarterly") => buildYahooStatements({ ...metrics,
+  // Controlled independent companion observations; the captured Yahoo request
+  // above contained only the directly compared operating trio.
+  [`${period}EBITDA`]: [{ asOfDate: period === "annual" ? "2025-12-31" : "2026-06-30", currency: "USD", periodType: period === "annual" ? "12M" : "3M", value: 17 }],
+  [`${period}TotalExpenses`]: [{ asOfDate: period === "annual" ? "2025-12-31" : "2026-06-30", currency: "USD", periodType: period === "annual" ? "12M" : "3M", value: 23 }],
+}, period, true)[0]!;
+const financials = (row: FinancialStatement): TickerFinancials => ({
+  quote: { symbol: "SHOP", currency: "USD", exchangeName: "NASDAQ", price: 100, change: 0, changePercent: 0 },
+  financialCurrency: "USD", annualStatements: [row], quarterlyStatements: [], priceHistory: [],
+});
+
+test("captured native provider and SEC rows keep direct trio and independent companions in both merge orders", () => {
+  for (const period of ["annual", "quarterly"] as const) {
+    const original = provider(period);
+    const direct = source()[period === "annual" ? "annualStatements" : "quarterlyStatements"][0]!;
+    for (const [primary, fallback] of [[original, direct], [direct, original]]) {
+      const merged = mergeFinancialStatementRows([primary!], [fallback!])[0]!;
+      expect(reportedOperatingCohort(merged, period)?.values).toEqual({
+        grossProfit: direct.grossProfit!, operatingExpense: direct.operatingExpense!, operatingIncome: direct.operatingIncome!,
+      });
+      expect(merged.operatingIncome).toBe(period === "annual" ? 1_468_000_000 : 488_000_000);
+      expect(merged.operatingExpense).toBe(period === "annual" ? 4_087_000_000 : 1_220_000_000);
+      expect(merged.ebitda).toBe(original.ebitda);
+      expect(merged.totalExpenses).toBe(original.totalExpenses);
+      expect(providerOperatingObservation(merged, "operatingIncome")?.value).toBe(original.operatingIncome);
+      if (original.ebitda !== undefined) expect(providerOperatingObservation(merged, "ebitda")?.value).toBe(original.ebitda);
+      expect(operatingResultDisagrees(merged)).toBe(true);
+      expect(statementFieldAvailability(merged, "operatingExpense")).toBe(direct.operatingResult!.reported!.filed);
+      expect(normalizeStatementOperatingResult(JSON.parse(JSON.stringify(merged)), period)).toEqual(merged);
+    }
+  }
+});
+
+test("native default supplementation changes only the qualified reported operating group, with unrelated controls", async () => {
+  const client = new YahooFinanceClient() as any;
+  let calls = 0;
+  client.secClient.getFinancialStatements = async () => { calls++; return source(); };
+  const original = financials(provider("annual"));
+  const merged = await client.supplementSecStatements("SHOP", "NASDAQ", original, false) as TickerFinancials;
+  expect(merged.annualStatements[0]!.operatingIncome).toBe(1_468_000_000);
+  expect(merged.annualStatements[0]!.ebitda).toBe(original.annualStatements[0]!.ebitda);
+  const toronto = { ...original, quote: { ...original.quote!, currency: "CAD", exchangeName: "TSX" } };
+  expect((await client.supplementSecStatements("SHOP", "TSX", toronto, false)).annualStatements).toEqual(toronto.annualStatements);
+  expect(calls).toBe(1);
+  const alias = await client.supplementSecStatements("SHOP", "XNAS", original, true) as TickerFinancials;
+  expect(alias.annualStatements[0]!.operatingIncome).toBe(1_468_000_000);
+  expect(alias.annualStatements[0]!.ebitda).toBe(original.annualStatements[0]!.ebitda);
+  const msft = parseCompanyFactsFinancialStatements(sec.msft).annualStatements[0]!;
+  expect(msft.operatingResult).toBeUndefined();
+  expect(mergeFinancialStatementRows([{ date: msft.date, currency: "USD", operatingIncome: 10 }], [msft])[0]!.operatingIncome).toBe(10);
+});
+
+test("owned operating rows cannot cross currency, neighboring period or conflicting top-line anchors", () => {
+  const direct = source().quarterlyStatements[0]!;
+  const original = provider("quarterly");
+  const foreign = { ...original, currency: "CAD" };
+  expect(mergeFinancialStatementRows([foreign], [direct])[0]!.operatingIncome).toBe(original.operatingIncome);
+  const neighboring: FinancialStatement = { date: "2026-06-29", currency: "USD", operatingIncome: original.operatingIncome };
+  const merged = mergeFinancialStatementRows([neighboring], [direct])[0]!;
+  expect(merged.date).toBe(neighboring.date);
+  expect(merged.operatingIncome).toBe(original.operatingIncome);
+  expect(merged.operatingExpense).toBeUndefined();
+  expect(merged.grossProfit).toBeUndefined();
+  expect(merged.operatingResult?.reported).toBeUndefined();
+  expect(mergeFinancialStatementRows([neighboring], [direct])).toHaveLength(2);
+  const matchingNeighbor = { ...direct, date: neighboring.date, operatingResult: undefined };
+  for (const [primary, fallback] of [[matchingNeighbor, direct], [direct, matchingNeighbor]] as const) {
+    expect(coalesceFinancialPeriodAliases([primary, fallback]).map(row => row.date)).toEqual([neighboring.date, direct.date]);
+    expect(mergeFinancialStatementRows([primary], [fallback]).map(row => row.date)).toEqual([neighboring.date, direct.date]);
+    expect(mergeFinancialStatementRows([primary], [fallback]).find(row => row.date === direct.date)?.operatingResult).toEqual(direct.operatingResult);
+  }
+  const anchored = structuredClone(direct);
+  anchored.operatingResult!.reported!.anchors = { totalRevenue: 3_583_000_000 };
+  const conflict = mergeFinancialStatementRows([{ ...original, totalRevenue: 1 }], [anchored])[0]!;
+  expect(conflict.operatingResult?.reported).toBeUndefined();
+  expect(conflict.operatingIncome).toBe(original.operatingIncome);
+});
+
+test("Cloud ownership is listing, period and numeric-value bound rather than accepting arbitrary metadata", () => {
+  const row = mergeFinancialStatementRows([provider("annual")], source().annualStatements)[0]!;
+  const input = financials(row);
+  expect(mapCloudFinancials(input as any, undefined, { symbol: "SHOP", exchange: "NASDAQ" }).annualStatements[0]!.operatingResult).toEqual(row.operatingResult);
+  expect(mapCloudFinancials({ ...input, quote: undefined } as any, undefined, { symbol: "SHOP", exchange: "TSX" }).annualStatements[0]!.operatingResult).toBeUndefined();
+  for (const mutate of [
+    (bad: FinancialStatement) => { bad.operatingResult!.reported!.cik = "0000789019"; },
+    (bad: FinancialStatement) => { bad.operatingResult!.reported!.period = "quarterly"; },
+    (bad: FinancialStatement) => { bad.operatingIncome = 7; },
+  ]) {
+    const bad = structuredClone(row); mutate(bad);
+    expect(mapCloudFinancials(financials(bad) as any, undefined, { symbol: "SHOP", exchange: "NASDAQ" }).annualStatements[0]!.operatingResult?.reported).toBeUndefined();
+  }
+  const bad = structuredClone(row);
+  (bad.operatingResult!.provider!.operatingIncome as any).sourceField = 42;
+  expect(normalizeStatementOperatingResult(bad).operatingResult?.provider?.operatingIncome).toBeUndefined();
+});
+
+test("companion provenance follows the actual numeric owner even when losing values happen to match", () => {
+  const direct = { ...source().annualStatements[0]!, ebitda: provider("annual").ebitda, totalExpenses: provider("annual").totalExpenses };
+  const merged = mergeFinancialStatementRows([direct], [provider("annual")])[0]!;
+  expect(merged.ebitda).toBe(direct.ebitda);
+  expect(merged.operatingResult?.provider?.ebitda).toBeUndefined();
+  expect(merged.operatingResult?.provider?.totalExpenses).toBeUndefined();
+  expect(merged.operatingResult?.provider?.operatingIncome).toBeDefined();
+});
+
+test("Yahoo ownership requires each observation's explicit currency and exact duration, including replacement points", () => {
+  for (const period of ["annual", "quarterly"] as const) {
+    const valid = { asOfDate: "2025-12-31", currency: "USD", periodType: period === "annual" ? "12M" : "3M", value: 100 };
+    for (const unqualified of [{ ...valid, currency: undefined }, { ...valid, periodType: undefined },
+      { ...valid, periodType: period === "annual" ? "3M" : "12M" }, { ...valid, value: undefined }]) {
+      const row = buildYahooStatements({ [`${period}OperatingIncome`]: [valid, unqualified] }, period, true)[0]!;
+      expect(row.operatingIncome).toBe(unqualified.value);
+      expect(providerOperatingObservation(row, "operatingIncome")).toBeUndefined();
+    }
+  }
+});
+
+function nativeFixtureClient() {
+  const client = new SecEdgarClient() as any;
+  const requests: string[] = [];
+  const state = { companyFactsFail: false, tableFail: false, submissionsFail: false, amendment: false,
+    annualFail: false, liveSubmissions: false, tableWait: undefined as Promise<void> | undefined };
+  client.loadLookup = async () => new Map([
+    ["SHOP", { cik: "0001594805", exchange: "Nasdaq" }],
+    ["MSFT", { cik: "0000789019", exchange: "Nasdaq" }],
+  ]);
+  client.fetchJson = async (url: string) => {
+    requests.push(url);
+    if (url.includes("companyfacts")) {
+      if (state.companyFactsFail) throw new Error("fixture companyfacts unavailable");
+      return url.includes("1594805") ? sec.shop : sec.msft;
+    }
+    if (state.submissionsFail) throw new Error("fixture submissions unavailable");
+    if (state.liveSubmissions) return liveSubmissions;
+    return { cik: "1594805", filings: { recent: {
+      accessionNumber: [...(state.amendment ? ["0001594805-26-000048"] : []), "0001594805-26-000047", "0001594805-26-000007"],
+      form: [...(state.amendment ? ["10-Q/A"] : []), "10-Q", "10-K"],
+      filingDate: [...(state.amendment ? ["2026-08-06"] : []), "2026-08-05", "2026-02-11"],
+      primaryDocument: [...(state.amendment ? ["shop-amendment.htm"] : []), "shop-20260630.htm", "shop-20251231.htm"],
+    } } };
+  };
+  client.fetchText = async (url: string) => {
+    requests.push(url);
+    if (state.tableWait) await state.tableWait;
+    if (state.tableFail) throw new Error("fixture source unavailable");
+    if (state.annualFail && url.includes("20251231")) throw new Error("fixture annual source unavailable");
+    return { body: readFileSync(new URL(`./fixtures/shop-${url.includes("20260630") ? "20260630" : "20251231"}-quarterly-summary.html`, import.meta.url), "utf8") };
+  };
+  return { client, requests, state };
+}
+
+test("native acquisition loads direct Q4 table cohorts with bounded, cached issuer-qualified documents", async () => {
+  const { client, requests } = nativeFixtureClient();
+  const first = await client.getFinancialStatements("SHOP", { reportedOperatingResults: true });
+  const q4 = first.quarterlyStatements.find((row: FinancialStatement) => row.date === "2025-12-31")!;
+  expect(q4.operatingIncome).toBe(631_000_000);
+  expect(q4.operatingExpense).toBe(1_062_000_000);
+  expect(q4.operatingResult.reported.origin.kind).toBe("filing-table");
+  expect(q4.operatingResult.reported.anchors).toEqual({ totalRevenue: 3_672_000_000, costOfRevenue: 1_979_000_000 });
+  expect(q4.ebitda).toBeUndefined();
+  expect(q4.totalExpenses).toBeUndefined();
+  expect(requests.filter(url => url.includes("submissions"))).toHaveLength(1);
+  expect(requests.filter(url => url.includes("Archives"))).toHaveLength(2);
+  await client.getFinancialStatements("SHOP", { reportedOperatingResults: true });
+  await client.getFinancialStatements("MSFT", { reportedOperatingResults: true });
+  expect(requests.filter(url => url.includes("Archives"))).toHaveLength(2);
+});
+
+test("native sources fail independently and total table refresh failure retains the original qualified snapshot", async () => {
+  for (const failure of ["tableFail", "submissionsFail"] as const) {
+    const { client, requests, state } = nativeFixtureClient();
+    await client.getFinancialStatements("SHOP", { reportedOperatingResults: true });
+    const snapshot = client.shopOperatingTables;
+    snapshot.expiresAt = 0;
+    state[failure] = true;
+    const stale = await client.getFinancialStatements("SHOP", { reportedOperatingResults: true });
+    expect(stale.quarterlyStatements.find((row: FinancialStatement) => row.date === "2025-12-31")?.operatingIncome).toBe(631_000_000);
+    expect(client.shopOperatingTables).toBe(snapshot);
+    expect(snapshot.expiresAt).toBe(0);
+    const requestCount = requests.filter(url => url.includes("submissions")).length;
+    await client.getFinancialStatements("SHOP", { reportedOperatingResults: true });
+    expect(requests.filter(url => url.includes("submissions"))).toHaveLength(requestCount);
+    const cold = nativeFixtureClient();
+    cold.state[failure] = true;
+    const fallback = await cold.client.getFinancialStatements("SHOP", { reportedOperatingResults: true });
+    expect(fallback.annualStatements[0].operatingIncome).toBe(1_468_000_000);
+    expect(fallback.quarterlyStatements.find((row: FinancialStatement) => row.date === "2025-12-31")).toBeUndefined();
+  }
+  const tablesOnly = nativeFixtureClient();
+  tablesOnly.state.companyFactsFail = true;
+  const rows = await tablesOnly.client.getFinancialStatements("SHOP", { reportedOperatingResults: true });
+  expect(rows.quarterlyStatements.find((row: FinancialStatement) => row.date === "2025-12-31")?.operatingIncome).toBe(631_000_000);
+  tablesOnly.client.shopOperatingTables = undefined;
+  tablesOnly.state.tableFail = true;
+  await expect(tablesOnly.client.getFinancialStatements("SHOP", { reportedOperatingResults: true })).rejects.toThrow("fixture companyfacts unavailable");
+});
+
+test("captured annual amendment does not discard the later Q2 filing's direct Q4 and compatible trailing quarters", async () => {
+  const { client, requests, state } = nativeFixtureClient();
+  state.liveSubmissions = true;
+  const first = await client.getFinancialStatements("SHOP", { reportedOperatingResults: true });
+  const q4 = first.quarterlyStatements.find((row: FinancialStatement) => row.date === "2025-12-31")!;
+  expect(q4.operatingIncome).toBe(631_000_000);
+  expect(q4.operatingExpense).toBe(1_062_000_000);
+  expect(q4.operatingResult.reported.accessionNumber).toBe("0001594805-26-000047");
+  expect(q4.operatingResult.reported.filed).toBe("2026-08-05");
+  const trailing = first.quarterlyStatements.filter((row: FinancialStatement) => row.date >= "2025-09-30");
+  expect(trailing).toHaveLength(4);
+  expect(canAggregateOperatingField(trailing, "operatingIncome")).toBe(true);
+  expect(canAggregateOperatingField(trailing, "operatingExpense")).toBe(true);
+  expect(trailing.reduce((sum: number, row: FinancialStatement) => sum + row.operatingIncome!, 0)).toBe(1_844_000_000);
+  expect(trailing.reduce((sum: number, row: FinancialStatement) => sum + row.operatingExpense!, 0)).toBe(4_494_000_000);
+  expect(requests.filter(url => url.includes("Archives"))).toHaveLength(1);
+  expect(requests.some(url => url.includes("000159480526000007"))).toBe(false);
+  expect(client.shopOperatingTables).toBeUndefined();
+  const partial = client.shopOperatingTablesPartial;
+  expect(partial.expiresAt - Date.now()).toBeGreaterThan(55_000);
+  expect(partial.expiresAt - Date.now()).toBeLessThanOrEqual(60_000);
+  const count = requests.length;
+  await client.getFinancialStatements("SHOP", { reportedOperatingResults: true });
+  expect(requests.length).toBe(count + 1); // companyfacts only; no repeated filings/documents
+  partial.expiresAt = client.shopOperatingTablesRetryAt = 0;
+  await client.getFinancialStatements("SHOP", { reportedOperatingResults: true });
+  expect(requests.filter(url => url.includes("submissions"))).toHaveLength(2);
+  expect(client.shopOperatingTablesPartial.cohorts).toHaveLength(partial.cohorts.length);
+});
+
+test("a later quarterly amendment preserves the annual sibling at its actual date without selecting the preceding Q", async () => {
+  const { client, requests, state } = nativeFixtureClient();
+  state.amendment = true;
+  const value = await client.getFinancialStatements("SHOP", { reportedOperatingResults: true });
+  const q4 = value.quarterlyStatements.find((row: FinancialStatement) => row.date === "2025-12-31")!;
+  expect(q4.operatingIncome).toBe(631_000_000);
+  expect(q4.operatingResult.reported.filed).toBe("2026-02-11");
+  expect(q4.operatingResult.reported.accessionNumber).toBe("0001594805-26-000007");
+  expect(requests.some(url => url.includes("Archives") && url.includes("20260630"))).toBe(false);
+  expect(client.shopOperatingTables).toBeUndefined();
+});
+
+test("partial refresh, total failure and recovery preserve snapshot expiry and source dates with bounded single-flight acquisition", async () => {
+  const { client, requests, state } = nativeFixtureClient();
+  await client.getFinancialStatements("SHOP", { reportedOperatingResults: true });
+  const complete = client.shopOperatingTables;
+  complete.expiresAt = 0;
+  state.annualFail = true;
+  let release!: () => void;
+  state.tableWait = new Promise<void>(resolve => { release = resolve; });
+  const pending = Promise.all([client.getFinancialStatements("SHOP", { reportedOperatingResults: true }),
+    client.getFinancialStatements("SHOP", { reportedOperatingResults: true })]);
+  release();
+  await pending;
+  expect(requests.filter(url => url.includes("submissions"))).toHaveLength(2);
+  expect(requests.filter(url => url.includes("Archives"))).toHaveLength(4);
+  expect(client.shopOperatingTables).toBe(complete);
+  expect(complete.expiresAt).toBe(0);
+  const partial = client.shopOperatingTablesPartial;
+  expect(partial.cohorts).toEqual(complete.cohorts);
+  partial.expiresAt = client.shopOperatingTablesRetryAt = 0;
+  state.tableFail = true;
+  await client.getFinancialStatements("SHOP", { reportedOperatingResults: true });
+  expect(client.shopOperatingTablesPartial).toBe(partial);
+  expect(partial.expiresAt).toBe(0);
+  expect(client.shopOperatingTables).toBe(complete);
+  client.shopOperatingTablesRetryAt = 0;
+  state.tableFail = state.annualFail = false;
+  await client.getFinancialStatements("SHOP", { reportedOperatingResults: true });
+  expect(client.shopOperatingTablesPartial).toBeUndefined();
+  expect(client.shopOperatingTables.expiresAt - Date.now()).toBeGreaterThan(5 * 60 * 60_000);
+  expect(client.shopOperatingTablesRetryAt).toBe(0);
+});

package/src/sources/sec-bank-revenue.test.ts

@@ -0,0 +1,79 @@
+import { expect, test } from "bun:test";
+import { parseCompanyFactsFinancialStatements } from "./sec-edgar";
+
+const bankConcept = "RevenuesNetOfInterestExpense";
+const fact = (rows: object[], unit = "USD") => ({ units: { [unit]: rows } });
+const quarter = { start: "2025-04-01", end: "2025-06-30", form: "10-Q", fp: "Q2", filed: "2025-08-05", accn: "0000019617-25-000615", val: 44_912_000_000 };
+const parseBank = (rows: object[], unit = "USD") => parseCompanyFactsFinancialStatements({ facts: { "us-gaap": { [bankConcept]: fact(rows, unit) } } });
+const revenueBy = (payload: object) => Object.fromEntries(parseCompanyFactsFinancialStatements(payload).quarterlyStatements
+  .map(row => [row.date, row.totalRevenue]));
+
+test("bank revenue fills quarters another tag leaves empty when both tags report the same amounts", () => {
+  // JPM tags total net revenue under both concepts; filings that carry both agree.
+  const q1 = { ...quarter, start: "2025-01-01", end: "2025-03-31", fp: "Q1", filed: "2025-05-01", accn: "0000019617-25-000400", val: 45_310_000_000 };
+  expect(revenueBy({ facts: { "us-gaap": {
+    Revenues: fact([q1]),
+    [bankConcept]: fact([q1, quarter]),
+  } } })).toEqual({ "2025-03-31": q1.val, "2025-06-30": quarter.val });
+});
+
+test("bank revenue stays out when a filing shows it measures something else than the filer's revenue tag", () => {
+  // AXP tags fee revenue alone under the contract-revenue concept. Mixing its
+  // total net revenue into empty periods would create false jumps.
+  const fee = { ...quarter, val: 6_047_000_000 };
+  const q3 = { ...quarter, start: "2025-07-01", end: "2025-09-30", fp: "Q3", accn: "0000004962-25-000900", val: 9_710_000_000 };
+  expect(revenueBy({ facts: { "us-gaap": {
+    RevenueFromContractWithCustomerExcludingAssessedTax: fact([fee]),
+    [bankConcept]: fact([{ ...quarter, val: 7_889_000_000 }, q3]),
+  } } })).toEqual({ "2025-06-30": fee.val });
+});
+
+test("a bank-revenue quarterly frame cannot admit YTD, missing, invalid or reversed duration", () => {
+  for (const duration of [
+    { start: "2025-01-01", end: "2025-06-30" },
+    { start: "2025-01-01", end: "2025-09-30" },
+    { start: undefined }, { start: "invalid" }, { start: "2025-02-30" },
+    { start: "2025-06-31", end: "2025-09-30" },
+    { start: "2025-07-01" }, { start: "2025-06-01" },
+  ]) {
+    const parsed = parseBank([{ ...quarter, ...duration, frame: "CY2025Q2" }]);
+    expect(parsed.quarterlyStatements).toEqual([]);
+  }
+  expect(parseBank([{ ...quarter, frame: "CY2025Q2", form: "8-K" }]).quarterlyStatements).toEqual([]);
+  expect(parseBank([quarter], "EUR").quarterlyStatements).toEqual([]);
+  // The new concept does not change the established frame policy for other tags.
+  const legacy = parseCompanyFactsFinancialStatements({ facts: { "us-gaap": {
+    Revenues: fact([{ ...quarter, start: "2025-01-01", frame: "CY2025Q2" }]),
+  } } });
+  expect(legacy.quarterlyStatements[0]?.totalRevenue).toBe(quarter.val);
+});
+
+test("direct bank revenue keeps zero and negative values, duration limits and existing annual rules", () => {
+  for (const [start, end, val] of [["2025-04-01", "2025-05-31", 0], ["2025-04-01", "2025-07-30", -2]] as const) {
+    const rows = parseBank([{ ...quarter, start, end, val, frame: "CY2025Q2" }]).quarterlyStatements;
+    expect(rows[0]?.totalRevenue).toBe(val);
+  }
+  for (const [start, end] of [["2025-04-01", "2025-05-30"], ["2025-04-01", "2025-07-31"]]) {
+    expect(parseBank([{ ...quarter, start, end, frame: "CY2025Q2" }]).quarterlyStatements).toEqual([]);
+  }
+  const annual = { ...quarter, start: "2025-01-01", end: "2025-12-31", form: "10-K", fp: "FY", filed: "2026-02-13" };
+  expect(parseBank([annual]).annualStatements[0]?.totalRevenue).toBe(annual.val);
+  expect(parseBank([{ ...annual, form: "10-Q" }]).annualStatements).toEqual([]);
+  expect(parseBank([{ ...annual, start: "2025-03-01" }]).annualStatements).toEqual([]);
+});
+
+test("bank revenue is a fallback; same-concept restatements retain their own disclosure dates", () => {
+  for (const tag of ["RevenueFromContractWithCustomerExcludingAssessedTax", "Revenues", "SalesRevenueNet"]) {
+    const result = parseCompanyFactsFinancialStatements({ facts: { "us-gaap": {
+      [tag]: fact([{ ...quarter, val: 100 }]),
+      [bankConcept]: fact([{ ...quarter, val: 200, filed: "2026-08-06" }]),
+    } } });
+    expect(result.quarterlyStatements[0]).toMatchObject({ totalRevenue: 100, fieldAvailability: { totalRevenue: "2025-08-05" } });
+  }
+  const repeat = { ...quarter, filed: "2026-08-06", frame: "CY2025Q2" };
+  expect(parseBank([quarter, repeat]).quarterlyStatements[0]?.fieldAvailability?.totalRevenue).toBe("2025-08-05");
+  const amended = { ...quarter, val: quarter.val + 1, filed: "2026-05-01", form: "10-Q/A" };
+  expect(parseBank([quarter, amended, { ...repeat, val: amended.val }]).quarterlyStatements[0]).toMatchObject({
+    totalRevenue: amended.val, fieldAvailability: { totalRevenue: "2026-05-01" },
+  });
+});

package/src/sources/sec-edgar.ts

@@ -1,5 +1,8 @@
+import { contradictsEarningsCohort, parseReportedEarningsCohorts, type ReportedEarningsCohort } from "../utils/reported-earnings-result";
 import type { SecFilingDocument, SecFilingItem } from "../types/data-provider";
 import type { FinancialStatement, IncomeStatementSource } from "../types/financials";
+import { parseReportedOperatingCohorts, promoteReportedOperatingResults, type ReportedOperatingCohort } from "../utils/operating-result";
+import { parseShopOperatingTable } from "../utils/shop-operating-table";
 import { INCOME_STATEMENT_FIELDS } from "../utils/income-statement";
 import { withdrawKnownSecQuarter } from "../utils/statement-observations";
 import { createSecEpsBasisResolver } from "../utils/sec-eps-basis";
@@ -78,9 +81,12 @@ type CompanyFactsStatementField = {
   units: string[];
   periodType: "duration" | "instant";
   transform?: (value: number) => number;
+  /** Last tag, used only while it measures the same thing as the filer's other tags. */
+  sameMeasureFallback?: string;
 };
 
 export type SecCompanyFactsStatements = {
+  reportedEarningsResults?: ReportedEarningsCohort[];
   annualStatements: FinancialStatement[];
   quarterlyStatements: FinancialStatement[];
 };
@@ -88,11 +94,13 @@ export type SecCompanyFactsStatements = {
 const COMPANY_FACTS_STATEMENT_FIELDS: CompanyFactsStatementField[] = [
   {
     field: "totalRevenue",
-    tags: ["RevenueFromContractWithCustomerExcludingAssessedTax", "Revenues", "SalesRevenueNet"],
+    tags: ["RevenueFromContractWithCustomerExcludingAssessedTax", "Revenues", "SalesRevenueNet", "RevenuesNetOfInterestExpense"],
     units: ["USD"],
     periodType: "duration",
+    sameMeasureFallback: "RevenuesNetOfInterestExpense",
   },
   { field: "grossProfit", tags: ["GrossProfit"], units: ["USD"], periodType: "duration" },
+  { field: "operatingExpense", tags: ["OperatingExpenses"], units: ["USD"], periodType: "duration" },
   { field: "operatingIncome", tags: ["OperatingIncomeLoss"], units: ["USD"], periodType: "duration" },
   { field: "netIncome", tags: ["NetIncomeLoss"], units: ["USD"], periodType: "duration" },
   { field: "netIncomeIncludingNoncontrollingInterests", tags: ["ProfitLoss"], units: ["USD"], periodType: "duration" },
@@ -508,6 +516,16 @@ function isQuarterlyCompanyFact(entry: CompanyFactsEntry, periodType: "duration"
         && /^Q[1-3]$/.test(normalize(entry.fp ?? undefined))
       );
   }
+  if (entry.concept === "RevenuesNetOfInterestExpense") {
+    // A quarterly frame cannot turn bank revenue reported year-to-date into
+    // a direct quarter. Keep the source's net-of-interest amount unchanged.
+    const start = Date.parse(`${entry.start}T00:00:00Z`);
+    const end = Date.parse(`${entry.end}T00:00:00Z`);
+    const days = (end - start) / 86_400_000;
+    if (!Number.isFinite(days) || days < 60 || days > 120
+      || new Date(start).toISOString().slice(0, 10) !== entry.start
+      || new Date(end).toISOString().slice(0, 10) !== entry.end) return false;
+  }
   if (/^CY\d{4}Q[1-4]$/.test(entry.frame ?? "")) return true;
   const form = normalize(entry.form);
   const fiscalPeriod = normalize(entry.fp ?? undefined);
@@ -653,6 +671,20 @@ function finalizeCompanyFactsStatements(rows: Map<string, FinancialStatement>, s
   return statements;
 }
 
+// Filling gaps per period from a concept with another definition mixes two
+// measures in one series (AXP fee revenue next to total net revenue). A filing
+// that reports both for one period with different values proves they differ.
+function withoutDifferentMeasureFallback(field: CompanyFactsStatementField, entries: CompanyFactsEntry[]): CompanyFactsEntry[] {
+  const fallback = field.sameMeasureFallback;
+  if (!fallback) return entries;
+  const periodKey = (entry: CompanyFactsEntry) => `${entry.accn}:${entry.start}:${entry.end}`;
+  const fallbackValues = new Map(entries.filter((entry) => entry.concept === fallback)
+    .map((entry) => [periodKey(entry), entry.val]));
+  const differs = entries.some((entry) => entry.concept !== fallback
+    && fallbackValues.has(periodKey(entry)) && fallbackValues.get(periodKey(entry)) !== entry.val);
+  return differs ? entries.filter((entry) => entry.concept !== fallback) : entries;
+}
+
 export function parseCompanyFactsFinancialStatements(payload: unknown): SecCompanyFactsStatements {
   const annualRows = new Map<string, FinancialStatement>();
   const quarterlyRows = new Map<string, FinancialStatement>();
@@ -660,8 +692,8 @@ export function parseCompanyFactsFinancialStatements(payload: unknown): SecCompa
   const quarterlySelectedFacts = new Map<string, CompanyFactsEntry>();
   const fieldEntries = COMPANY_FACTS_STATEMENT_FIELDS.map((field) => ({
     field,
-    entries: field.tags.flatMap((tag, tagPriority) => companyFactsEntries(payload, tag, field.units)
-      .map((entry) => ({ ...entry, tagPriority, concept: tag }))),
+    entries: withoutDifferentMeasureFallback(field, field.tags.flatMap((tag, tagPriority) => companyFactsEntries(payload, tag, field.units)
+      .map((entry) => ({ ...entry, tagPriority, concept: tag })))),
   }));
   // Balance-sheet facts have no duration. Anchor their dates to actual annual
   // periods, so quarterly comparative snapshots in a 10-K stay quarterly.
@@ -676,14 +708,27 @@ export function parseCompanyFactsFinancialStatements(payload: unknown): SecCompa
   }
 
   const resolveEps = createSecEpsBasisResolver(payload);
-  return withdrawKnownSecQuarter({
+  const statements = withdrawKnownSecQuarter({
     annualStatements: finalizeCompanyFactsStatements(annualRows, annualSelectedFacts, resolveEps),
     quarterlyStatements: finalizeCompanyFactsStatements(quarterlyRows, quarterlySelectedFacts, resolveEps),
   }, companyFactsRecord(payload)?.cik);
+  const cohorts = parseReportedOperatingCohorts(payload, "0001594805");
+  if (cohorts.length) {
+    statements.annualStatements = promoteReportedOperatingResults(statements.annualStatements, cohorts, "annual");
+    statements.quarterlyStatements = promoteReportedOperatingResults(statements.quarterlyStatements, cohorts, "quarterly");
+  }
+  return statements;
 }
 
 export class SecEdgarClient {
+  private asmlEarnings?: { cohorts: ReportedEarningsCohort[]; expiresAt: number; fetchedAt: number };
+  private asmlEarningsPromise?: Promise<ReportedEarningsCohort[]>;
+  private asmlEarningsRetryAt = 0;
   private lookupPromise: Promise<Map<string, LookupEntry>> | null = null;
+  private shopOperatingTables?: { cohorts: ReportedOperatingCohort[]; expiresAt: number };
+  private shopOperatingTablesPartial?: { cohorts: ReportedOperatingCohort[]; expiresAt: number };
+  private shopOperatingTablesPromise?: Promise<ReportedOperatingCohort[]>;
+  private shopOperatingTablesRetryAt = 0;
 
   private defaultHeaders() {
     return {
@@ -800,17 +845,158 @@ export class SecEdgarClient {
     return filings;
   }
 
-  async getFinancialStatements(ticker: string): Promise<SecCompanyFactsStatements | null> {
+  private loadShopOperatingTables(entry: LookupEntry): Promise<ReportedOperatingCohort[]> {
+    if (entry.cik !== "0001594805" || normalize(entry.exchange) !== "NASDAQ") return Promise.resolve([]);
+    if (this.shopOperatingTables && this.shopOperatingTables.expiresAt > Date.now()) return Promise.resolve(this.shopOperatingTables.cohorts);
+    if (this.shopOperatingTablesPartial && this.shopOperatingTablesPartial.expiresAt > Date.now()) return Promise.resolve(this.shopOperatingTablesPartial.cohorts);
+    if (this.shopOperatingTablesRetryAt > Date.now()) return Promise.resolve(this.previousShopOperatingTables());
+    if (this.shopOperatingTablesPromise) return this.shopOperatingTablesPromise;
+    const pending = (async () => {
+      const payload = await this.fetchJson<unknown>(`${SUBMISSIONS_URL}/CIK${entry.cik}.json`);
+      if (zeroPadCik(asRecord(payload)?.cik) !== entry.cik) throw new Error("SEC operating submissions issuer mismatch");
+      // One current submissions response and at most two primary documents.
+      // No archive crawl and no accession/period-specific production constants.
+      const recent = parseRecentFilings(payload, 1000)
+        .filter(filing => filing.cik === entry.cik && /^(10-K|10-Q)(\/A)?$/.test(filing.form))
+        .sort((a, b) => b.filingDate.getTime() - a.filingDate.getTime() || b.accessionNumber.localeCompare(a.accessionNumber));
+      const filings = ["10-K", "10-Q"].flatMap(form => {
+        const filing = recent.find(item => item.form === form || item.form === `${form}/A`);
+        return filing ? [filing] : [];
+      });
+      if (!filings.length) throw new Error("SEC operating filings are unavailable");
+      const results = await Promise.allSettled(filings.map(async filing => {
+        // An unsupported latest filing must not silently select an older one.
+        if (!/^(10-K|10-Q)$/.test(filing.form)
+          || !/^0001594805-\d{2}-\d{6}$/.test(filing.accessionNumber)
+          || !/^[A-Za-z0-9_-]+\.html?$/.test(filing.primaryDocument ?? "")) throw new Error("SEC operating filing is unsupported");
+        const documentUrl = filing.primaryDocumentUrl!;
+        const { body } = await this.fetchText(documentUrl);
+        const cohorts = parseShopOperatingTable(body, { cik: entry.cik, accessionNumber: filing.accessionNumber,
+          filed: filing.filingDate.toISOString().slice(0, 10), form: filing.form, documentUrl });
+        if (!cohorts.length) throw new Error("SEC operating table has no qualified quarters");
+        return cohorts;
+      }));
+      const supported = results.flatMap(result => result.status === "fulfilled" ? result.value : []);
+      if (!supported.length) throw new Error("SEC operating tables are unavailable");
+      if (filings.length === 2 && results.every(result => result.status === "fulfilled")) {
+        this.shopOperatingTables = { cohorts: supported, expiresAt: Date.now() + 6 * 60 * 60_000 };
+        this.shopOperatingTablesPartial = undefined;
+        this.shopOperatingTablesRetryAt = 0;
+        return supported;
+      }
+      // A qualified sibling remains evidence at its original filing date. Keep
+      // prior coverage without extending the complete snapshot's lifetime.
+      const cohorts = [...new Map([...this.previousShopOperatingTables(), ...supported].map(cohort => [
+        JSON.stringify([cohort.accessionNumber, cohort.startDate, cohort.endDate, cohort.origin]), cohort,
+      ])).values()];
+      this.shopOperatingTablesRetryAt = Date.now() + 60_000;
+      this.shopOperatingTablesPartial = { cohorts, expiresAt: this.shopOperatingTablesRetryAt };
+      return cohorts;
+    })().catch(() => {
+      this.shopOperatingTablesRetryAt = Date.now() + 60_000;
+      // Preserve the last qualified snapshot and original expiry on failure.
+      return this.previousShopOperatingTables();
+    });
+    this.shopOperatingTablesPromise = pending;
+    void pending.finally(() => { if (this.shopOperatingTablesPromise === pending) this.shopOperatingTablesPromise = undefined; });
+    return pending;
+  }
+
+  private previousShopOperatingTables(): ReportedOperatingCohort[] {
+    return this.shopOperatingTablesPartial?.cohorts ?? this.shopOperatingTables?.cohorts ?? [];
+  }
+
+  /** Let the outer financial cache revisit an incomplete optional acquisition. */
+  getOperatingTablesRetryAt(ticker: string): number | undefined {
+    if (normalize(ticker) !== "SHOP") return undefined;
+    if (this.shopOperatingTables && this.shopOperatingTables.expiresAt > Date.now()) return undefined;
+    if (this.shopOperatingTablesPromise) return Date.now() + 60_000;
+    return this.shopOperatingTablesRetryAt || Date.now() + 60_000;
+  }
+
+  private previousAsmlEarnings(): ReportedEarningsCohort[] {
+    const age = this.asmlEarnings ? Date.now() - this.asmlEarnings.fetchedAt : Infinity;
+    return age >= 0 && age <= 24 * 60 * 60_000 ? this.asmlEarnings!.cohorts : [];
+  }
+
+  /** Optional EUR/20-F projection; it never widens the generic USD parser. */
+  private loadAsmlEarnings(): Promise<ReportedEarningsCohort[]> {
+    if (this.previousAsmlEarnings().length && this.asmlEarnings!.expiresAt > Date.now()) return Promise.resolve(this.asmlEarnings!.cohorts);
+    if (this.asmlEarningsPromise) return this.asmlEarningsPromise;
+    if (this.asmlEarningsRetryAt > Date.now()) return Promise.resolve(this.previousAsmlEarnings());
+    const pending = (async () => {
+      const entry = (await this.loadLookup()).get("ASML");
+      if (entry?.cik !== "0000937966" || normalize(entry.exchange) !== "NASDAQ") throw new Error("SEC earnings issuer mismatch");
+      const payload = await this.fetchJson<unknown>(`${COMPANY_FACTS_URL}/CIK${entry.cik}.json`);
+      if (zeroPadCik(asRecord(payload)?.cik) !== entry.cik) throw new Error("SEC companyfacts issuer mismatch");
+      const fresh = parseReportedEarningsCohorts(payload, entry.cik);
+      const complete = ["2022-12-31", "2023-12-31"].every(end => fresh.some(group => group.endDate === end));
+      const keys = new Set(fresh.map(group => `${group.endDate}:${group.accessionNumber}`));
+      const retained = complete ? [] : this.previousAsmlEarnings().filter(group =>
+        !keys.has(`${group.endDate}:${group.accessionNumber}`) && !contradictsEarningsCohort(payload, group));
+      const cohorts = [...retained, ...fresh];
+      this.asmlEarningsRetryAt = complete ? 0 : Date.now() + 60_000;
+      this.asmlEarnings = { cohorts, expiresAt: complete ? Date.now() + 6 * 60 * 60_000 : 0,
+        fetchedAt: retained.length ? this.asmlEarnings!.fetchedAt : Date.now() };
+      return cohorts;
+    })().catch(() => {
+      this.asmlEarningsRetryAt = Date.now() + 60_000;
+      return this.previousAsmlEarnings();
+    });
+    this.asmlEarningsPromise = pending;
+    void pending.finally(() => { if (this.asmlEarningsPromise === pending) this.asmlEarningsPromise = undefined; });
+    return pending;
+  }
+
+  getEarningsHistoryRetryAt(): number | undefined {
+    return this.asmlEarningsPromise ? Date.now() + 60_000 : this.asmlEarningsRetryAt || undefined;
+  }
+
+  private async asmlEarningsWithinBudget(): Promise<ReportedEarningsCohort[]> {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      return await Promise.race([
+        this.loadAsmlEarnings(),
+        new Promise<ReportedEarningsCohort[]>(resolve => {
+          timer = setTimeout(() => resolve(this.previousAsmlEarnings()), 750);
+        }),
+      ]);
+    } finally { if (timer) clearTimeout(timer); }
+  }
+
+  async getFinancialStatements(ticker: string, options: { reportedOperatingResults?: boolean; reportedEarningsResults?: boolean } = {}): Promise<SecCompanyFactsStatements | null> {
     const normalizedTicker = normalize(ticker);
     if (!normalizedTicker) return null;
 
+    if (options.reportedEarningsResults && normalizedTicker === "ASML") return {
+      annualStatements: [], quarterlyStatements: [], reportedEarningsResults: await this.asmlEarningsWithinBudget(),
+    };
     const lookup = await this.loadLookup();
     const entry = lookup.get(normalizedTicker) ?? lookup.get(normalizedTicker.replace(/\./g, "-"));
     if (!entry) return null;
 
-    const payload = await this.fetchJson<unknown>(`${COMPANY_FACTS_URL}/CIK${entry.cik}.json`);
-    if (zeroPadCik(asRecord(payload)?.cik) !== entry.cik) throw new Error("SEC companyfacts issuer mismatch");
+    const operatingTarget = options.reportedOperatingResults && normalizedTicker === "SHOP"
+      && entry.cik === "0001594805" && normalize(entry.exchange) === "NASDAQ";
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const [companyFacts, tableResult] = await Promise.allSettled([
+      this.fetchJson<unknown>(`${COMPANY_FACTS_URL}/CIK${entry.cik}.json`).then(payload => {
+        if (zeroPadCik(asRecord(payload)?.cik) !== entry.cik) throw new Error("SEC companyfacts issuer mismatch");
+        return payload;
+      }),
+      operatingTarget ? Promise.race([
+        this.loadShopOperatingTables(entry),
+        new Promise<ReportedOperatingCohort[]>(resolve => { timer = setTimeout(() => resolve(this.previousShopOperatingTables()), 750); }),
+      ]).finally(() => { if (timer) clearTimeout(timer); }) : Promise.resolve([] as ReportedOperatingCohort[]),
+    ]);
+    const tables = tableResult.status === "fulfilled" ? tableResult.value : [];
+    if (companyFacts.status === "rejected" && !tables.length) throw companyFacts.reason;
+    const payload = companyFacts.status === "fulfilled" ? companyFacts.value : undefined;
     const statements = parseCompanyFactsFinancialStatements(payload);
+    if (operatingTarget) {
+      const cohorts = [...parseReportedOperatingCohorts(payload, entry.cik), ...tables];
+      statements.annualStatements = promoteReportedOperatingResults(statements.annualStatements, cohorts, "annual");
+      statements.quarterlyStatements = promoteReportedOperatingResults(statements.quarterlyStatements, cohorts, "quarterly");
+    }
     if (/[.-]/.test(normalizedTicker)) {
       for (const row of [...statements.annualStatements, ...statements.quarterlyStatements]) {
         for (const field of ["eps", "basicShares", "dilutedShares"] as const) {