@buoy-gg/js-top 7.0.29 → 7.0.30

package/src/js-top/engine/__tests__/engine.test.ts

@@ -1,337 +0,0 @@
-/**
- * Unit tests for the js-top engine's pure accounting core.
- *
- * Same self-contained harness pattern as perf-monitor's __tests__: the repo
- * has no Jest, so run with `npx tsx <path>`; `__tests__` is excluded from
- * the publish build.
- */
-
-import {
-  bookBusyRange,
-  bookAttributedRange,
-  resetAggregator,
-  windowBusyMs,
-  windowAttributedMs,
-  busyHistory,
-} from "../aggregator";
-import {
-  buoyJsTopScheduleOrigin,
-  buoyJsTopBookExclusive,
-  buildRows,
-  debugGetOrigin,
-  originCount,
-  parseStack,
-  resetOrigins,
-  OTHER_KEY,
-} from "../originRegistry";
-import { buoyJsTopWrapTask, buoyJsTopRunAs, debugDepth } from "../frameStack";
-import { setNowForTests } from "../now";
-import { setActive } from "../state";
-import {
-  BUCKET_MS,
-  MAX_ORIGINS,
-  PROMOTE_MIN_CALLS,
-  WINDOW_BUCKETS,
-} from "../../types";
-
-// ----------------------------------------------------------------------------
-// Tiny harness
-// ----------------------------------------------------------------------------
-
-type TestFn = () => void | Promise<void>;
-interface TestCase {
-  name: string;
-  fn: TestFn;
-}
-
-const cases: TestCase[] = [];
-let currentSuite = "";
-
-function describe(name: string, body: () => void) {
-  const prev = currentSuite;
-  currentSuite = prev ? `${prev} › ${name}` : name;
-  body();
-  currentSuite = prev;
-}
-
-function it(name: string, fn: TestFn) {
-  cases.push({ name: `${currentSuite} › ${name}`, fn });
-}
-
-function expectEq(actual: unknown, expected: unknown, label = "") {
-  const a = JSON.stringify(actual);
-  const e = JSON.stringify(expected);
-  if (a !== e) {
-    throw new Error(`${label || "expectEq"}: expected ${e}, got ${a}`);
-  }
-}
-
-function expectClose(actual: number, expected: number, tol = 0.01, label = "") {
-  if (Math.abs(actual - expected) > tol) {
-    throw new Error(
-      `${label || "expectClose"}: expected ~${expected}, got ${actual}`,
-    );
-  }
-}
-
-function expectTrue(cond: boolean, label = "") {
-  if (!cond) throw new Error(`${label || "expectTrue"}: condition false`);
-}
-
-// ----------------------------------------------------------------------------
-// Controllable clock
-// ----------------------------------------------------------------------------
-
-let fakeNow = 0;
-function advance(ms: number) {
-  fakeNow += ms;
-}
-function resetAll(startAt = 1_000_000) {
-  fakeNow = startAt;
-  setNowForTests(() => fakeNow);
-  resetOrigins();
-  resetAggregator();
-  setActive(true);
-}
-
-// ----------------------------------------------------------------------------
-// Aggregator
-// ----------------------------------------------------------------------------
-
-describe("aggregator", () => {
-  it("distributes a span across buckets and caps each at BUCKET_MS", () => {
-    resetAll();
-    const t0 = fakeNow;
-    // A 1000ms fully-busy span covers 4 buckets of 250 each.
-    bookBusyRange(t0, t0 + 1000);
-    expectClose(windowBusyMs(t0 + 1000), 1000, 1, "busy sum");
-    // Booking the same span again must not exceed the per-bucket cap.
-    bookBusyRange(t0, t0 + 1000);
-    expectClose(windowBusyMs(t0 + 1000), 1000, 1, "capped busy sum");
-  });
-
-  it("windows slide: old buckets fall out after WINDOW_BUCKETS", () => {
-    resetAll();
-    const t0 = fakeNow;
-    bookBusyRange(t0, t0 + 100);
-    const later = t0 + (WINDOW_BUCKETS + 2) * BUCKET_MS;
-    expectClose(windowBusyMs(later), 0, 0.001, "expired window");
-  });
-
-  it("attributed range books exclusive ms proportionally", () => {
-    resetAll();
-    const t0 = fakeNow;
-    // 500ms span but only 100ms exclusive → 100 attributed total.
-    bookAttributedRange(t0, t0 + 500, 100);
-    expectClose(windowAttributedMs(t0 + 500), 100, 1, "attributed sum");
-  });
-
-  it("clamps pathological multi-minute spans to the history ring", () => {
-    resetAll();
-    const t0 = fakeNow;
-    bookBusyRange(t0 - 10 * 60 * 1000, t0);
-    // Booked at most one ring's worth; window sum is fully busy.
-    expectClose(
-      windowBusyMs(t0),
-      WINDOW_BUCKETS * BUCKET_MS,
-      BUCKET_MS,
-      "stall backfill",
-    );
-    expectTrue(busyHistory(t0).length > 0, "history present");
-  });
-});
-
-// ----------------------------------------------------------------------------
-// Origin registry
-// ----------------------------------------------------------------------------
-
-describe("originRegistry", () => {
-  it("cheap keys aggregate by api + fn name", () => {
-    resetAll();
-    function pollFeed() {}
-    const k1 = buoyJsTopScheduleOrigin("interval", pollFeed, fakeNow);
-    const k2 = buoyJsTopScheduleOrigin("interval", pollFeed, fakeNow);
-    expectEq(k1, k2, "same cheap key");
-    expectEq(k1, "interval|pollFeed", "key shape");
-    expectEq(debugGetOrigin(k1)?.scheduleCount, 2, "schedule count");
-  });
-
-  it("promotes after PROMOTE_MIN_CALLS schedules", () => {
-    resetAll();
-    function hot() {}
-    let key = "";
-    for (let i = 0; i < PROMOTE_MIN_CALLS + 1; i++) {
-      key = buoyJsTopScheduleOrigin("timeout", hot, fakeNow);
-      advance(10);
-    }
-    // Cheap origin is promoted; refined key may or may not resolve under
-    // tsx/node stack formats, but the cheap origin must be flagged.
-    const cheap = debugGetOrigin("timeout|hot");
-    expectTrue(cheap?.promoted === true, "promoted flag");
-    expectTrue(key.length > 0, "key resolves");
-  });
-
-  it("books exclusive time into calls/totals/max and the ring", () => {
-    resetAll();
-    function job() {}
-    const key = buoyJsTopScheduleOrigin("timeout", job, fakeNow);
-    buoyJsTopBookExclusive(key, 40, fakeNow, fakeNow + 50);
-    buoyJsTopBookExclusive(key, 10, fakeNow + 60, fakeNow + 70);
-    const o = debugGetOrigin(key);
-    expectEq(o?.calls, 2, "calls");
-    expectClose(o?.totalMs ?? 0, 50, 0.01, "totalMs");
-    expectClose(o?.maxMs ?? 0, 40, 0.01, "maxMs");
-    const rows = buildRows(fakeNow + 100, 1000, 10);
-    expectEq(rows[0]?.key, key, "row present");
-    expectClose(rows[0]?.windowMs ?? 0, 50, 1, "row windowMs");
-  });
-
-  it("evicts the coldest origin into the pinned other row at MAX_ORIGINS", () => {
-    resetAll();
-    // Create a cold origin with booked history, then flood the registry.
-    function coldFn() {}
-    const coldKey = buoyJsTopScheduleOrigin("timeout", coldFn, fakeNow);
-    buoyJsTopBookExclusive(coldKey, 5, fakeNow, fakeNow + 5);
-    advance(WINDOW_BUCKETS * BUCKET_MS + 1000); // cold falls out of window
-    for (let i = 0; i < MAX_ORIGINS + 10; i++) {
-      // Distinct names → distinct cheap keys.
-      const fn = { name: `filler_${i}` };
-      const k = buoyJsTopScheduleOrigin("timeout", fn, fakeNow);
-      buoyJsTopBookExclusive(k, 1, fakeNow, fakeNow + 1);
-      advance(2);
-    }
-    expectTrue(originCount() <= MAX_ORIGINS + 1, "registry capped (+other)");
-    expectTrue(debugGetOrigin(coldKey) === undefined, "cold evicted");
-    const other = debugGetOrigin(OTHER_KEY);
-    expectTrue((other?.totalMs ?? 0) >= 5, "other absorbed totals");
-  });
-
-  it("parses Hermes-style stacks and skips engine frames", () => {
-    const stack = [
-      "Error",
-      "    at buoyJsTopScheduleOrigin (address at bundle.js:10:5)",
-      "    at buoyJsTopSetTimeout (address at bundle.js:20:5)",
-      "    at startPolling (address at http://localhost:8081/index.bundle?platform=ios:120233:22)",
-      "    at anonymous (address at bundle.js:99:1)",
-    ].join("\n");
-    const { caller, frames } = parseStack(stack);
-    expectEq(caller, "startPolling", "caller");
-    expectTrue(frames.length >= 1, "frames kept");
-    expectEq(frames[0]?.line, 120233, "top frame line");
-  });
-});
-
-// ----------------------------------------------------------------------------
-// Frame stack — exclusive-time math
-// ----------------------------------------------------------------------------
-
-describe("frameStack", () => {
-  it("books exclusive time for nested wrapped calls (no double count)", () => {
-    resetAll();
-    // Parent runs 100ms total; child (invoked synchronously inside, as a
-    // bridge call-in would invoke wrapped rAF callbacks) consumes 60ms.
-    const child = buoyJsTopWrapTask(function childWork() {
-      advance(60);
-    }, "raf");
-    buoyJsTopRunAs("bridge", "JSTimers.callTimers", () => {
-      advance(30);
-      child();
-      advance(10);
-    });
-    const childO = debugGetOrigin("raf|childWork");
-    const parentO = debugGetOrigin("bridge|JSTimers.callTimers");
-    expectClose(childO?.totalMs ?? 0, 60, 0.01, "child exclusive");
-    expectClose(parentO?.totalMs ?? 0, 40, 0.01, "parent exclusive");
-    // Union attributed globally = 100, not 160.
-    expectClose(windowAttributedMs(fakeNow), 100, 2, "attributed union");
-    expectEq(debugDepth(), 0, "stack drained");
-  });
-
-  it("inactive engine wraps but books nothing; attribution starts on activation", () => {
-    resetAll();
-    setActive(false);
-    function pollFeedLoop() {
-      advance(30);
-    }
-    // Scheduled while off (the classic pre-open interval)…
-    const wrapped = buoyJsTopWrapTask(pollFeedLoop, "interval");
-    expectTrue(wrapped !== pollFeedLoop, "wrapper installed even while off");
-    wrapped();
-    expectTrue(
-      debugGetOrigin("interval|pollFeedLoop") === undefined,
-      "no booking while inactive",
-    );
-    // …attributes from the first fire after the engine turns on.
-    setActive(true);
-    wrapped();
-    expectClose(
-      debugGetOrigin("interval|pollFeedLoop")?.totalMs ?? 0,
-      30,
-      0.01,
-      "late-resolved attribution",
-    );
-  });
-
-  it("survives clear(): live wrappers re-register their origin", () => {
-    resetAll();
-    function tickerWork() {
-      advance(10);
-    }
-    const wrapped = buoyJsTopWrapTask(tickerWork, "interval");
-    wrapped();
-    resetOrigins(); // what clear() does
-    wrapped();
-    expectClose(
-      debugGetOrigin("interval|tickerWork")?.totalMs ?? 0,
-      10,
-      0.01,
-      "re-registered after clear",
-    );
-  });
-
-  it("propagates errors while still booking the frame", () => {
-    resetAll();
-    const boom = buoyJsTopWrapTask(function boomTask() {
-      advance(25);
-      throw new Error("boom");
-    }, "timeout");
-    let threw = false;
-    try {
-      boom();
-    } catch (e) {
-      threw = (e as Error).message === "boom";
-    }
-    expectTrue(threw, "error propagated");
-    expectClose(
-      debugGetOrigin("timeout|boomTask")?.totalMs ?? 0,
-      25,
-      0.01,
-      "booked despite throw",
-    );
-    expectEq(debugDepth(), 0, "stack drained after throw");
-  });
-});
-
-// ----------------------------------------------------------------------------
-// Runner
-// ----------------------------------------------------------------------------
-
-async function main() {
-  let failed = 0;
-  for (const c of cases) {
-    try {
-      await c.fn();
-      // eslint-disable-next-line no-console
-      console.log(`  ✓ ${c.name}`);
-    } catch (err) {
-      failed++;
-      // eslint-disable-next-line no-console
-      console.error(`  ✗ ${c.name}\n      ${(err as Error).message}`);
-    }
-  }
-  // eslint-disable-next-line no-console
-  console.log(`\n${cases.length - failed}/${cases.length} passed`);
-  if (failed > 0) process.exit(1);
-}
-
-void main();

