gloomberb 0.16.0 → 0.16.2

package/src/plugins/builtin/doe/range-bar.tsx

@@ -1,45 +1,15 @@
+import { RangeTrack } from "../../../components/ui/range-track";
 import { useThemeColors } from "../../../theme/theme-context";
-import { Box, Text, useUiCapabilities } from "../../../ui";
-
-/** Where a marker sits on a track of `cells`, and whether it is past an end. */
-function rangeMarker(position: number, cells: number): { index: number; outside: "below" | "above" | null } {
-  const last = Math.max(0, cells - 1);
-  if (position < 0) return { index: 0, outside: "below" };
-  if (position > 100) return { index: last, outside: "above" };
-  return { index: Math.round((position / 100) * last), outside: null };
-}
+import { Text } from "../../../ui";
 
 /**
- * The value's place in its five-year range: the low at the left, the high at
- * the right, a marker past an end when the value is outside it. The desktop
- * draws real elements; the terminal a rule of cells, so box-drawing glyphs
- * never reach the browser renderer.
+ * The value's place in its five-year range (`position` 0 to 100): the low at
+ * the left, the high at the right, an amber arrow past an end when the value
+ * is outside it.
  */
 export function DoeRangeBar({ position, width }: { position: number | null; width: number }) {
   const colors = useThemeColors();
-  const isDesktopWeb = useUiCapabilities().nativePaneChrome === true;
   if (position == null || width < 3) return <Text fg={colors.textDim}>{""}</Text>;
-  const cells = Math.max(3, width - 1);
-  const marker = rangeMarker(position, cells);
-  const markerColor = marker.outside ? colors.warning : colors.textBright;
-  if (isDesktopWeb) {
-    const left = marker.outside === "below" ? 0 : marker.outside === "above" ? 100 : position;
-    return (
-      <Box width={cells} height={1} style={{ position: "relative", justifyContent: "center" }}>
-        <Box style={{ position: "absolute", left: 0, right: 0, height: "2px", borderRadius: "1px", backgroundColor: colors.border }} />
-        <Box style={{
-          position: "absolute", left: `${left}%`, width: "8px", height: "8px", marginLeft: "-4px",
-          borderRadius: marker.outside ? "1px" : "50%", backgroundColor: markerColor,
-        }} />
-      </Box>
-    );
-  }
-  const glyph = marker.outside === "below" ? "◂" : marker.outside === "above" ? "▸" : "●";
-  return (
-    <Box width={cells} flexDirection="row">
-      <Text fg={colors.border}>{"─".repeat(marker.index)}</Text>
-      <Text fg={markerColor}>{glyph}</Text>
-      <Text fg={colors.border}>{"─".repeat(Math.max(0, cells - marker.index - 1))}</Text>
-    </Box>
-  );
+  const outside = position < 0 || position > 100;
+  return <RangeTrack position={position / 100} width={Math.max(3, width - 1)} markerColor={outside ? colors.warning : colors.textBright} outside />;
 }

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

@@ -70,9 +70,9 @@ export async function fetchEarningsCalendar(query: EarningsCalendarQuery, client
   }
 }
 
