fix: bound sibling identity work per React commit

Author: y0u-0

.changeset/calm-cameras-count.md

@@ -0,0 +1,5 @@
+---
+"genie-react": patch
+---
+
+Reduce synchronous render-analysis overhead for wide component lists by reusing bounded sibling identity scans within each commit. Preserve key uniqueness, reorder handling, deadlines, and incomplete coverage reporting.

docs/runtime-overhead.md

@@ -0,0 +1,42 @@
+# Runtime instrumentation overhead
+
+Genie observes React commits synchronously. Active render analysis adds work to the app's main thread, even when no agent is querying it. Pausing a profile stops detailed analysis while keeping the hook and liveness bookkeeping installed. Profiling is not a zero-overhead measurement of an uninstrumented app.
+
+## Verified wide-list regression
+
+The instance identity collector previously recovered sibling position and key uniqueness by scanning the same sibling chain several times for every rendered component. An updating keyed list therefore incurred quadratic sibling reads. A deterministic regression fixture of 100 rows observed 29,900 sibling reads before the fix.
+
+Sibling positions and key counts are now indexed once per commit work budget. The index is discarded with that budget, so later reorders and duplicate keys are re-evaluated. Incomplete scans cannot prove key uniqueness. Existing operation limits, deadlines, Fiber limits, and conservative coverage reporting still apply; reports outside a commit continue to inspect live structure.
+
+## Reproduce in Chromium
+
+```sh
+pnpm install --frozen-lockfile
+pnpm exec playwright install chromium
+node scripts/benchmark-runtime-overhead.mjs > overhead.json
+```
+
+The script starts an isolated Vite fixture and closes its browser/server afterward. It uses the installed workspace React development build and the current Genie source. Five hundred keyed sibling components update synchronously, each producing one span. Every mode receives 20 warmup updates and 60 measured updates on each of three fresh pages, with mode order varied between rounds. The script verifies row count and rendered values and records raw samples, coverage omissions, collection mode, budget settings, and Chromium version.
+
+Modes are **disabled** (no Genie hook), **active** (Genie's hook and default render analysis), and **paused** (hook installed, detailed render collection paused). This isolates the commit instrumentation; it does not include connected hub traffic, plugin collectors, source transforms, or report queries. Durations cover synchronous React rendering and commit instrumentation, not paint or end-to-end input latency. Do not treat this synthetic workload as the unidentified reporter's app or as a production/native benchmark.
+
+A local run on September 5, 2026, using Chromium 149.0.7827.55 produced:
+
+| Mode | Before median / p95 | Fixed median / p95 |
+| --- | --- | --- |
+| Genie disabled | 1.8 / 2.3 ms | 1.8 / 2.1 ms |
+| Active analysis | 8.7 / 9.5 ms | 3.9 / 4.7 ms |
+| Paused analysis | 2.0 / 2.2 ms | 1.9 / 2.0 ms |
+
+Active median update time decreased about 55% in this fixture, while remaining above the uninstrumented baseline. Skipped Fiber analyses across each page's 80 updates decreased from 34,269 to 20,080. Both runs used the same default configuration. Before the fix, operation exhaustion raised the adaptive scale to 4 (a 1,000-Fiber allowance), yet only about 73 Fibers per commit could be analyzed. Afterward, scale stayed at 1 and 250 Fibers per commit were analyzed. The remaining omissions reflect that default 250-Fiber limit; these numbers measure bounded partial collection, not analysis of all 500 rows. This fix does not trade reduced evidence coverage for speed. Timing results vary by machine, browser, thermal state, and workload; the unit test enforces the linear sibling-read property rather than a flaky millisecond threshold.
+
+## Regression risks and evidence
+
+| Risk | Protected behavior | Validation |
+| --- | --- | --- |
+| Repeated sibling scans | All row positions and unique keys resolve with linear sibling reads | Deterministic 100-row test failed before fix and passes afterward |
+| Stale index across commits | Reorders change position, duplicate keys remove keyed identity, physical mount stays stable | Successive-budget reorder/key-change test |
+| Scan truncation | An unseen sibling cannot be assumed to have a different key | 2,001-row bound and exhausted-operation tests |
+| Deadline bypass on cache hit | Cached evidence does not bypass the shared time budget | Controlled monotonic-clock test |
+
+The reporter's exact environment remains unverified because no app, workload, or trace was supplied. This reproduction establishes a concrete Genie overhead defect and validates its improvement; it does not establish that all reported slowdowns share this cause.

packages/genie-react/src/collectors/react/instance-identity.test.ts

@@ -1,5 +1,6 @@
 import { type Fiber, getFiberId } from 'bippy'
 import { beforeEach, describe, expect, it } from 'vitest'
+import { createCommitWorkBudget } from './commit-budget'
 import {
   beginInstanceObservation,
   clearInstanceIdentityForTests,
@@ -262,3 +263,96 @@ describe('React component instance identity', () => {
     expect(last?.mountGenerationEvidence).toBe('unknown')
   })
 })