package/src/js-top/engine/aggregator.ts

@@ -1,148 +0,0 @@
-/**
- * Global per-bucket accounting: the engine's clock is divided into 250ms
- * buckets (epochs). Each bucket tracks measured busy ms (from the probe) and
- * attributed ms (from wrapped tasks); `unattributed = busy − attributed` per
- * bucket is what keeps the table honest when work enters the thread through
- * a path we can't wrap (bridgeless events, React commits, async/await).
- *
- * Rings are epoch-stamped parallel arrays: a slot is only valid when its
- * stamp matches the epoch being read, so stale slots cost nothing to skip
- * and nothing to zero eagerly.
- */
-
-import { BUCKET_MS, HISTORY_BUCKETS, WINDOW_BUCKETS } from "../types";
-
-const busyMs = new Float64Array(HISTORY_BUCKETS);
-const attributedMs = new Float64Array(HISTORY_BUCKETS);
-const longtaskMs = new Float64Array(HISTORY_BUCKETS);
-const stamps = new Float64Array(HISTORY_BUCKETS).fill(-1);
-
-export function epochOf(t: number): number {
-  return Math.floor(t / BUCKET_MS);
-}
-
-function slotFor(epoch: number): number {
-  const i = epoch % HISTORY_BUCKETS;
-  if (stamps[i] !== epoch) {
-    stamps[i] = epoch;
-    busyMs[i] = 0;
-    attributedMs[i] = 0;
-    longtaskMs[i] = 0;
-  }
-  return i;
-}
-
-/**
- * Distribute a wall-clock span across the buckets it overlaps. Spans older
- * than the history ring are clamped — a pathological hours-long gap books at
- * most one ring's worth of buckets.
- */
-function distribute(
-  start: number,
-  end: number,
-  add: (slot: number, ms: number) => void,
-): void {
-  if (!(end > start)) return;
-  const clampedStart = Math.max(start, end - HISTORY_BUCKETS * BUCKET_MS);
-  let e = epochOf(clampedStart);
-  const lastEpoch = epochOf(end);
-  let cursor = clampedStart;
-  while (e <= lastEpoch) {
-    const bucketEnd = (e + 1) * BUCKET_MS;
-    const sliceEnd = Math.min(end, bucketEnd);
-    const ms = sliceEnd - cursor;
-    if (ms > 0) add(slotFor(e), ms);
-    cursor = sliceEnd;
-    e++;
-  }
-}
-
-/** Book probe-measured busy time over [start, end], capped per bucket. */
-export function bookBusyRange(start: number, end: number): void {
-  distribute(start, end, (i, ms) => {
-    busyMs[i] = Math.min(BUCKET_MS, busyMs[i] + ms);
-  });
-}
-
-/**
- * Book a task's exclusive ms, spread proportionally over its wall span.
- * (Exclusive time isn't contiguous when children interleave; proportional
- * spread is exact at 250ms-bucket granularity for all practical tasks.)
- */
-export function bookAttributedRange(
-  start: number,
-  end: number,
-  exclusiveMs: number,
-): void {
-  const span = end - start;
-  if (!(span > 0) || !(exclusiveMs > 0)) return;
-  const ratio = Math.min(1, exclusiveMs / span);
-  distribute(start, end, (i, ms) => {
-    attributedMs[i] = Math.min(BUCKET_MS, attributedMs[i] + ms * ratio);
-  });
-}
-
-/** Book a reported longtask span (for history display only). */
-export function bookLongtaskRange(start: number, end: number): void {
-  distribute(start, end, (i, ms) => {
-    longtaskMs[i] = Math.min(BUCKET_MS, longtaskMs[i] + ms);
-  });
-}
-
-function sumWindow(arr: Float64Array, nowT: number, buckets: number): number {
-  const current = epochOf(nowT);
-  let sum = 0;
-  for (let e = current - buckets + 1; e <= current; e++) {
-    const i = e % HISTORY_BUCKETS;
-    if (i >= 0 && stamps[i] === e) sum += arr[i];
-  }
-  return sum;
-}
-
-export function windowBusyMs(nowT: number): number {
-  return sumWindow(busyMs, nowT, WINDOW_BUCKETS);
-}
-
-export function windowAttributedMs(nowT: number): number {
-  return sumWindow(attributedMs, nowT, WINDOW_BUCKETS);
-}
-
-/**
- * Per-bucket UNATTRIBUTED ms (busy − attributed), oldest→newest over the
- * rolling window — the "system" row's activity trend for the detail view.
- */
-export function windowResidualBuckets(nowT: number): number[] {
-  const current = epochOf(nowT);
-  const out: number[] = [];
-  for (let e = current - WINDOW_BUCKETS + 1; e <= current; e++) {
-    const i = e % HISTORY_BUCKETS;
-    if (i >= 0 && stamps[i] === e) {
-      out.push(Math.max(0, Math.round((busyMs[i] - attributedMs[i]) * 10) / 10));
-    } else {
-      out.push(0);
-    }
-  }
-  return out;
-}
-
-/** Per-bucket busy%, oldest→newest, over the full 30s history ring. */
-export function busyHistory(nowT: number): number[] {
-  const current = epochOf(nowT);
-  const out: number[] = [];
-  for (let e = current - HISTORY_BUCKETS + 1; e <= current; e++) {
-    const i = e % HISTORY_BUCKETS;
-    if (i >= 0 && stamps[i] === e) {
-      out.push(Math.round((busyMs[i] / BUCKET_MS) * 100));
-    } else {
-      out.push(0);
-    }
-  }
-  // Trim the leading dead zone from before the engine started.
-  let firstLive = 0;
-  while (firstLive < out.length && out[firstLive] === 0) firstLive++;
-  return out.slice(Math.max(0, Math.min(firstLive, out.length - 1)));
-}
-
-export function resetAggregator(): void {
-  stamps.fill(-1);
-}