-export async function fetchEarningsHistory(symbol: string, client: HistoryClient = apiClient) {
+export async function fetchEarningsHistory(symbol: string, client: HistoryClient = apiClient, limit?: number) {
   try {
-    return validateEarningsHistory(await client.getCloudEarningsHistory(symbol), symbol);
+    return validateEarningsHistory(await client.getCloudEarningsHistory(symbol, limit), symbol);
   } catch (error) {
     throw unavailableOnServer(error, "Earnings history is not available yet.", [404, 503]);
   }

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

@@ -3,6 +3,7 @@ import type {
   HeadlessPaneColumn,
   HeadlessPaneContext,
   HeadlessPaneDefinition,
+  HeadlessPaneFreshness,
   HeadlessPaneLoadArgs,
   HeadlessRowsResult,
 } from "../../../types/plugin";
@@ -137,9 +138,12 @@ async function historyReport(symbol: string, context: HeadlessPaneContext, deps:
 }
 
 /** EVTS: the market board, whatever ticker is given. */
+const EARNINGS_CALENDAR: HeadlessPaneFreshness = { status: "not-a-feed", basis: "calendar" };
+
 function createEarningsBoardHeadless(deps: EarningsHeadlessDependencies = defaultDependencies): HeadlessPaneDefinition<"rows"> {
   return {
     shape: "rows",
+    freshness: EARNINGS_CALENDAR,
     argument: { kind: "ticker", placeholder: "ticker", description: "Optional; the board is the same.", minimum: 0, maximum: 1 },
     options: [
       { key: "limit", description: "Maximum rows.", type: "integer", defaultValue: 200, minimum: 1, maximum: 1000 },
@@ -155,6 +159,7 @@ function createEarningsBoardHeadless(deps: EarningsHeadlessDependencies = defaul
 function createEarningsHeadless(deps: EarningsHeadlessDependencies = defaultDependencies): HeadlessPaneDefinition<"rows"> {
   return {
     shape: "rows",
+    freshness: EARNINGS_CALENDAR,
     argument: {
       kind: "symbol-list",
       placeholder: "tickers",

package/src/plugins/builtin/earnings-calls/headless.ts

@@ -186,6 +186,7 @@ export function createEarningsCallsHeadless(
 ): HeadlessPaneDefinition<"rows"> {
   return {
     shape: "rows",
+    freshness: { source: "Company earnings calls", status: "not-a-feed", basis: "transcripts" },
     argument: {
       kind: "ticker",
       placeholder: "ticker",

package/src/plugins/builtin/earnings-calls/index.tsx

@@ -36,6 +36,7 @@ export const earningsCallsModule: PluginModule = {
       icon: "C",
       component: EarningsCallsPane,
       defaultPosition: "right",
+      tickerFollower: true,
       defaultMode: "floating",
       defaultFloatingSize: { width: 100, height: 30 },
       tableExport: true,

package/src/plugins/builtin/earnings-ripple/client.ts

@@ -1,60 +1,133 @@
 import type { EarningsCalendarPayload, EarningsCalendarQuery } from "../../../api-client/earnings";
 import type { SupplyChainPayload } from "../../../api-client/supply-chain";
+import { DEFAULT_GRAPH_OPTIONS, type GraphOptions, type GraphPayload } from "../../../api-client/supply-chain-graph";
 import { errorMessage } from "../../../utils/errors";
 import { addDays, newYorkToday } from "../earnings/board-model";
 import { loadEarningsBoard } from "../earnings/client";
 import { loadSupplyChain } from "../supply-chain/client";
-import { projectRipple, rippleCompanyTickers, RIPPLE_DAYS, type RippleRow } from "./model";
+import { cachedGraph, loadGraph } from "../supply-chain/graph-client";
+import { projectRipple, projectSecondHop, rippleCompanyTickers, RIPPLE_DAYS, secondHopLinks, type RippleRow, type SecondHopRow } from "./model";
 
 export interface RippleSources {
   supplyChain(symbol: string): Promise<SupplyChainPayload>;
   calendar(query: EarningsCalendarQuery): Promise<EarningsCalendarPayload>;
+  /** SPLC's graph, which returns both hops around a holding in one call. Absent when the account sees one hop only. */
+  graph?(symbol: string, options: GraphOptions): Promise<GraphPayload>;
 }
 
+/**
+ * The graph query behind the 2 hops tab. Supplier and customer links only, and
+ * only evidence from filings, company announcements and calls (graph classes
+ * structured and primary), the tiers the 1 hop tab's disclosures are read with.
+ * The server filters before it ranks and caps each direction, so news and
+ * partner routes cannot use up the 50 companies a direction returns.
+ */
+const RIPPLE_GRAPH_OPTIONS: GraphOptions = { ...DEFAULT_GRAPH_OPTIONS, depth: 2, roles: ["customer", "supplier"], tiers: ["structured", "primary"] };
+
+/**
+ * What opens SPLC's Path view on a 2 hops row: from the holding to the company
+ * that reports, on RIPL's own query in the row's direction, so the route the
+ * row shows is the one Path lists.
+ */
+export function rippleRouteSettings(row: Pick<SecondHopRow, "company" | "link">): Record<string, string> {
+  return { tab: "path", to: row.company, depth: String(RIPPLE_GRAPH_OPTIONS.depth), direction: row.link === "supplier" ? "upstream" : "downstream",
+    roles: RIPPLE_GRAPH_OPTIONS.roles.join(","), tiers: RIPPLE_GRAPH_OPTIONS.tiers.join(",") };
+}
+
+interface Failure { symbol: string; error: string }
+
 export interface RippleSnapshot {
   rows: RippleRow[];
   /** Holdings whose disclosures could not be read, with the reason. */
-  failures: { symbol: string; error: string }[];
+  failures: Failure[];
   /** Holdings whose disclosures the free preview cut short, so a missing link may only be hidden. */
   truncated: string[];
+  /**
+   * Companies two hops away, when asked for. `locked`: the account sees one hop
+   * only. `truncated`: holdings whose graph search stopped at a limit, with the
+   * server's reasons, so a company missing there may only be cut off.
+   */
+  secondHop: { rows: SecondHopRow[]; failures: Failure[]; truncated: { symbol: string; reasons: string[] }[]; locked: boolean } | null;
   stale: boolean;
   from: string;
   to: string;
 }
 
-/** The same caches SPLC and ERN fill, so opening either pane after this costs nothing. */
-export function cachedRippleSources(accessKey: string, force = false): RippleSources & { staleFlags: boolean[] } {
+/**
+ * The same caches SPLC and ERN fill, so opening either pane after this costs
+ * nothing. `graph`: no graph source, graphs read through the cache, or graphs
+ * from the cache alone (fetched only when missing) while 2 hops is not on screen.
+ */
+export function cachedRippleSources(accessKey: string, force = false, graph: "off" | "load" | "cached" = "off"): RippleSources & { staleFlags: boolean[] } {
   const staleFlags: boolean[] = [];
   return {
     staleFlags,
     supplyChain: async (symbol) => { const result = await loadSupplyChain(symbol, accessKey, force); staleFlags.push(result.stale); return result.payload; },
     calendar: async (query) => { const result = await loadEarningsBoard(query, force); staleFlags.push(result.stale); return result.payload; },
+    // Cached by the full query, apart from SPLC Graph's default one.
+    ...(graph !== "off" ? { graph: async (symbol: string, options: GraphOptions) => {
+      const cached = graph === "cached" ? cachedGraph(symbol, "", options, accessKey) : null;
+      const result = cached ?? await loadGraph(symbol, "", options, accessKey, force); staleFlags.push(result.stale); return result.payload;
+    } } : {}),
   };
 }
 
 const CONCURRENCY = 6;
 
-export async function loadRipple(holdings: readonly string[], sources: RippleSources & { staleFlags?: boolean[] }, now = new Date()): Promise<RippleSnapshot> {
+async function eachLimited(symbols: readonly string[], load: (symbol: string) => Promise<void>) {
+  const queue = [...symbols];
+  await Promise.all(Array.from({ length: Math.min(CONCURRENCY, queue.length) }, async () => {
+    for (let symbol = queue.shift(); symbol; symbol = queue.shift()) await load(symbol);
+  }));
+}
+
+const locked = () => ({ graphs: new Map<string, GraphPayload>(), failures: [] as Failure[], locked: true });
+const isPreview = (graphs: ReadonlyMap<string, GraphPayload>) => [...graphs.values()].some((graph) => graph.access === "preview");
+
+/** One graph call per holding. The first answer says whether the account sees two hops; a one-hop preview skips the rest. */
+async function loadGraphs(holdings: readonly string[], graph: NonNullable<RippleSources["graph"]>) {
+  const graphs = new Map<string, GraphPayload>();
+  const failures: Failure[] = [];
+  const load = async (symbol: string) => {
+    try { graphs.set(symbol, await graph(symbol, RIPPLE_GRAPH_OPTIONS)); }
+    catch (error) { failures.push({ symbol, error: errorMessage(error) }); }
+  };
+  const [first, ...rest] = holdings;
+  if (first) await load(first);
+  if (isPreview(graphs)) return locked();
+  await eachLimited(rest, load);
+  // Only when the first holding failed can a preview get this far.
+  if (isPreview(graphs)) return locked();
+  return { graphs, failures: failures.sort((a, b) => a.symbol.localeCompare(b.symbol)), locked: false };
+}
+
+export async function loadRipple(holdings: readonly string[], sources: RippleSources & { staleFlags?: boolean[] }, now = new Date(), { secondHop = false } = {}): Promise<RippleSnapshot> {
   const from = newYorkToday(now);
   const to = addDays(from, RIPPLE_DAYS);
+  const symbols = [...new Set(holdings.map((symbol) => symbol.toUpperCase()))];
   const chains = new Map<string, SupplyChainPayload>();
-  const failures: RippleSnapshot["failures"] = [];
-  const queue = [...new Set(holdings.map((symbol) => symbol.toUpperCase()))];
-  await Promise.all(Array.from({ length: Math.min(CONCURRENCY, queue.length) }, async () => {
-    for (let symbol = queue.shift(); symbol; symbol = queue.shift()) {
-      try { chains.set(symbol, await sources.supplyChain(symbol)); }
-      catch (error) { failures.push({ symbol, error: errorMessage(error) }); }
-    }
-  }));
-  const companies = rippleCompanyTickers(chains);
+  const failures: Failure[] = [];
+  await eachLimited(symbols, async (symbol) => {
+    try { chains.set(symbol, await sources.supplyChain(symbol)); }
+    catch (error) { failures.push({ symbol, error: errorMessage(error) }); }
+  });
+  const second = !secondHop ? null : sources.graph ? await loadGraphs(symbols, sources.graph) : locked();
+  const graphs = second?.graphs ?? new Map<string, GraphPayload>();
+  const companies = [...rippleCompanyTickers(chains), ...secondHopLinks(chains, graphs).map((link) => link.company.ticker!.toUpperCase())];
   const reports: EarningsCalendarPayload["reports"] = [];
   if (companies.length) {
-    const symbols = [...new Set([...companies, ...holdings.map((symbol) => symbol.toUpperCase())])].sort();
-    for (let offset = 0; offset < symbols.length; offset += 200) {
-      const payload = await sources.calendar({ from, to, perDay: 0, symbols: symbols.slice(offset, offset + 200) });
+    const calendarSymbols = [...new Set([...companies, ...symbols])].sort();
+    for (let offset = 0; offset < calendarSymbols.length; offset += 200) {
+      const payload = await sources.calendar({ from, to, perDay: 0, symbols: calendarSymbols.slice(offset, offset + 200) });
       reports.push(...payload.reports);
     }
   }
   const truncated = [...chains].filter(([, chain]) => chain.truncated).map(([symbol]) => symbol).sort();
-  return { rows: projectRipple(chains, reports), failures, truncated, stale: !!sources.staleFlags?.some(Boolean), from, to };
+  return {
+    rows: projectRipple(chains, reports), failures, truncated,
+    secondHop: second ? { rows: projectSecondHop(chains, graphs, reports), failures: second.failures, locked: second.locked,
+      truncated: [...graphs].filter(([, graph]) => graph.truncated || !graph.search.complete)
+        .map(([symbol, graph]) => ({ symbol, reasons: graph.search.reasons })).sort((a, b) => a.symbol.localeCompare(b.symbol)) } : null,
+    stale: !!sources.staleFlags?.some(Boolean), from, to,
+  };
 }

package/src/plugins/builtin/earnings-ripple/headless.ts

@@ -1,35 +1,55 @@
 import type { HeadlessPaneDefinition } from "../../../types/plugin";
 import { fetchEarningsCalendar } from "../earnings/client";
 import { fetchSupplyChain } from "../supply-chain/client";
+import { fetchSupplyGraph } from "../supply-chain/graph-client";
 import { loadRipple } from "./client";
-import { revenueOwner } from "./model";
+import { hopLabel, revenueOwner } from "./model";
 
 const percent = (value: unknown) => typeof value === "number" ? `${(value * 100).toFixed(1)}%` : "--";
 
 export const earningsRippleHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle",
+  freshness: { source: "SEC filings and Gloom Cloud", status: "not-a-feed", basis: "filings and earnings calendar" },
   argument: { kind: "symbol-list", placeholder: "tickers", description: "Holdings to check against their customers' and suppliers' report dates.", minimum: 1, maximum: 60 },
-  options: [],
+  options: [{ key: "tab", type: "enum", settingKey: "tab", defaultValue: "direct", values: [{ value: "direct" }, { value: "two-hop" }],
+    description: "Direct customers and suppliers, or also companies two hops away (Pro)." }],
   describe: (args) => `RIPL ${args.symbols.join(", ")}`,
-  discovery: { screenshotReadiness: "live-dom", limitations: ["Customers each holding names in its own US filings, and suppliers whose US filings name it, with a share of revenue."] },
+  discovery: { screenshotReadiness: "live-dom", limitations: ["Customers each holding names in its own US filings, and suppliers whose US filings name it, with a share of revenue.",
+    "Two hops: a supplier's supplier or a customer's customer from the supply chain graph, read from filings, company announcements and calls only, Pro only; companies already one hop away are left out."] },
   async load(args, ctx) {
+    const secondHop = args.options.tab === "two-hop";
     const snapshot = await loadRipple(args.symbols, {
       supplyChain: (symbol) => fetchSupplyChain(symbol, ctx.apiClient),
       calendar: (query) => fetchEarningsCalendar(query, ctx.apiClient),
-    });
+      graph: (symbol, options) => fetchSupplyGraph(symbol, options, "", ctx.apiClient),
+    }, undefined, { secondHop });
     ctx.signal.throwIfAborted();
+    const second = snapshot.secondHop;
     return {
       sections: [{ title: `Customers and suppliers reporting ${snapshot.from} to ${snapshot.to}`, columns: [
         { key: "date", header: "Date" }, { key: "timing", header: "Time" }, { key: "company", header: "Reports" }, { key: "link", header: "Link" },
         { key: "holding", header: "Holding" }, { key: "pctOfRevenue", header: "Revenue %" }, { key: "revenueOf", header: "Of" }, { key: "averageMove", header: "Avg move", format: percent },
         { key: "holdingDate", header: "Holding reports" }, { key: "period", header: "Filing period" },
-      ], rows: snapshot.rows.map((row) => ({ ...row, timing: row.timing?.toUpperCase() ?? null, link: row.link === "customer" ? "customer of" : "supplier to", revenueOf: revenueOwner(row) })) }],
-      complete: snapshot.failures.length === 0 && snapshot.truncated.length === 0,
+      ], rows: snapshot.rows.map((row) => ({ ...row, timing: row.timing?.toUpperCase() ?? null, link: row.link === "customer" ? "customer of" : "supplier to", revenueOf: revenueOwner(row) })) },
+      ...(second && !second.locked ? [{ title: `Two hops away, reporting ${snapshot.from} to ${snapshot.to}`, columns: [
+        { key: "date", header: "Date" }, { key: "timing", header: "Time" }, { key: "company", header: "Reports" }, { key: "link", header: "Link" },
+        { key: "via", header: "Via" }, { key: "holding", header: "Holding" }, { key: "hop1", header: "Holding to via" }, { key: "hop2", header: "Via to company" },
+        { key: "exposure", header: "Estimated exposure" }, { key: "averageMove", header: "Avg move", format: percent }, { key: "holdingDate", header: "Holding reports" },
+      ], rows: second.rows.map((row) => ({ ...row, timing: row.timing?.toUpperCase() ?? null, link: row.link === "customer" ? "customer's customer" : "supplier's supplier",
+        hop1: hopLabel(row.hops[0]), hop2: hopLabel(row.hops[1]) })) }] : []),
+      ],
+      complete: snapshot.failures.length === 0 && snapshot.truncated.length === 0 && !second?.locked && !second?.failures.length && !second?.truncated.length,
       unavailableSymbols: snapshot.failures.map((failure) => failure.symbol),
       // Same wording as SPLC: the preview's cut hides relationships, it does not mean there are none.
       errors: [...snapshot.failures.map((failure) => `${failure.symbol}: ${failure.error}`),
-        ...(snapshot.truncated.length ? ["Additional relationships need Gloom Pro"] : [])],
-      metadata: { from: snapshot.from, to: snapshot.to, truncated: snapshot.truncated, unit: "percent of the seller's revenue, as the seller's filing discloses it", methodology: "docs/research-data.md#earnings-ripple" },
+        ...(snapshot.truncated.length ? ["Additional relationships need Gloom Pro"] : []),
+        ...(second?.locked ? ["Companies two hops away need Gloom Pro"] : []),
+        ...(second?.failures ?? []).map((failure) => `${failure.symbol} graph: ${failure.error}`),
+        // As SPLC words it: the graph stopped at a limit, so companies two hops away may be missing.
+        ...(second?.truncated ?? []).map(({ symbol, reasons }) => `${symbol}: ${reasons.length
+          ? `Graph search incomplete: ${reasons.join(", ").replaceAll("_", " ")}` : "Graph results are truncated"}`)],
+      metadata: { from: snapshot.from, to: snapshot.to, truncated: snapshot.truncated, ...(second ? { twoHopTruncated: second.truncated.map(({ symbol }) => symbol) } : {}),
+        unit: "percent of the seller's revenue, as the seller's filing discloses it", methodology: "docs/research-data.md#earnings-ripple" },
     };
   },
 };

package/src/plugins/builtin/earnings-ripple/index.tsx

@@ -18,8 +18,8 @@ export const earningsRippleModule: PluginModule = {
   }],
   paneTemplates: [{
     id: "earnings-ripple-pane", paneId: "earnings-ripple", label: "Earnings Ripple",
-    description: "Customers of your holdings that report soon, with the share of each holding's revenue they make up.",
-    keywords: ["ripl", "ripple", "earnings", "customers", "supply chain", "exposure", "read-through"],
+    description: "Customers and suppliers of your holdings that report soon, with the disclosed revenue share, and with Pro the companies two hops away.",
+    keywords: ["ripl", "ripple", "earnings", "customers", "supply chain", "exposure", "read-through", "suppliers", "two hop", "second order"],
     shortcut: { prefix: "RIPL", argPlaceholder: "tickers", argKind: "ticker-list", argOptional: true, openWithoutArg: true },
     headless: earningsRippleHeadless,
     canCreate: () => true,

package/src/plugins/builtin/earnings-ripple/model.ts

@@ -1,7 +1,9 @@
 import type { EarningsCalendarReport, EarningsTiming } from "../../../api-client/earnings";
-import type { SupplyChainPayload, SupplyRow } from "../../../api-client/supply-chain";
+import type { SupplyChainPayload, SupplyEntity, SupplyRow } from "../../../api-client/supply-chain";
+import type { GraphPath, GraphPayload } from "../../../api-client/supply-chain-graph";
 import { isUsListingExchange } from "../../../utils/exchanges";
 import { MIN_AVERAGE_REPORTS } from "../earnings/board-model";
+import { exposureLabel } from "../supply-chain/graph-model";
 
 /** Days ahead the calendar is read. */
 export const RIPPLE_DAYS = 30;
@@ -71,18 +73,24 @@ export function rippleCompanyTickers(chains: ReadonlyMap<string, SupplyChainPayl
   return [...companies];
 }
 
-/**
- * Customers a holding names in its own filings (`says`), and suppliers whose
- * filings name the holding as a customer (`names`), that report in the
- * calendar: soonest first, then by the share.
- */
-export function projectRipple(chains: ReadonlyMap<string, SupplyChainPayload>, reports: readonly EarningsCalendarReport[]): RippleRow[] {
+/** Each company's soonest report in the window. */
+function nextReports(reports: readonly EarningsCalendarReport[]) {
   const next = new Map<string, EarningsCalendarReport>();
   for (const report of reports) {
     const key = report.symbol.toUpperCase();
     const current = next.get(key);
     if (!current || report.date < current.date) next.set(key, report);
   }
+  return next;
+}
+
+/**
+ * Customers a holding names in its own filings (`says`), and suppliers whose
+ * filings name the holding as a customer (`names`), that report in the
+ * calendar: soonest first, then by the share.
+ */
+export function projectRipple(chains: ReadonlyMap<string, SupplyChainPayload>, reports: readonly EarningsCalendarReport[]): RippleRow[] {
+  const next = nextReports(reports);
   const rows: RippleRow[] = [];
   for (const [holding, chain] of chains) {
     for (const { row, link } of rippleLinks(chain)) {
@@ -96,3 +104,85 @@ export function projectRipple(chains: ReadonlyMap<string, SupplyChainPayload>, r
   }
   return rows.sort((a, b) => a.date.localeCompare(b.date) || b.pctOfRevenue - a.pctOfRevenue || a.holding.localeCompare(b.holding));
 }
+
+/** One hop of a two-hop route, with the share the reporting company's filing discloses. */
+export interface RippleHop {
+  /** Whose figure it is: the reporting company. */
+  owner: string;
+  pct: number | null;
+  basis: SupplyRow["pctBasis"];
+  scoped: boolean;
+}
+
+export interface SecondHopRow extends Omit<RippleRow, "pctOfRevenue" | "pctScope" | "period"> {
+  /** The company between the holding and the one that reports. */
+  via: string;
+  viaName: string;
+  /** Holding to via, then via to the company. */
+  hops: [RippleHop, RippleHop];
+  /** Chained estimate along the route, when every hop's figure is compatible. */
+  exposure: string | null;
+}
+
+const entityLabel = (entity: SupplyEntity) => entity.ticker?.toUpperCase() ?? entity.name;
+
+interface SecondHopLink { holding: string; company: SupplyEntity; via: SupplyEntity; link: "customer" | "supplier"; path: GraphPath; graph: GraphPayload }
+
+/**
+ * Companies two disclosed hops from each holding: a supplier's supplier
+ * (upstream) or a customer's customer (downstream). Anyone the holding already
+ * has a direct link with, in its disclosures or in the graph, is hop 1 and is
+ * left out, as are companies outside the US calendar. One row per holding and
+ * company: the higher-scoring route when both directions reach it.
+ */
+export function secondHopLinks(chains: ReadonlyMap<string, SupplyChainPayload>, graphs: ReadonlyMap<string, GraphPayload>): SecondHopLink[] {
+  const result: SecondHopLink[] = [];
+  for (const [holding, graph] of graphs) {
+    const chain = chains.get(holding);
+    const nodes = new Map(graph.nodes.map((node) => [node.id, node]));
+    const reaches = [...graph.upstream, ...graph.downstream];
+    const direct = new Set([holding.toUpperCase(),
+      ...[...chain?.says ?? [], ...chain?.names ?? []].flatMap((row) => row.counterparty.ticker ? [row.counterparty.ticker.toUpperCase()] : []),
+      ...reaches.filter((reach) => reach.hops === 1).flatMap((reach) => nodes.get(reach.entityId)?.ticker?.toUpperCase() ?? [])]);
+    const best = new Map<string, SecondHopLink>();
+    for (const reach of reaches) {
+      const path = reach.shortestPath;
+      const company = nodes.get(reach.entityId);
+      const via = nodes.get(path.nodeIds[1] ?? "");
+      const ticker = company?.ticker?.toUpperCase();
+      if (reach.hops !== 2 || path.hops !== 2 || !company || !via || !ticker || company.aggregate || direct.has(ticker)) continue;
+      if (company.exchange && !isUsListingExchange(company.exchange)) continue;
+      const current = best.get(ticker);
+      if (!current || path.score > current.path.score) best.set(ticker, { holding, company, via, link: reach.direction === "upstream" ? "supplier" : "customer", path, graph });
+    }
+    result.push(...best.values());
+  }
+  return result;
+}
+
+function hopShare(graph: GraphPayload, linkId: string): RippleHop {
+  const link = graph.links.find((entry) => entry.id === linkId);
+  const evidence = link?.evidence.find((item) => item.id === link.primaryEvidenceId);
+  return { owner: evidence ? entityLabel(evidence.reporter) : "--", pct: evidence?.pctOfRevenue ?? null, basis: evidence?.pctBasis ?? null, scoped: !!evidence?.pctScope };
+}
+
+/** `30% of TSM`, `12% of AVGO purchases`, or `--` where the filing names the link without a figure. */
+export function hopLabel(hop: RippleHop) {
+  if (hop.pct == null) return "--";
+  return `${hop.pct}%${hop.scoped ? "*" : ""} of ${hop.owner}${hop.basis && hop.basis !== "revenue" ? ` ${hop.basis}` : ""}`;
+}
+
+export function projectSecondHop(chains: ReadonlyMap<string, SupplyChainPayload>, graphs: ReadonlyMap<string, GraphPayload>, reports: readonly EarningsCalendarReport[]): SecondHopRow[] {
+  const next = nextReports(reports);
+  const rows: SecondHopRow[] = [];
+  for (const { holding, company, via, link, path, graph } of secondHopLinks(chains, graphs)) {
+    const ticker = company.ticker!.toUpperCase();
+    const report = next.get(ticker);
+    if (!report) continue;
+    rows.push({ id: `${holding}:${link}:2:${ticker}`, company: ticker, companyName: report.name ?? company.name, link, date: report.date, timing: report.timing,
+      averageMove: report.averageReports >= MIN_AVERAGE_REPORTS ? report.averageMove : null, holding, holdingDate: next.get(holding.toUpperCase())?.date ?? null,
+      via: entityLabel(via), viaName: via.name, hops: [hopShare(graph, path.linkIds[0]!), hopShare(graph, path.linkIds[1]!)],
+      exposure: path.exposure ? exposureLabel(path, graph) : null });
+  }
+  return rows.sort((a, b) => a.date.localeCompare(b.date) || a.holding.localeCompare(b.holding) || a.company.localeCompare(b.company));
+}