+
+describe('commit-scoped sibling identity work', () => {
+  const work = () => createCommitWorkBudget({ operationLimit: 1_000_000, now: () => 0 })
+
+  it('identifies a wide keyed list with linear app-owned sibling reads', () => {
+    const parent = component('Rows')
+    const rows = Array.from({ length: 100 }, (_, index) => component('Row', String(index)))
+    attach(parent, rows)
+    let siblingReads = 0
+    rows.forEach((row, index) => {
+      Object.defineProperty(row, 'sibling', {
+        get() {
+          siblingReads += 1
+          return rows[index + 1] ?? null
+        },
+      })
+    })
+    const budget = work()
+
+    rows.forEach((row, index) => {
+      expect(noteInstanceRender(row, 'mount', 1, 1, budget)).toMatchObject({
+        siblingIndex: index,
+        key: String(index),
+        logicalIdentityEvidence: 'keyed',
+      })
+    })
+
+    // Recovering every position and key must not re-read the list for every row.
+    expect(siblingReads).toBeLessThanOrEqual(rows.length * 2)
+  })
+
+  it('recomputes positions and key uniqueness after the next commit reorders siblings', () => {
+    const parent = component('Rows')
+    const a = component('Row', 'a')
+    const b = component('Row', 'b')
+    attach(parent, [a, b])
+    const mounted = noteInstanceRender(a, 'mount', 1, 1, work())
+
+    attach(parent, [b, a])
+    const reordered = noteInstanceRender(a, 'update', 2, 2, work())
+    expect(reordered).toMatchObject({ siblingIndex: 1, logicalIdentityEvidence: 'keyed' })
+    expect(reordered.mountId).toBe(mounted.mountId)
+    expect(reordered.logicalPath).toBe(mounted.logicalPath)
+
+    ;(b as { key: string }).key = 'a'
+    const duplicated = noteInstanceRender(a, 'update', 3, 3, work())
+    expect(duplicated).toMatchObject({ siblingIndex: 1, logicalIdentityEvidence: 'positional' })
+    expect(duplicated.logicalPath).toContain('Row[index=1]')
+  })
+
+  it('does not let a cached sibling scan bypass an expired commit deadline', () => {
+    const parent = component('Rows')
+    const a = component('Row', 'a')
+    const b = component('Row', 'b')
+    attach(parent, [a, b])
+    let now = 0
+    const budget = createCommitWorkBudget({ now: () => now, timeLimitMs: 1 })
+    expect(noteInstanceRender(a, 'mount', 1, 1, budget).logicalIdentityEvidence).toBe('keyed')
+
+    now = 1
+    expect(noteInstanceRender(b, 'mount', 1, 1, budget)).toMatchObject({
+      siblingIndex: null,
+      logicalIdentityEvidence: 'unknown',
+    })
+  })
+
+  it('does not infer key uniqueness when the shared operation budget interrupts the scan', () => {
+    const parent = component('Rows')
+    const rows = Array.from({ length: 100 }, (_, index) => component('Row', String(index)))
+    attach(parent, rows)
+    const budget = createCommitWorkBudget({ now: () => 0, operationLimit: 10 })
+
+    expect(
+      noteInstanceRender(rows[0] as Fiber, 'mount', 1, 1, budget).logicalIdentityEvidence,
+    ).toBe('unknown')
+    expect(
+      noteInstanceRender(rows[1] as Fiber, 'mount', 1, 1, budget).logicalIdentityEvidence,
+    ).toBe('unknown')
+  })
+
+  it('does not infer key uniqueness from a bounded prefix of a larger sibling list', () => {
+    const parent = component('Rows')
+    const rows = Array.from({ length: 2_001 }, (_, index) => component('Row', String(index)))
+    attach(parent, rows)
+    const budget = work()
+
+    const first = noteInstanceRender(rows[0] as Fiber, 'mount', 1, 1, budget)
+    const last = noteInstanceRender(rows[2_000] as Fiber, 'mount', 1, 1, budget)
+
+    expect(first).toMatchObject({ siblingIndex: 0, logicalIdentityEvidence: 'positional' })
+    expect(last).toMatchObject({ siblingIndex: null, logicalIdentityEvidence: 'unknown' })
+  })
+})