package/src/js-top/engine/busyProbe.ts

@@ -1,100 +0,0 @@
-/**
- * Busy probe — measures true JS-thread occupancy from timer-gap inflation.
- *
- * A 16ms heartbeat (created with the PRE-PATCH setInterval so the probe never
- * appears in its own table) can only fire when the thread yields; any gap
- * beyond the calibrated idle baseline is time the thread was busy. This is
- * the same physical signal as perf-monitor's stall-aware sampler, at higher
- * frequency: multi-second stalls simply arrive as one huge gap and are booked
- * as fully-busy buckets by bookBusyRange (the backfill falls out of the
- * range-distribution math; no separate synthetic-sample pass needed).
- *
- * Calibration: the nominal 16ms is never what a real device delivers at
- * idle. We track a rolling min gap (3 one-second slots) and subtract THAT,
- * otherwise idle devices read 10–20% phantom busy.
- *
- * AppState transitions also pause JS timers, so the controller flags them
- * via suppressNextGap() — same trick as PerfMonitorController; AppState
- * events arrive on the JS thread, so a genuine stall can never set the flag.
- */
-
-import { now } from "./now";
-import { getOriginals } from "./state";
-import { bookBusyRange } from "./aggregator";
-
-const PROBE_INTERVAL_MS = 16;
-/** Ignore gaps below this when calibrating (a busy tick isn't a baseline). */
-const CALIBRATION_MAX_GAP_MS = 100;
-const BASELINE_SLOTS = 3;
-const MIN_BASELINE_MS = 8;
-
-let handle: ReturnType<typeof setInterval> | null = null;
-let lastAt = 0;
-let suppressNext = false;
-
-let slotMins: number[] = [];
-let currentSlotMin = Infinity;
-let currentSlotStart = 0;
-let baseline = PROBE_INTERVAL_MS;
-
-function buoyJsTopProbeTick(): void {
-  const t = now();
-  const gap = lastAt > 0 ? t - lastAt : 0;
-  lastAt = t;
-  if (suppressNext) {
-    // Backgrounding/foregrounding paused timers — not a stall. Reset
-    // calibration too: refresh-rate or thermal state may have changed.
-    suppressNext = false;
-    currentSlotMin = Infinity;
-    currentSlotStart = t;
-    return;
-  }
-  if (gap <= 0) return;
-
-  if (gap < CALIBRATION_MAX_GAP_MS) {
-    if (gap < currentSlotMin) currentSlotMin = gap;
-    if (currentSlotStart === 0) currentSlotStart = t;
-    if (t - currentSlotStart >= 1000) {
-      slotMins.push(currentSlotMin);
-      if (slotMins.length > BASELINE_SLOTS) slotMins.shift();
-      baseline = Math.max(MIN_BASELINE_MS, Math.min(...slotMins));
-      currentSlotMin = Infinity;
-      currentSlotStart = t;
-    }
-  }
-
-  const busyExcess = gap - baseline;
-  if (busyExcess > 1) {
-    // The block ended when this tick finally fired — position it at the tail.
-    bookBusyRange(t - busyExcess, t);
-  }
-}
-
-export function startBusyProbe(): void {
-  if (handle != null) return;
-  const originals = getOriginals();
-  lastAt = now();
-  suppressNext = false;
-  slotMins = [];
-  currentSlotMin = Infinity;
-  currentSlotStart = 0;
-  baseline = PROBE_INTERVAL_MS;
-  handle = originals.setInterval(buoyJsTopProbeTick, PROBE_INTERVAL_MS);
-}
-
-export function stopBusyProbe(): void {
-  if (handle != null) {
-    getOriginals().clearInterval(handle);
-    handle = null;
-  }
-  lastAt = 0;
-}
-
-export function suppressNextGap(): void {
-  suppressNext = true;
-}
-
-/** Test-only. */
-export function debugBaseline(): number {
-  return baseline;
-}