gloomberb 0.13.2 → 0.14.0

package/src/utils/price-history.test.ts

@@ -1,5 +1,38 @@
 import { describe, expect, test } from "bun:test";
-import { isPriceHistoryStaleForCurrentWindow, normalizePriceHistory } from "./price-history";
+import { isPriceHistoryStaleForCurrentWindow, normalizePriceHistory, priceHistoryIntervalMs } from "./price-history";
+
+describe("history freshness follows bar cadence", () => {
+  const now = Date.parse("2026-09-10T19:39:09Z");
+  const points = (dates: string[]) => dates.map((date) => ({ date: new Date(date), close: 709 }));
+
+  test("allows delayed completed bars without relaxing one-minute freshness", () => {
+    const history = points(["2026-09-10T18:45:00Z", "2026-09-10T19:00:00Z"]);
+    expect(isPriceHistoryStaleForCurrentWindow(history, now, { exchange: "NASDAQ", intervalMs: priceHistoryIntervalMs("15m") })).toBe(false);
+    expect(isPriceHistoryStaleForCurrentWindow(history, now, { exchange: "NASDAQ", intervalMs: priceHistoryIntervalMs("1m") })).toBe(true);
+    expect(isPriceHistoryStaleForCurrentWindow(history, now, { exchange: "NASDAQ", intervalMs: priceHistoryIntervalMs("5min") })).toBe(true);
+    expect(isPriceHistoryStaleForCurrentWindow(history, Date.parse("2026-09-10T19:46:00Z"), { exchange: "NASDAQ", intervalMs: priceHistoryIntervalMs("15m") })).toBe(true);
+    expect(isPriceHistoryStaleForCurrentWindow(points(["2026-09-10T17:30:00Z"]), now,
+      { exchange: "NASDAQ", intervalMs: priceHistoryIntervalMs("1h") })).toBe(false);
+  });
+
+  test("infers generic daily history across weekends and holidays, not a sparse intraday pair", () => {
+    const daily = points(["2026-09-04T00:00:00Z", "2026-09-08T00:00:00Z", "2026-09-09T00:00:00Z"]);
+    expect(isPriceHistoryStaleForCurrentWindow(daily, now, { exchange: "NASDAQ" })).toBe(false);
+    expect(isPriceHistoryStaleForCurrentWindow(daily, now, { exchange: "NASDAQ", intervalMs: priceHistoryIntervalMs("15m") })).toBe(true);
+    const sparse = points(["2026-09-09T19:00:00Z", "2026-09-10T19:00:00Z"]);
+    expect(isPriceHistoryStaleForCurrentWindow(sparse, now, { exchange: "NASDAQ" })).toBe(true);
+  });
+
+  test("keeps explicit weekly labels usable and still rejects prior-session intraday bars", () => {
+    expect(isPriceHistoryStaleForCurrentWindow(points(["2026-09-07T00:00:00Z"]), now,
+      { exchange: "NASDAQ", intervalMs: priceHistoryIntervalMs("1week") })).toBe(false);
+    const previousSession = points(["2026-09-09T18:45:00Z", "2026-09-09T19:00:00Z"]);
+    expect(isPriceHistoryStaleForCurrentWindow(previousSession, now,
+      { exchange: "NASDAQ", intervalMs: priceHistoryIntervalMs("15min") })).toBe(true);
+    expect(isPriceHistoryStaleForCurrentWindow(points(["2026-09-11T19:00:00Z"]), Date.parse("2026-09-13T19:39:09Z"),
+      { exchange: "NASDAQ", intervalMs: priceHistoryIntervalMs("15min") })).toBe(false);
+  });
+});
 
 describe("normalizePriceHistory", () => {
   test("drops poisoned cached history when every timestamp collapses to the same value", () => {
@@ -23,7 +56,7 @@ describe("normalizePriceHistory", () => {
     expect(history.map((point) => point.close)).toEqual([101, 102, 103]);
   });
 
-  test("drops zero-price bars instead of treating missing upstream prices as real data", () => {
+  test("retains dated missing closes and explicit zero without advancing freshness on missing values", () => {
     const history = normalizePriceHistory([
       { date: new Date("2026-05-13T13:30:00Z"), close: 64 },
       { date: new Date("2026-05-13T13:45:00Z"), close: 0 },
@@ -31,7 +64,12 @@ describe("normalizePriceHistory", () => {
       { date: new Date("2026-05-13T14:15:00Z"), close: 65 },
     ]);
 
-    expect(history.map((point) => point.close)).toEqual([64, 65]);
+    expect(history.map((point) => point.close)).toEqual([64, 0, Number.NaN, 65]);
+    expect(normalizePriceHistory([{ date: history[0]!.date, close: -10 }, { date: history[3]!.date, close: 0 }])
+      .map((point) => point.close)).toEqual([-10, 0]);
+    expect(normalizePriceHistory(history.slice(2, 3))).toEqual(history.slice(2, 3));
+    expect(isPriceHistoryStaleForCurrentWindow([history[0]!, { date: history[3]!.date, close: Number.NaN }],
+      Date.parse("2026-05-13T14:15:00Z"), { exchange: "NASDAQ", intervalMs: 60_000 })).toBe(true);
   });
 
   test("detects intraday history that is old even when the cache record is fresh", () => {

package/src/utils/price-history.ts

@@ -4,20 +4,81 @@ import { isTimestampStaleForExchangeSession } from "../market-data/market/freshn
 
 const MAX_CURRENT_INTRADAY_HISTORY_LAG_MS = 18 * 60 * 60 * 1000;
 const MAX_SAME_SESSION_HISTORY_LAG_MS = 30 * 60 * 1000;
+const DELAYED_HISTORY_ALLOWANCE_MS = 15 * 60 * 1000;
+const DAY_MS = 24 * 60 * 60 * 1000;
 
 interface PriceHistoryFreshnessOptions {
   exchange?: string;
+  intervalMs?: number | null;
 }
 
+export function priceHistoryIntervalMs(interval: string): number | null {
+  const match = /^(\d+)\s*(m|min|mins|minute|minutes|h|hr|hour|hours|d|day|days|w|wk|week|weeks|mo|month|months)$/i.exec(interval.trim());
+  if (!match) return null;
+  const count = Number(match[1]);
+  const unit = match[2]!.toLowerCase();
+  const step = /^(mo|month)/.test(unit) ? 30 * DAY_MS
+    : /^(w|wk|week)/.test(unit) ? 7 * DAY_MS
+    : /^(d|day)/.test(unit) ? DAY_MS
+    : /^(h|hr|hour)/.test(unit) ? 60 * 60 * 1000
+    : 60 * 1000;
+  return count > 0 && Number.isFinite(count * step) ? count * step : null;
+}
+
+function inferredHistoryIntervalMs(points: PricePoint[]): number | null {
+  const times = [...new Set(points.slice(-20).map(getPricePointTimestamp))];
+  const gaps = times.slice(1).map((time, index) => time - times[index]!);
+  const shortest = Math.min(...gaps);
+  if (shortest > 0 && shortest <= 60 * 60 * 1000) return shortest;
+  // A generic range does not specify bar size. Multiple daily labels can
+  // establish daily cadence; a single overnight gap between sparse intraday
+  // observations cannot. One-hour drift allows daily exchange opens over DST.
+  if (times.length >= 3 && shortest >= 20 * 60 * 60 * 1000) {
+    const clockTimes = times.map((time) => time % DAY_MS);
+    if (Math.max(...clockTimes) - Math.min(...clockTimes) <= 60 * 60 * 1000) return DAY_MS;
+  }
+  return null;
+}
+
+// Cached history carries ISO strings for dates, and every pass over a
+// series (normalizing, sorting, charting) parses each one again; a sort
+// comparator does it twice per comparison. Points are never edited in
+// place, so the parse is kept per point.
+const pointTimestamps = new WeakMap<PricePoint, number>();
+
 export function getPricePointTimestamp(point: PricePoint): number {
   const value = point.date as Date | string | number | null | undefined;
   if (value instanceof Date) return value.getTime();
   if (value == null) return Number.NaN;
-  return new Date(value).getTime();
+  const cached = pointTimestamps.get(point);
+  if (cached !== undefined) return cached;
+  const time = new Date(value).getTime();
+  pointTimestamps.set(point, time);
+  return time;
+}
+
+function hasFiniteClose(point: PricePoint): boolean {
+  return Number.isFinite(point.close);
 }
 
-function hasValidClose(point: PricePoint): boolean {
-  return Number.isFinite(point.close) && point.close > 0;
+/** Observation dates and usable price coverage are independent. */
+export function hasUsablePriceHistory(points: readonly PricePoint[]): boolean {
+  return points.some((point) => Number.isFinite(getPricePointTimestamp(point)) && hasFiniteClose(point));
+}
+
+/** A usable alternate source may recover a gap; uncovered reported dates remain gaps. */
+export function preservePriceHistoryGaps(points: PricePoint[], unavailable: readonly PricePoint[][]): PricePoint[] {
+  const times = new Set(points.map(getPricePointTimestamp));
+  const gaps: PricePoint[] = [];
+  for (const history of unavailable) {
+    for (const point of history) {
+      const time = getPricePointTimestamp(point);
+      if (!Number.isFinite(time) || hasFiniteClose(point) || times.has(time)) continue;
+      times.add(time);
+      gaps.push(point);
+    }
+  }
+  return gaps.length ? normalizePriceHistory([...points, ...gaps]) : points;
 }
 
 function comparePricePointsByDate(left: PricePoint, right: PricePoint): number {
@@ -32,9 +93,21 @@ function comparePricePointsByDate(left: PricePoint, right: PricePoint): number {
   return 0;
 }
 
+// The merged financials view is rebuilt on every quote tick and normalizes
+// the same history array each time. Arrays are replaced, not edited, so the
+// result is kept per input array.
+const normalizedHistories = new WeakMap<PricePoint[], PricePoint[]>();
+
 export function normalizePriceHistory(points: PricePoint[]): PricePoint[] {
   if (points.length === 0) return points;
+  const cached = normalizedHistories.get(points);
+  if (cached) return cached;
+  const normalized = normalizePriceHistoryUncached(points);
+  normalizedHistories.set(points, normalized);
+  return normalized;
+}
 
+function normalizePriceHistoryUncached(points: PricePoint[]): PricePoint[] {
   const validPoints: PricePoint[] = [];
   let sawDistinctTimestamp = false;
   let firstTimestamp: number | null = null;
@@ -44,7 +117,8 @@ export function normalizePriceHistory(points: PricePoint[]): PricePoint[] {
   for (const point of points) {
     const time = getPricePointTimestamp(point);
     if (!Number.isFinite(time)) continue;
-    if (!hasValidClose(point)) continue;
+    // Keep dated unavailable closes so downstream returns/charts cannot join
+    // their neighbors, including when the entire response is unavailable.
 
     if (firstTimestamp === null) {
       firstTimestamp = time;
@@ -75,13 +149,23 @@ export function isPriceHistoryStaleForCurrentWindow(
   options: PriceHistoryFreshnessOptions = {},
 ): boolean {
   const normalized = normalizePriceHistory(points);
-  const latest = normalized.at(-1);
+  const latest = normalized.findLast(hasFiniteClose);
   if (!latest) return false;
 
+  const intervalMs = options.intervalMs ?? inferredHistoryIntervalMs(normalized);
+  // Daily/weekly/monthly labels are period starts, not live observation times.
+  // Their cache policy controls refresh; an intraday lag test is inapplicable.
+  if (intervalMs != null && intervalMs >= DAY_MS) return false;
+
   const latestTime = getPricePointTimestamp(latest);
   if (!Number.isFinite(latestTime)) return false;
   const age = now - latestTime;
-  if (age <= MAX_SAME_SESSION_HISTORY_LAG_MS) return false;
+  // Completed bars are timestamped at their opening time. Before the next
+  // completed bar is delivered, the newest bar may be almost two intervals
+  // plus the feed delay old. Keep the existing tolerance for finer bars.
+  const allowedLag = Math.max(MAX_SAME_SESSION_HISTORY_LAG_MS,
+    intervalMs != null ? 2 * intervalMs + DELAYED_HISTORY_ALLOWANCE_MS : 0);
+  if (age <= allowedLag) return false;
   const exchange = options.exchange || "NASDAQ";
   if (
     resolveExchangeTimeZone(exchange)

package/src/utils/reported-money.test.ts

@@ -0,0 +1,25 @@
+import { expect, test } from "bun:test";
+import { formatPerShareNumber, formatReportedMoney } from "./reported-money";
+
+test("reported per-share values retain small profit/loss signs and explicit monetary units", () => {
+  const values = [0.004125, -0.004125, 0.0001234, -0.0001234, 0.00000254, -0.00000254, Number.MIN_VALUE];
+  for (const value of values) {
+    const amount = formatPerShareNumber(value);
+    expect(Math.sign(Number(amount))).toBe(Math.sign(value));
+    expect(Number(amount)).toBe(value);
+    expect(amount.length).toBeLessThanOrEqual(11);
+    for (const currency of [undefined, "GBp", "GBX", "ILA", "ZAc"]) {
+      expect(formatReportedMoney(value, currency, true)).toBe(`${amount} ${currency ?? "(ccy?)"}`);
+    }
+  }
+  expect(formatReportedMoney(0.004125, "USD", true)).toBe("$0.004125");
+  expect(formatReportedMoney(-0.004125, "CNY", true)).toBe("-CN¥0.004125");
+  expect(formatReportedMoney(-0.00000254, "USD", true)).toBe("-2.54e-6 USD");
+  expect(formatReportedMoney(-0, "USD", true)).toBe("$0.00");
+  expect(formatReportedMoney(2.5, "JPY", true)).toBe("¥2.50");
+  expect(formatReportedMoney(1_000_000, "USD")).toBe("1M USD");
+  for (const value of [undefined, Number.NaN, Infinity, -Infinity]) {
+    expect(formatPerShareNumber(value)).toBe("—");
+    expect(formatReportedMoney(value, "USD", true)).toBe("—");
+  }
+});

package/src/utils/reported-money.ts

@@ -0,0 +1,31 @@
+import { resolveCurrencyUnit } from "./currency-units";
+import { formatCompact, formatCurrency, formatNumber } from "./format";
+
+function perShareDecimals(value: number): number {
+  const magnitude = Math.abs(value);
+  return magnitude > 0 && magnitude < 1 ? Math.max(2, 3 - Math.floor(Math.log10(magnitude))) : 2;
+}
+
+function usesScientificNotation(value: number): boolean {
+  return value !== 0 && Math.abs(value) < 0.0001;
+}
+
+/** Preserve small profits and losses without widening ordinary EPS cells. */
+export function formatPerShareNumber(value: number | undefined): string {
+  if (value == null || !Number.isFinite(value)) return "—";
+  if (usesScientificNotation(value)) return value.toExponential(3).replace(/\.?0+e/, "e");
+  return formatNumber(value === 0 ? 0 : value, perShareDecimals(value)).replace(/(\.\d{2}.*?)0+$/, "$1");
+}
+
+/** Keep reported monetary amounts in their own units, independently of a quote. */
+export function formatReportedMoney(value: number | undefined, currency?: string, perShare = false): string {
+  if (value == null || !Number.isFinite(value)) return "—";
+  const amount = perShare ? formatPerShareNumber(value) : formatCompact(value);
+  const unit = currency?.trim();
+  if (!unit) return `${amount} (ccy?)`;
+  // Intl uppercases currency codes: GBp must not become GBP without scaling.
+  if (perShare && !usesScientificNotation(value) && /^[a-z]{3}$/i.test(unit) && resolveCurrencyUnit(unit).divisor === 1) {
+    return formatCurrency(value === 0 ? 0 : value, unit, perShareDecimals(value));
+  }
+  return `${amount} ${unit}`;
+}

package/src/utils/screenshot-watermark.ts

@@ -0,0 +1,27 @@
+/// <reference lib="dom" />
+
+/**
+ * Screenshot branding for the DOM renderers.
+ *
+ * Chart bitmaps are opaque, so the wordmark cannot literally sit behind the
+ * plot. Instead every chart mounts a faint, always-hidden watermark layer and
+ * this attribute on `<html>` reveals all of them at once. Flipping an
+ * attribute is synchronous, which lets the pane capture paint the watermark
+ * without a React render, and lets the OS screenshot detector toggle it
+ * without touching component state.
+ */
+export const SCREENSHOT_WATERMARK_ATTRIBUTE = "data-gloom-screenshot";
+
+export const CHART_WATERMARK_ROLE = "chart-watermark";
+
+export function isScreenshotWatermarkVisible(): boolean {
+  if (typeof document === "undefined") return false;
+  return document.documentElement.getAttribute(SCREENSHOT_WATERMARK_ATTRIBUTE) === "true";
+}
+
+export function setScreenshotWatermarkVisible(visible: boolean): void {
+  if (typeof document === "undefined") return;
+  const root = document.documentElement;
+  if (visible) root.setAttribute(SCREENSHOT_WATERMARK_ATTRIBUTE, "true");
+  else root.removeAttribute(SCREENSHOT_WATERMARK_ATTRIBUTE);
+}

package/src/utils/sec-eps-basis.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, test } from "bun:test";
+import { createSecEpsBasisResolver } from "./sec-eps-basis";
+
+const oldAccn = "0000320193-19-000119";
+const newAccn = "0000320193-20-000096";
+const period = { start: "2017-10-01", end: "2018-09-29", form: "10-K" };
+const before = { ...period, accn: oldAccn, filed: "2019-10-31", val: 11.91 };
+const after = { ...period, accn: newAccn, filed: "2020-10-30", val: 2.98 };
+const split = { end: "2020-08-28", val: 4, accn: newAccn, filed: "2020-10-30", form: "10-K" };
+const payload = (eps = [before, after], splitRows = [split], incomes = eps.map((row) => ({ ...row, val: 59_531_000_000 }))) => ({
+  facts: { "us-gaap": {
+    EarningsPerShareDiluted: { units: { "USD/shares": eps } },
+    StockholdersEquityNoteStockSplitConversionRatio1: { units: { pure: splitRows } },
+    NetIncomeLoss: { units: { USD: incomes } },
+    WeightedAverageNumberOfDilutedSharesOutstanding: { units: { shares: eps.map((row) => ({ ...row, val: row.val === 2.98 ? 20_000_435_000 : 5_000_109_000 })) } },
+  } },
+});
+
+describe("SEC EPS share-basis evidence", () => {
+  test("uses an exact split and rounded comparative EPS with unchanged income", () => {
+    const resolve = createSecEpsBasisResolver(payload());
+    const older = { ...before, start: "2016-09-25", end: "2017-09-30", val: 9.21 };
+    expect(resolve(older)).toMatchObject({ value: 2.3025, availableAt: "2020-10-30", basis: {
+      status: "split-adjusted", originalValue: 9.21, originalFiled: "2019-10-31", factor: 4,
+      evidence: [{ date: "2020-08-28", ratio: 4, accessionNumber: newAccn, beforeEps: 11.91, afterEps: 2.98 }],
+    } });
+    expect(resolve(after)).toMatchObject({ value: 2.98, basis: { factor: 1, originalValue: 2.98 } });
+  });
+
+  test("links an earlier accession only with matching comparative EPS and shares", () => {
+    const earlier = { ...before, accn: "0000320193-18-000145", filed: "2018-11-05" };
+    expect(createSecEpsBasisResolver(payload([earlier, before, after]))(earlier)).toMatchObject({ value: 2.9775, basis: { factor: 4 } });
+    // This accession still has a direct same-period split witness, so use a
+    // different old period to test the repeat-only link rather than that edge.
+    const repeated = { ...before, start: "2016-09-25", end: "2017-09-30", val: 9.21 };
+    const oldRepeat = { ...repeated, accn: earlier.accn, filed: earlier.filed };
+    const fixture = payload([oldRepeat, repeated, before, after]);
+    expect(createSecEpsBasisResolver(fixture)(oldRepeat).basis?.factor).toBe(4);
+    fixture.facts["us-gaap"].WeightedAverageNumberOfDilutedSharesOutstanding.units.shares[0]!.val += 1;
+    expect(createSecEpsBasisResolver(fixture)(oldRepeat)).toMatchObject({ basis: { status: "unresolved" } });
+    expect(createSecEpsBasisResolver(fixture)(oldRepeat).value).toBeUndefined();
+  });
+
+  test("does not double-adjust an already restated pre-effective filing", () => {
+    const earlyAdjusted = { ...after, accn: "0000320193-20-000062", filed: "2020-07-31" };
+    const resolve = createSecEpsBasisResolver(payload([before, earlyAdjusted, after]));
+    expect(resolve(earlyAdjusted)).toMatchObject({ value: 2.98, availableAt: "2020-10-30", basis: { factor: 1 } });
+  });
+
+  test("composes two disclosed, independently corroborated split factors", () => {
+    const a = { ...before, start: "2010-09-26", end: "2011-09-24", accn: "0000320193-12-000001", filed: "2012-10-31", val: 28 };
+    const b = { ...a, accn: "0000320193-14-000001", filed: "2014-10-31", val: 4 };
+    const c = { ...a, accn: newAccn, filed: "2020-10-30", val: 1 };
+    const one = { ...split, end: "2014-06-06", val: 7, accn: b.accn, filed: b.filed };
+    const resolve = createSecEpsBasisResolver(payload([a, b, c], [one, split]));
+    expect(resolve({ ...a, end: "2010-09-25", val: 14 })).toMatchObject({ value: .5, basis: { factor: 28 } });
+    expect(resolve(b)).toMatchObject({ value: 1, basis: { factor: 4 } });
+  });
+
+  test("supports a reverse split without confusing it with earnings growth", () => {
+    const pre = { ...before, val: 2 };
+    const post = { ...after, val: 10 };
+    expect(createSecEpsBasisResolver(payload([pre, post], [{ ...split, val: .2 }]))(pre)).toMatchObject({ value: 10, basis: { factor: .2 } });
+  });
+
+  test("never infers a split from EPS changes, price changes, or filing chronology", () => {
+    expect(createSecEpsBasisResolver(payload([before, after], []))(before)).toEqual({ value: 11.91, availableAt: before.filed });
+    const unknown = { ...before, accn: "0000320193-17-000001", filed: "2017-10-31" };
+    expect(createSecEpsBasisResolver(payload())(unknown).value).toBeUndefined();
+    const restatement = payload();
+    restatement.facts["us-gaap"].NetIncomeLoss.units.USD[1]!.val += 1;
+    expect(createSecEpsBasisResolver(restatement)(before).value).toBeUndefined();
+    expect(createSecEpsBasisResolver(payload([before, { ...after, val: 3.5 }]))(before).value).toBeUndefined();
+  });
+
+  test("rejects conflicting, missing, zero and invalid-date evidence", () => {
+    expect(createSecEpsBasisResolver(payload([before, after], [split, { ...split, val: 5 }]))(before).value).toBeUndefined();
+    expect(createSecEpsBasisResolver(payload([{ ...before, val: 0 }, { ...after, val: 0 }]))(before).value).toBeUndefined();
+    expect(() => createSecEpsBasisResolver(payload([before, after], [{ ...split, end: "2020-99-99" }]))).not.toThrow();
+    expect(createSecEpsBasisResolver(payload())({ ...before, filed: undefined }).value).toBeUndefined();
+  });
+});

package/src/utils/sec-eps-basis.ts

@@ -0,0 +1,152 @@
+/** Keep this pure SEC projection rule synchronized with the cloud backend. */
+export interface SecEpsSplitEvidence {
+  date: string;
+  ratio: number;
+  accessionNumber: string;
+  filed: string;
+  comparativePeriodEnd?: string;
+  beforeAccessionNumber?: string;
+  beforeEps?: number;
+  afterEps?: number;
+}
+
+export interface SecEpsBasis {
+  status: "split-adjusted" | "unresolved";
+  source: "sec";
+  originalValue: number;
+  originalFiled?: string;
+  basisDate: string;
+  factor?: number;
+  evidence: SecEpsSplitEvidence[];
+}
+
+type Fact = { start?: string; end?: string; val?: number; accn?: string; filed?: string; form?: string };
+type Row = Fact & { start: string; end: string; val: number; accn: string; filed: string };
+type Edge = { node: string; factor: number; evidence?: SecEpsSplitEvidence };
+const date = (value: unknown): value is string => typeof value === "string" && /^\d{4}-\d{2}-\d{2}$/.test(value)
+  && Number.isFinite(Date.parse(`${value}T00:00:00Z`)) && new Date(`${value}T00:00:00Z`).toISOString().slice(0, 10) === value;
+const record = (value: unknown): Record<string, unknown> => value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+
+function entries(payload: unknown, tag: string, unit: string): Fact[] {
+  const values = record(record(record(record(record(payload).facts)["us-gaap"])[tag]).units)[unit];
+  return Array.isArray(values) ? values.map(record).filter((row) => typeof row.val === "number" && Number.isFinite(row.val)
+    && date(row.end) && date(row.filed) && /^(10-K|10-Q)(\/A)?$/.test(String(row.form))
+    && /^\d{10}-\d{2}-\d{6}$/.test(String(row.accn))) as Fact[] : [];
+}
+
+function uniqueObservations(rows: Fact[]): Map<string, Row> {
+  const result = new Map<string, Row>();
+  const ambiguous = new Set<string>();
+  for (const row of rows) {
+    if (!date(row.start) || !row.end || row.start > row.end || row.filed! < row.end) continue;
+    const key = `${row.accn}:${row.start}:${row.end}`;
+    if (result.has(key) && result.get(key)!.val !== row.val) ambiguous.add(key);
+    result.set(key, row as Row);
+  }
+  for (const key of ambiguous) result.delete(key);
+  return result;
+}
+
+/**
+ * Share bases belong to source accessions, not filing dates. A split edge needs
+ * an explicit SEC split fact and unchanged same-period income with inverse EPS
+ * restatement. Repeated EPS AND diluted shares connect otherwise equal bases.
+ * No price jump, ticker exception, or chronological assumption establishes one.
+ */
+export function createSecEpsBasisResolver(payload: unknown): (fact: Fact) => { value?: number; basis?: SecEpsBasis; availableAt?: string } {
+  const splits = entries(payload, "StockholdersEquityNoteStockSplitConversionRatio1", "pure")
+    .filter((row) => row.val! > 0 && row.val !== 1)
+    .sort((a, b) => a.filed!.localeCompare(b.filed!));
+  if (splits.length === 0) return (fact) => ({ value: fact.val, availableAt: fact.filed });
+  const eventRows = new Map<string, Fact>();
+  const conflicts = new Set<string>();
+  for (const split of splits) {
+    if (eventRows.has(split.end!) && eventRows.get(split.end!)!.val !== split.val) conflicts.add(split.end!);
+    if (!eventRows.has(split.end!)) eventRows.set(split.end!, split);
+  }
+  const latest = [...eventRows.values()].sort((a, b) => a.end!.localeCompare(b.end!)).at(-1)!;
+  const eps = uniqueObservations(entries(payload, "EarningsPerShareDiluted", "USD/shares"));
+  const shares = uniqueObservations(entries(payload, "WeightedAverageNumberOfDilutedSharesOutstanding", "shares"));
+  const income = uniqueObservations(entries(payload, "NetIncomeLoss", "USD"));
+  const graph = new Map<string, Edge[]>();
+  const connect = (before: string, after: string, ratio: number, evidence?: SecEpsSplitEvidence) => {
+    graph.set(after, [...graph.get(after) ?? [], { node: before, factor: ratio, evidence }]);
+    graph.set(before, [...graph.get(before) ?? [], { node: after, factor: 1 / ratio, evidence }]);
+  };
+  const identical = new Map<string, Row>();
+  const periods = new Map<string, Row[]>();
+  for (const [key, row] of eps) {
+    const period = `${row.start}:${row.end}`;
+    periods.set(period, [...periods.get(period) ?? [], row]);
+    const denominator = shares.get(key)?.val;
+    if (!row.val || !denominator || denominator <= 0) continue;
+    const identity = `${period}:${row.val}:${denominator}`;
+    const prior = identical.get(identity);
+    if (prior && prior.accn !== row.accn) connect(prior.accn, row.accn, 1);
+    else identical.set(identity, row);
+  }
+  const proved = new Map<string, SecEpsSplitEvidence>();
+  for (const split of eventRows.values()) {
+    if (conflicts.has(split.end!)) continue;
+    for (const after of eps.values()) {
+      if (after.accn !== split.accn || after.filed !== split.filed || after.end >= split.end! || after.val === 0) continue;
+      for (const before of periods.get(`${after.start}:${after.end}`) ?? []) {
+        if (before.accn === after.accn || before.filed >= after.filed || before.val === after.val || before.val * after.val <= 0) continue;
+        const beforeIncome = income.get(`${before.accn}:${before.start}:${before.end}`)?.val;
+        const afterIncome = income.get(`${after.accn}:${after.start}:${after.end}`)?.val;
+        if (beforeIncome === undefined || beforeIncome === 0 || beforeIncome !== afterIncome) continue;
+        // EPS reports rounded to cents have overlapping rounding intervals.
+        // This accommodates 11.91 / 4 -> 2.98 without inventing precision.
+        const tolerance = .005 + .005 / split.val!;
+        if (Math.abs(before.val / split.val! - after.val) > tolerance + 1e-12
+          || Math.abs(before.val - after.val) <= tolerance * 2) continue;
+        const evidence: SecEpsSplitEvidence = {
+          date: split.end!, ratio: split.val!, accessionNumber: split.accn!, filed: split.filed!,
+          comparativePeriodEnd: before.end, beforeAccessionNumber: before.accn, beforeEps: before.val, afterEps: after.val,
+        };
+        connect(before.accn, after.accn, split.val!, evidence);
+        proved.set(split.end!, evidence);
+      }
+    }
+  }
+  const paths = new Map<string, { factor: number; evidence: SecEpsSplitEvidence[] }>();
+  const queue = [latest.accn!];
+  paths.set(latest.accn!, { factor: 1, evidence: [] });
+  let inconsistent = false;
+  for (let i = 0; i < queue.length; i++) {
+    const node = queue[i]!;
+    const path = paths.get(node)!;
+    for (const edge of graph.get(node) ?? []) {
+      const factor = path.factor * edge.factor;
+      if (!Number.isFinite(factor) || factor <= 0) { inconsistent = true; continue; }
+      const previous = paths.get(edge.node);
+      if (previous) {
+        if (Math.abs(previous.factor - factor) > Math.max(previous.factor, factor) * 1e-10) inconsistent = true;
+        continue;
+      }
+      paths.set(edge.node, { factor, evidence: [...path.evidence, ...edge.evidence ? [edge.evidence] : []] });
+      queue.push(edge.node);
+    }
+  }
+  return (fact) => {
+    if (!fact.end || fact.end >= latest.end!) return { value: fact.val, availableAt: fact.filed };
+    const path = fact.accn ? paths.get(fact.accn) : undefined;
+    const target = proved.get(latest.end!);
+    const evidence = [...new Map([...(path?.evidence ?? []), target ?? {
+      date: latest.end!, ratio: latest.val!, accessionNumber: latest.accn!, filed: latest.filed!,
+    }].map((item) => [item.date, item])).values()].sort((a, b) => a.date.localeCompare(b.date));
+    const basis: SecEpsBasis = {
+      status: "unresolved", source: "sec", originalValue: fact.val!, originalFiled: fact.filed,
+      basisDate: latest.end!, evidence,
+    };
+    // Any unproved intervening disclosure can represent an additional share basis.
+    const unproved = [...eventRows.values()].some((event) => event.end! > fact.end! && !proved.has(event.end!));
+    if (!path || !target || inconsistent || unproved || !date(fact.filed)) return { basis };
+    const value = fact.val! / path.factor;
+    if (!Number.isFinite(value)) return { basis };
+    return {
+      value, basis: { ...basis, status: "split-adjusted", factor: path.factor },
+      availableAt: [fact.filed, ...evidence.map((item) => item.filed)].sort().at(-1),
+    };
+  };
+}

package/src/utils/sec.test.ts

@@ -35,15 +35,17 @@ describe("isUsEquityTicker", () => {
     }))).toBe(true);
   });
 
-  test("accepts US-listed ADRs", () => {
-    expect(isUsEquityTicker(makeTicker({
-      assetCategory: "ADR",
-    }))).toBe(true);
-  });
-
-  test("rejects non-equity instruments", () => {
-    expect(isUsEquityTicker(makeTicker({
-      assetCategory: "OPT",
-    }))).toBe(false);
+  test("accepts catalogue common stocks and depositary receipts without admitting funds or foreign listings", () => {
+    for (const assetCategory of ["ADR", "Common Stock", "Depositary Receipt"]) {
+      expect(isUsEquityTicker(makeTicker({ assetCategory }))).toBe(true);
+      expect(isUsEquityTicker(makeTicker({ assetCategory, exchange: "LSE" }))).toBe(false);
+      expect(isUsEquityTicker(makeTicker({ assetCategory, currency: "CAD" }))).toBe(false);
+    }
+    for (const exchange of ["XNAS", "NGM", "NCM", "XNYS", "XASE"]) {
+      expect(isUsEquityTicker(makeTicker({ assetCategory: "Common Stock", exchange }))).toBe(true);
+    }
+    for (const assetCategory of ["OPT", "ETF", "Mutual Fund", "Preferred Stock"]) {
+      expect(isUsEquityTicker(makeTicker({ assetCategory }))).toBe(false);
+    }
   });
 });

package/src/utils/sec.ts

@@ -1,4 +1,5 @@
 import type { TickerRecord } from "../types/ticker";
+import { canonicalExchange } from "./exchanges";
 
 const US_EQUITY_EXCHANGES = new Set([
   "AMEX",
@@ -19,12 +20,12 @@ function normalize(value?: string): string {
 }
 
 function isUsExchange(value?: string): boolean {
-  return US_EQUITY_EXCHANGES.has(normalize(value));
+  return US_EQUITY_EXCHANGES.has(canonicalExchange(value));
 }
 
 function isEquityType(value?: string): boolean {
-  const normalized = normalize(value);
-  return normalized.length === 0 || normalized === "STK" || normalized === "EQUITY" || normalized === "ADR";
+  const normalized = normalize(value).replace(/[\s_-]/g, "");
+  return normalized.length === 0 || ["STK", "EQUITY", "ADR", "COMMONSTOCK", "DEPOSITARYRECEIPT"].includes(normalized);
 }
 
 export function isUsEquityTicker(ticker: TickerRecord | null | undefined): boolean {

package/src/utils/semver.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, test } from "bun:test";
+
+import { compareSemver, formatVersion } from "./semver";
+
+describe("compareSemver", () => {
+  test("orders by major, minor, patch and ignores a leading v", () => {
+    expect(compareSemver("v1.2.3", "1.2.3")).toBe(0);
+    expect(compareSemver("1.2.3", "1.10.0")).toBeLessThan(0);
+    expect(compareSemver("2.0", "1.99.99")).toBeGreaterThan(0);
+  });
+
+  test("a release outranks its own prerelease", () => {
+    expect(compareSemver("1.0.0-beta.2", "1.0.0")).toBeLessThan(0);
+    expect(compareSemver("1.0.0-beta.1", "1.0.0-beta.2")).toBeLessThan(0);
+  });
+
+  test("returns null rather than guessing when either side is not a version", () => {
+    // Plugins pin to tags like "main" or a commit; comparing those as versions
+    // would report an update forever or never.
+    expect(compareSemver("main", "1.0.0")).toBeNull();
+    expect(compareSemver(undefined, "1.0.0")).toBeNull();
+  });
+});
+
+describe("formatVersion", () => {
+  test("normalizes spelling and passes non-versions through", () => {
+    expect(formatVersion("v1.2")).toBe("1.2.0");
+    expect(formatVersion("main")).toBe("main");
+    expect(formatVersion("")).toBeNull();
+  });
+});