packages/genie-react/src/collectors/react/instance-identity.ts

@@ -416,9 +416,49 @@ function nearestKeyedComposite(fiber: Fiber | null, budget?: CommitWorkBudget):
   return null
 }
 
+interface SiblingIdentityScan {
+  indices: Map<Fiber, number>
+  keyCounts: Map<string, number>
+  complete: boolean
+}
+
+// A work budget belongs to one synchronous commit; sibling order can change on the next one.
+const siblingScans = new WeakMap<CommitWorkBudget, WeakMap<Fiber, SiblingIdentityScan>>()
+
+function commitSiblingScan(first: Fiber, budget: CommitWorkBudget): SiblingIdentityScan {
+  let scans = siblingScans.get(budget)
+  if (!scans) {
+    scans = new WeakMap()
+    siblingScans.set(budget, scans)
+  }
+  const cached = scans.get(first)
+  if (cached) return cached
+
+  const scan: SiblingIdentityScan = { indices: new Map(), keyCounts: new Map(), complete: false }
+  let current: Fiber | null = first
+  let index = 0
+  while (current && index < SIBLING_SCAN_LIMIT) {
+    if (!consumeCommitWork(budget, 'instance-siblings')) break
+    scan.indices.set(current, index)
+    if (current.alternate) scan.indices.set(current.alternate, index)
+    if (typeof current.key === 'string') {
+      scan.keyCounts.set(current.key, (scan.keyCounts.get(current.key) ?? 0) + 1)
+    }
+    current = current.sibling
+    index += 1
+  }
+  scan.complete = current === null
+  scans.set(first, scan)
+  return scan
+}
+
 function indexAmongSiblings(fiber: Fiber, budget?: CommitWorkBudget): number | null {
   const first = fiber.return?.child
   if (!first) return fiber.return ? null : 0
+  if (budget) {
+    if (!consumeCommitWork(budget, 'instance-siblings')) return null
+    return commitSiblingScan(first, budget).indices.get(fiber) ?? null
+  }
   let current: Fiber | null = first
   let index = 0
   while (current && index < SIBLING_SCAN_LIMIT) {
@@ -434,6 +474,11 @@ function indexAmongSiblings(fiber: Fiber, budget?: CommitWorkBudget): number | n
 function isUniqueSiblingKey(fiber: Fiber, key: string, budget?: CommitWorkBudget): boolean {
   const first = fiber.return?.child
   if (!first) return false
+  if (budget) {
+    if (!consumeCommitWork(budget, 'instance-siblings')) return false
+    const scan = commitSiblingScan(first, budget)
+    return scan.complete && scan.keyCounts.get(key) === 1
+  }
   let current: Fiber | null = first
   let matches = 0
   let scanned = 0

scripts/benchmark-runtime-overhead.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { chromium } from 'playwright'
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const runtimeRequire = createRequire(join(root, 'packages/genie-react/package.json'))
+const demoRequire = createRequire(join(root, 'apps/vite-demo/package.json'))
+const { createServer } = await import(runtimeRequire.resolve('vite'))
+const fixture = await mkdtemp(join(root, '.runtime-benchmark-'))
+let server
+let browser
+try {
+  await writeFile(
+    join(fixture, 'index.html'),
+    '<div id="root"></div><script type="module" src="/main.js"></script>',
+  )
+  await writeFile(
+    join(fixture, 'main.js'),
+    `
+const mode = new URLSearchParams(location.search).get('mode');
+let tracker;
+if (mode !== 'disabled') {
+  await import('/@fs/${root}/packages/genie-react/src/collectors/react/hook.ts');
+  tracker = await import('/@fs/${root}/packages/genie-react/src/collectors/react/render-tracker.ts');
+}
+const React = await import('react');
+const { createRoot } = await import('react-dom/client');
+const { flushSync } = await import('react-dom');
+const count = 500;
+function Row({ value, index }) { return React.createElement('span', null, index + ':' + value); }
+function App({ value }) { return React.createElement('div', null, Array.from({ length: count }, (_, index) => React.createElement(Row, { key: index, index, value }))); }
+const root = createRoot(document.getElementById('root'));
+let value = 0;
+const update = () => flushSync(() => root.render(React.createElement(App, { value: ++value })));
+update();
+if (mode === 'paused') tracker.stopRenderTracking();
+window.runBenchmark = () => {
+  tracker?.clearRenders();
+  for (let i = 0; i < 20; i++) update();
+  const samples = [];
+  for (let i = 0; i < 60; i++) { const start = performance.now(); update(); samples.push(performance.now() - start); }
+  return { samples, text: document.querySelector('span').textContent, expectedText: '0:' + value, rows: document.querySelectorAll('span').length, count, budget: tracker?.getRenderObservationConfig(), skippedFibers: tracker?.getSkippedCommitFiberCount(), commits: tracker?.getCommitCount() };
+};
+`,
+  )
+  server = await createServer({
+    configFile: false,
+    root: fixture,
+    logLevel: 'error',
+    resolve: {
+      alias: [
+        { find: /^react$/, replacement: runtimeRequire.resolve('react') },
+        { find: /^react-dom\/client$/, replacement: demoRequire.resolve('react-dom/client') },
+        { find: /^react-dom$/, replacement: demoRequire.resolve('react-dom') },
+      ],
+    },
+    server: { host: '127.0.0.1', port: 0, fs: { allow: [root] } },
+  })
+  await server.listen()
+  const address = server.httpServer.address()
+  if (!address || typeof address === 'string') throw new Error('Missing Vite port')
+  browser = await chromium.launch({ headless: true })
+  const results = []
+  // Alternate order to reduce one-directional warmup/thermal bias. Each run has a fresh document.
+  for (const modes of [
+    ['disabled', 'active', 'paused'],
+    ['paused', 'active', 'disabled'],
+    ['active', 'disabled', 'paused'],
+  ]) {
+    for (const mode of modes) {
+      const page = await browser.newPage()
+      const pageErrors = []
+      page.on('pageerror', (error) => pageErrors.push(error))
+      await page.goto(`http://127.0.0.1:${address.port}/?mode=${mode}`)
+      await page.waitForFunction(() => typeof window.runBenchmark === 'function')
+      const result = await page.evaluate(() => window.runBenchmark())
+      if (pageErrors.length > 0) throw pageErrors[0]
+      if (result.text !== result.expectedText || result.rows !== result.count)
+        throw new Error('Fixture rendered incorrectly')
+      results.push({ mode, ...result })
+      await page.close()
+    }
+  }
+  const percentile = (values, fraction) =>
+    [...values].sort((a, b) => a - b)[Math.ceil(values.length * fraction) - 1]
+  const summary = ['disabled', 'active', 'paused'].map((mode) => {
+    const runs = results.filter((result) => result.mode === mode)
+    const samples = runs.flatMap((run) => run.samples)
+    return {
+      mode,
+      medianMs: percentile(samples, 0.5),
+      p95Ms: percentile(samples, 0.95),
+      runs: runs.map(({ samples, ...run }) => ({ ...run, medianMs: percentile(samples, 0.5) })),
+    }
+  })
+  console.log(
+    JSON.stringify(
+      {
+        fixture:
+          'React development build, 500 keyed sibling rows; 20 warmup + 60 synchronous updates × 3 fresh documents per mode',
+        browser: browser.version(),
+        react: runtimeRequire('react/package.json').version,
+        platform: process.platform,
+        architecture: process.arch,
+        summary,
+        results,
+      },
+      null,
+      2,
+    ),
+  )
+} finally {
+  await browser?.close()
+  await server?.close()
+  await rm(fixture, { recursive: true, force: true })
+}