@aztec/end-to-end 0.0.1-commit.b655e406 → 0.0.1-commit.b8a057fa

package/src/fixtures/e2e_prover_test.ts

@@ -1,43 +1,29 @@
-import type { InitialAccountData } from '@aztec/accounts/testing';
-import { type Archiver, createArchiver } from '@aztec/archiver';
+import { type InitialAccountData, generateSchnorrAccounts } from '@aztec/accounts/testing';
+import { AztecNodeService, createAztecNodeService } from '@aztec/aztec-node';
 import { AztecAddress, EthAddress } from '@aztec/aztec.js/addresses';
-import { type Logger, createLogger } from '@aztec/aztec.js/log';
+import { createLogger } from '@aztec/aztec.js/log';
 import type { AztecNode } from '@aztec/aztec.js/node';
 import { CheatCodes } from '@aztec/aztec/testing';
-import {
-  BBCircuitVerifier,
-  type ClientProtocolCircuitVerifier,
-  QueuedIVCVerifier,
-  TestCircuitVerifier,
-} from '@aztec/bb-prover';
-import { createBlobSinkClient } from '@aztec/blob-sink/client';
-import type { BlobSinkServer } from '@aztec/blob-sink/server';
-import type { DeployL1ContractsReturnType } from '@aztec/ethereum';
+import type { ClientProtocolCircuitVerifier } from '@aztec/bb-prover';
+import { BackendType, Barretenberg } from '@aztec/bb.js';
+import type { DeployAztecL1ContractsReturnType } from '@aztec/ethereum/deploy-aztec-l1-contracts';
 import { Buffer32 } from '@aztec/foundation/buffer';
 import { SecretValue } from '@aztec/foundation/config';
 import { FeeAssetHandlerAbi } from '@aztec/l1-artifacts';
 import { TokenContract } from '@aztec/noir-contracts.js/Token';
-import { type ProverNode, type ProverNodeConfig, createProverNode } from '@aztec/prover-node';
+import type { ContractInstanceWithAddress } from '@aztec/stdlib/contract';
 import type { AztecNodeAdmin } from '@aztec/stdlib/interfaces/client';
-import { TestWallet } from '@aztec/test-wallet/server';
 import { getGenesisValues } from '@aztec/world-state/testing';
 
 import { type Hex, getContract } from 'viem';
 import { privateKeyToAddress } from 'viem/accounts';
 
 import { TokenSimulator } from '../simulators/token_simulator.js';
+import { SingleNodeTestContext, type SingleNodeTestOpts } from '../single-node/single_node_test_context.js';
+import { TestWallet } from '../test-wallet/test_wallet.js';
 import { getACVMConfig } from './get_acvm_config.js';
 import { getBBConfig } from './get_bb_config.js';
-import {
-  type ISnapshotManager,
-  type SubsystemsContext,
-  createSnapshotManager,
-  deployAccounts,
-  publicDeployAccounts,
-} from './snapshot_manager.js';
-import { getPrivateKeyFromIndex, getSponsoredFPCAddress, setupPXEAndGetWallet } from './utils.js';
-
-const { E2E_DATA_PATH: dataPath } = process.env;
+import { getPrivateKeyFromIndex, getSponsoredFPCAddress, setup, setupPXEAndGetWallet } from './setup.js';
 
 type ProvenSetup = {
   wallet: TestWallet;
@@ -49,127 +35,117 @@ type ProvenSetup = {
  * However, we then setup a second PXE with a full prover instance.
  * We configure this instance with all of the accounts and contracts.
  * We then prove and verify transactions created via this full prover PXE.
+ *
+ * The real-prover sub-base of the single-node topology: extends {@link SingleNodeTestContext} so it
+ * reuses the base node tracking / chain monitor / teardown machinery, but builds its environment with
+ * the bespoke prover opts below (real BB, `realVerifier` L1, the snapshot/account + TokenSimulator
+ * harness, and a hand-built prover node) rather than the base's default fake-prover config.
  */
 
-export class FullProverTest {
+export class FullProverTest extends SingleNodeTestContext {
   static TOKEN_NAME = 'USDC';
   static TOKEN_SYMBOL = 'USD';
   static TOKEN_DECIMALS = 18n;
-  private snapshotManager: ISnapshotManager;
-  logger: Logger;
   wallet!: TestWallet;
   provenWallet!: TestWallet;
   accounts: AztecAddress[] = [];
-  deployedAccounts!: InitialAccountData[];
+  fundedAccounts!: InitialAccountData[];
   fakeProofsAsset!: TokenContract;
+  fakeProofsAssetInstance!: ContractInstanceWithAddress;
   tokenSim!: TokenSimulator;
   aztecNode!: AztecNode;
   aztecNodeAdmin!: AztecNodeAdmin;
   cheatCodes!: CheatCodes;
-  blobSink!: BlobSinkServer;
   private provenComponents: ProvenSetup[] = [];
   private bbConfigCleanup?: () => Promise<void>;
   private acvmConfigCleanup?: () => Promise<void>;
-  circuitProofVerifier?: ClientProtocolCircuitVerifier;
+  /** Returns the proof verifier from the prover node (for test assertions). */
+  get circuitProofVerifier(): ClientProtocolCircuitVerifier | undefined {
+    return this.proverAztecNode?.getProofVerifier();
+  }
   provenAsset!: TokenContract;
-  private context!: SubsystemsContext;
-  private proverNode!: ProverNode;
-  private simulatedProverNode!: ProverNode;
-  public l1Contracts!: DeployL1ContractsReturnType;
+  private proverAztecNode!: AztecNodeService;
+  private simulatedProverAztecNode!: AztecNodeService;
+  public l1Contracts!: DeployAztecL1ContractsReturnType;
   public proverAddress!: EthAddress;
-
-  constructor(
-    testName: string,
-    private minNumberOfTxsPerBlock: number,
-    coinbase: EthAddress,
-    private realProofs = true,
-  ) {
+  private testName: string;
+  private minNumberOfTxsPerBlock: number;
+  private coinbase: EthAddress;
+  private realProofs: boolean;
+
+  constructor(testName: string, minNumberOfTxsPerBlock: number, coinbase: EthAddress, realProofs = true) {
+    super();
+    this.testName = testName;
     this.logger = createLogger(`e2e:full_prover_test:${testName}`);
-    this.snapshotManager = createSnapshotManager(
-      `full_prover_integration/${testName}`,
-      dataPath,
-      { startProverNode: true, fundRewardDistributor: true, coinbase },
-      {
-        realVerifier: realProofs,
-      },
-    );
+    this.minNumberOfTxsPerBlock = minNumberOfTxsPerBlock;
+    this.coinbase = coinbase;
+    this.realProofs = realProofs;
   }
 
   /**
-   * Adds two state shifts to snapshot manager.
-   * 1. Add 2 accounts.
-   * 2. Publicly deploy accounts, deploy token contract
+   * Applies base setup: deploys 2 accounts and token contract.
    */
-  async applyBaseSnapshots() {
-    await this.snapshotManager.snapshot(
-      '2_accounts',
-      deployAccounts(2, this.logger),
-      ({ deployedAccounts }, { wallet }) => {
-        this.deployedAccounts = deployedAccounts;
-        this.accounts = deployedAccounts.map(a => a.address);
-        this.wallet = wallet;
-        return Promise.resolve();
-      },
-    );
+  private async applyBaseSetup() {
+    this.logger.info('Applying base setup: registering funded accounts');
+    this.fundedAccounts = this.context.additionallyFundedAccounts;
+    this.accounts = this.fundedAccounts.map(a => a.address);
+    this.wallet = this.context.wallet;
+    for (const { secret, salt, signingKey } of this.fundedAccounts) {
+      await this.wallet.createSchnorrInitializerlessAccount(secret, salt, signingKey);
+    }
+
+    this.logger.info('Applying base setup: deploying token contract');
+    const { contract: asset, instance } = await TokenContract.deploy(
+      this.wallet,
+      this.accounts[0],
+      FullProverTest.TOKEN_NAME,
+      FullProverTest.TOKEN_SYMBOL,
+      FullProverTest.TOKEN_DECIMALS,
+    ).send({ from: this.accounts[0] });
+    this.logger.verbose(`Token deployed to ${asset.address}`);
+
+    this.fakeProofsAsset = asset;
+    this.fakeProofsAssetInstance = instance;
+    this.logger.verbose(`Token contract address: ${this.fakeProofsAsset.address}`);
 
-    await this.snapshotManager.snapshot(
-      'client_prover_integration',
-      async () => {
-        // Create the token contract state.
-        // Move this account thing to addAccounts above?
-        this.logger.verbose(`Public deploy accounts...`);
-        await publicDeployAccounts(this.wallet, this.accounts.slice(0, 2));
-
-        this.logger.verbose(`Deploying TokenContract...`);
-        const asset = await TokenContract.deploy(
-          this.wallet,
-          this.accounts[0],
-          FullProverTest.TOKEN_NAME,
-          FullProverTest.TOKEN_SYMBOL,
-          FullProverTest.TOKEN_DECIMALS,
-        )
-          .send({ from: this.accounts[0] })
-          .deployed();
-        this.logger.verbose(`Token deployed to ${asset.address}`);
-
-        return { tokenContractAddress: asset.address };
-      },
-      async ({ tokenContractAddress }) => {
-        // Restore the token contract state.
-        this.fakeProofsAsset = await TokenContract.at(tokenContractAddress, this.wallet);
-        this.logger.verbose(`Token contract address: ${this.fakeProofsAsset.address}`);
-
-        this.tokenSim = new TokenSimulator(
-          this.fakeProofsAsset,
-          this.wallet,
-          this.accounts[0],
-          this.logger,
-          this.accounts,
-        );
-
-        expect(await this.fakeProofsAsset.methods.get_admin().simulate({ from: this.accounts[0] })).toBe(
-          this.accounts[0].toBigInt(),
-        );
-      },
+    this.tokenSim = new TokenSimulator(this.fakeProofsAsset, this.wallet, this.accounts[0], this.logger, this.accounts);
+
+    expect((await this.fakeProofsAsset.methods.get_admin().simulate({ from: this.accounts[0] })).result).toBe(
+      this.accounts[0].toBigInt(),
     );
   }
 
-  async setup() {
-    this.context = await this.snapshotManager.setup();
+  override async setup(opts: SingleNodeTestOpts = {}) {
+    this.logger.info('Setting up subsystems from fresh');
+    const context = await setup(0, {
+      ...opts,
+      startProverNode: true,
+      coinbase: this.coinbase,
+      fundSponsoredFPC: true,
+      additionallyFundedAccounts: await generateSchnorrAccounts(2),
+      l1ContractsArgs: { realVerifier: this.realProofs },
+    });
+
+    // Reuse the base context machinery (rollup, epoch cache, chain monitor, node tracking, teardown)
+    // over the environment built above. Restore the FullProverTest-named logger afterwards, since
+    // hydrateFromContext repoints `this.logger` at the context logger.
+    await this.hydrateFromContext(context);
+    this.logger = createLogger(`e2e:full_prover_test:${this.testName}`);
+
+    await this.applyBaseSetup();
+    await this.applyMint();
 
-    // We don't wish to mark as proven automatically, so we set the flag to false
-    this.context.watcher.setIsMarkingAsProven(false);
+    this.logger.info(`Enabling proving`, { realProofs: this.realProofs });
 
-    this.simulatedProverNode = this.context.proverNode!;
+    this.simulatedProverAztecNode = this.context.proverNode!;
     ({
       aztecNode: this.aztecNode,
       deployL1ContractsValues: this.l1Contracts,
       cheatCodes: this.cheatCodes,
-      blobSink: this.blobSink,
     } = this.context);
-    this.aztecNodeAdmin = this.context.aztecNode;
+    this.aztecNodeAdmin = this.context.aztecNodeService;
 
-    const blobSinkClient = createBlobSinkClient({ blobSinkUrl: `http://localhost:${this.blobSink.port}` });
+    const config = this.context.aztecNodeConfig;
 
     // Configure a full prover PXE
     let acvmConfig: Awaited<ReturnType<typeof getACVMConfig>> | undefined;
@@ -183,12 +159,7 @@ export class FullProverTest {
       this.acvmConfigCleanup = acvmConfig.cleanup;
       this.bbConfigCleanup = bbConfig.cleanup;
 
-      if (!bbConfig?.bbWorkingDirectory || !bbConfig?.bbBinaryPath) {
-        throw new Error(`Test must be run with BB native configuration`);
-      }
-
-      const verifier = await BBCircuitVerifier.new(bbConfig);
-      this.circuitProofVerifier = new QueuedIVCVerifier(bbConfig, verifier);
+      await Barretenberg.initSingleton({ backend: BackendType.NativeUnixSocket });
 
       this.logger.debug(`Configuring the node for real proofs...`);
       await this.aztecNodeAdmin.setConfig({
@@ -197,7 +168,6 @@ export class FullProverTest {
       });
     } else {
       this.logger.debug(`Configuring the node min txs per block ${this.minNumberOfTxsPerBlock}...`);
-      this.circuitProofVerifier = new TestCircuitVerifier();
       await this.aztecNodeAdmin.setConfig({
         minTxsPerBlock: this.minNumberOfTxsPerBlock,
       });
@@ -212,23 +182,25 @@ export class FullProverTest {
     this.logger.verbose(`Main setup completed, initializing full prover PXE, Node, and Prover Node`);
     const { wallet: provenWallet, teardown: provenTeardown } = await setupPXEAndGetWallet(
       this.aztecNode,
-      {
-        proverEnabled: this.realProofs,
-        bbBinaryPath: bbConfig?.bbBinaryPath,
-        bbWorkingDirectory: bbConfig?.bbWorkingDirectory,
-      },
+      this.context.aztecNode,
+      { proverEnabled: this.realProofs },
       undefined,
-      true,
+      'pxe-proven',
     );
     this.logger.debug(`Contract address ${this.fakeProofsAsset.address}`);
-    await provenWallet.registerContract(this.fakeProofsAsset);
+    await provenWallet.registerContract(this.fakeProofsAssetInstance, TokenContract.artifact);
 
     for (let i = 0; i < 2; i++) {
-      await provenWallet.createSchnorrAccount(this.deployedAccounts[i].secret, this.deployedAccounts[i].salt);
-      await this.wallet.createSchnorrAccount(this.deployedAccounts[i].secret, this.deployedAccounts[i].salt);
+      // Mirror the initializerless funded accounts (created via createFundedAccounts) in both wallets so
+      // their addresses match the genesis-funded ones.
+      await provenWallet.createSchnorrInitializerlessAccount(
+        this.fundedAccounts[i].secret,
+        this.fundedAccounts[i].salt,
+      );
+      await this.wallet.createSchnorrInitializerlessAccount(this.fundedAccounts[i].secret, this.fundedAccounts[i].salt);
     }
 
-    const asset = await TokenContract.at(this.fakeProofsAsset.address, provenWallet);
+    const asset = TokenContract.at(this.fakeProofsAsset.address, provenWallet);
     this.provenComponents.push({
       wallet: provenWallet,
       teardown: provenTeardown,
@@ -237,20 +209,13 @@ export class FullProverTest {
     this.provenWallet = provenWallet;
     this.logger.info(`Full prover PXE started`);
 
-    // Shutdown the current, simulated prover node
+    // Shutdown the current, simulated prover node (by stopping its hosting aztec node)
     this.logger.verbose('Shutting down simulated prover node');
-    await this.simulatedProverNode.stop();
-
-    // Creating temp store and archiver for fully proven prover node
-    this.logger.verbose('Starting archiver for new prover node');
-    const archiver = await createArchiver(
-      { ...this.context.aztecNodeConfig, dataDirectory: undefined },
-      { blobSinkClient },
-      { blockUntilSync: true },
-    );
+    await this.simulatedProverAztecNode.stop();
 
     // The simulated prover node (now shutdown) used private key index 2
     const proverNodePrivateKey = getPrivateKeyFromIndex(2);
+    const proverNodePrivateKeyHex = `0x${proverNodePrivateKey!.toString('hex')}` as const;
     const proverNodeSenderAddress = privateKeyToAddress(new Buffer32(proverNodePrivateKey!).toString());
     this.proverAddress = EthAddress.fromString(proverNodeSenderAddress);
 
@@ -258,41 +223,48 @@ export class FullProverTest {
     await this.mintFeeJuice(proverNodeSenderAddress);
 
     this.logger.verbose('Starting prover node');
-    const proverConfig: ProverNodeConfig = {
-      ...this.context.aztecNodeConfig,
-      txCollectionNodeRpcUrls: [],
+    const sponsoredFPCAddress = await getSponsoredFPCAddress();
+    const { genesis } = await getGenesisValues(
+      this.context.additionallyFundedAccounts.map(a => a.address).concat(sponsoredFPCAddress),
+      undefined,
+      undefined,
+      this.context.genesis!.genesisTimestamp,
+    );
+
+    const proverNodeConfig: Parameters<typeof createAztecNodeService>[0] = {
+      ...config,
+      enableProverNode: true,
+      disableValidator: true,
       dataDirectory: undefined,
+      txCollectionNodeRpcUrls: [],
       proverId: this.proverAddress,
       realProofs: this.realProofs,
       proverAgentCount: 2,
-      publisherPrivateKeys: [new SecretValue(`0x${proverNodePrivateKey!.toString('hex')}` as const)],
+      proverPublisherPrivateKeys: [new SecretValue(proverNodePrivateKeyHex)],
       proverNodeMaxPendingJobs: 100,
       proverNodeMaxParallelBlocksPerEpoch: 32,
       proverNodePollingIntervalMs: 100,
       txGatheringIntervalMs: 1000,
       txGatheringBatchSize: 10,
       txGatheringMaxParallelRequestsPerNode: 100,
-      txGatheringTimeoutMs: 24_000,
+      // The test warps the L1 clock forward a full epoch via cheatcodes; the prover-node
+      // tracks L1 time, so an in-flight tx-gather would see its deadline jump into the
+      // past. Use a generous window so the deadline survives the warp.
+      txGatheringTimeoutMs: 10 * 60 * 1000,
       proverNodeFailedEpochStore: undefined,
       proverNodeEpochProvingDelayMs: undefined,
+      validatorPrivateKeys: new SecretValue([]),
     };
-    const sponsoredFPCAddress = await getSponsoredFPCAddress();
-    const { prefilledPublicData } = await getGenesisValues(
-      this.context.initialFundedAccounts.map(a => a.address).concat(sponsoredFPCAddress),
-    );
-    this.proverNode = await createProverNode(
-      proverConfig,
-      {
-        aztecNodeTxProvider: this.aztecNode,
-        archiver: archiver as Archiver,
-        blobSinkClient,
-      },
-      { prefilledPublicData },
-    );
-    await this.proverNode.start();
 
-    this.logger.warn(`Proofs are now enabled`);
-    return this;
+    this.proverAztecNode = await createAztecNodeService(
+      proverNodeConfig,
+      { dateProvider: this.context.dateProvider, p2pClientDeps: { rpcTxProviders: [this.aztecNode] } },
+      { genesis },
+    );
+    // Track the real prover node so the base teardown stops it (the simulated one created by `setup`
+    // was already stopped above).
+    this.proverNodes = [this.proverAztecNode];
+    this.logger.warn(`Proofs are now enabled`, { realProofs: this.realProofs });
   }
 
   private async mintFeeJuice(recipient: Hex) {
@@ -304,71 +276,60 @@ export class FullProverTest {
     await this.context.deployL1ContractsValues.l1Client.waitForTransactionReceipt({ hash });
   }
 
-  snapshot = <T>(
-    name: string,
-    apply: (context: SubsystemsContext) => Promise<T>,
-    restore: (snapshotData: T, context: SubsystemsContext) => Promise<void> = () => Promise.resolve(),
-  ): Promise<void> => this.snapshotManager.snapshot(name, apply, restore);
-
-  async teardown() {
-    await this.snapshotManager.teardown();
-
+  override async teardown() {
     // Cleanup related to the full prover PXEs
     for (let i = 0; i < this.provenComponents.length; i++) {
       await this.provenComponents[i].teardown();
     }
 
-    // clean up the full prover node
-    await this.proverNode.stop();
+    // Stop the prover node before destroying the BB singleton it proves with.
+    await this.proverAztecNode.stop();
 
+    await Barretenberg.destroySingleton();
     await this.bbConfigCleanup?.();
     await this.acvmConfigCleanup?.();
+
+    // Stops the chain monitor, the tracked nodes (main node + the already-stopped prover node, a
+    // safe no-op), and the context.
+    await super.teardown();
   }
 
-  async applyMintSnapshot() {
-    await this.snapshotManager.snapshot(
-      'mint',
-      async () => {
-        const { fakeProofsAsset: asset, accounts } = this;
-        const privateAmount = 10000n;
-        const publicAmount = 10000n;
-
-        this.logger.verbose(`Minting ${privateAmount + publicAmount} publicly...`);
-        await asset.methods
-          .mint_to_public(accounts[0], privateAmount + publicAmount)
-          .send({ from: accounts[0] })
-          .wait();
-
-        this.logger.verbose(`Transferring ${privateAmount} to private...`);
-        await asset.methods.transfer_to_private(accounts[0], privateAmount).send({ from: accounts[0] }).wait();
-
-        this.logger.verbose(`Minting complete.`);
-
-        return { amount: publicAmount };
-      },
-      async ({ amount }) => {
-        const {
-          fakeProofsAsset: asset,
-          accounts: [address],
-          tokenSim,
-        } = this;
-        tokenSim.mintPublic(address, amount);
-
-        const publicBalance = await asset.methods.balance_of_public(address).simulate({ from: address });
-        this.logger.verbose(`Public balance of wallet 0: ${publicBalance}`);
-        expect(publicBalance).toEqual(this.tokenSim.balanceOfPublic(address));
-
-        tokenSim.mintPrivate(address, amount);
-        const privateBalance = await asset.methods.balance_of_private(address).simulate({ from: address });
-        this.logger.verbose(`Private balance of wallet 0: ${privateBalance}`);
-        expect(privateBalance).toEqual(tokenSim.balanceOfPrivate(address));
-
-        const totalSupply = await asset.methods.total_supply().simulate({ from: address });
-        this.logger.verbose(`Total supply: ${totalSupply}`);
-        expect(totalSupply).toEqual(tokenSim.totalSupply);
-
-        return Promise.resolve();
-      },
-    );
+  private async applyMint() {
+    this.logger.info('Applying mint setup');
+    const { fakeProofsAsset: asset, accounts } = this;
+    const privateAmount = 10000n;
+    const publicAmount = 10000n;
+
+    this.logger.verbose(`Minting ${privateAmount + publicAmount} publicly...`);
+    await asset.methods.mint_to_public(accounts[0], privateAmount + publicAmount).send({ from: accounts[0] });
+
+    this.logger.verbose(`Transferring ${privateAmount} to private...`);
+    await asset.methods.transfer_to_private(accounts[0], privateAmount).send({ from: accounts[0] });
+
+    this.logger.info(`Minting complete`);
+
+    const {
+      fakeProofsAsset,
+      accounts: [address],
+      tokenSim,
+    } = this;
+    tokenSim.mintPublic(address, publicAmount);
+
+    const { result: publicBalance } = await fakeProofsAsset.methods
+      .balance_of_public(address)
+      .simulate({ from: address });
+    this.logger.verbose(`Public balance of wallet 0: ${publicBalance}`);
+    expect(publicBalance).toEqual(this.tokenSim.balanceOfPublic(address));
+
+    tokenSim.mintPrivate(address, publicAmount);
+    const { result: privateBalance } = await fakeProofsAsset.methods
+      .balance_of_private(address)
+      .simulate({ from: address });
+    this.logger.verbose(`Private balance of wallet 0: ${privateBalance}`);
+    expect(privateBalance).toEqual(tokenSim.balanceOfPrivate(address));
+
+    const { result: totalSupply } = await fakeProofsAsset.methods.total_supply().simulate({ from: address });
+    this.logger.verbose(`Total supply: ${totalSupply}`);
+    expect(totalSupply).toEqual(tokenSim.totalSupply);
   }
 }

package/src/fixtures/elu_monitor.ts

@@ -0,0 +1,126 @@
+import { appendFileSync } from 'node:fs';
+import { type EventLoopUtilization, type IntervalHistogram, monitorEventLoopDelay, performance } from 'node:perf_hooks';
+
+const NANOS_PER_MS = 1_000_000;
+
+/** Samples event-loop utilization, delay histogram, and heap usage per test, writing columnar text to a file. */
+export class EluMonitor {
+  private filePath: string;
+  private intervalMs: number;
+  private timer: ReturnType<typeof setInterval> | undefined;
+  private lastELU: EventLoopUtilization | undefined;
+  private histogram: IntervalHistogram;
+  private testName: string | undefined;
+  private testStart: number | undefined;
+  private eluSamples: number[] = [];
+
+  constructor(filePath: string, intervalMs?: number) {
+    this.filePath = filePath;
+    this.intervalMs = intervalMs ?? 2000;
+    this.histogram = monitorEventLoopDelay({ resolution: 20 });
+  }
+
+  /** Begin sampling for a test. Writes a header line and starts the periodic sampler. */
+  startTest(testName: string): void {
+    this.stopTest();
+
+    this.testName = testName;
+    this.testStart = performance.now();
+    this.eluSamples = [];
+
+    appendFileSync(this.filePath, `\n=== Test: ${testName} ===\n`);
+    appendFileSync(
+      this.filePath,
+      padColumns('TIME', 'ELU', 'EL_DLY_P50', 'EL_DLY_P99', 'EL_DLY_MAX', 'HEAP_MB') + '\n',
+    );
+
+    this.lastELU = performance.eventLoopUtilization();
+    this.histogram.enable();
+
+    this.timer = setInterval(() => this.sample(), this.intervalMs);
+    // Allow the process to exit even if the timer is still running.
+    this.timer.unref();
+  }
+
+  /** Stop sampling and write a summary line. */
+  stopTest(): void {
+    if (!this.timer) {
+      return;
+    }
+
+    // Take a final sample before stopping.
+    this.sample();
+
+    clearInterval(this.timer);
+    this.timer = undefined;
+    this.histogram.disable();
+    this.histogram.reset();
+
+    this.writeSummary();
+
+    this.lastELU = undefined;
+    this.testName = undefined;
+    this.testStart = undefined;
+    this.eluSamples = [];
+  }
+
+  /** Alias for stopTest — call on process exit to flush any remaining data. */
+  stop(): void {
+    this.stopTest();
+  }
+
+  private sample(): void {
+    const newELU = performance.eventLoopUtilization();
+    const delta = performance.eventLoopUtilization(newELU, this.lastELU);
+    this.lastELU = newELU;
+
+    const elu = delta.utilization;
+    this.eluSamples.push(elu);
+
+    const p50 = this.histogram.percentile(50) / NANOS_PER_MS;
+    const p99 = this.histogram.percentile(99) / NANOS_PER_MS;
+    const max = this.histogram.max / NANOS_PER_MS;
+    const heapMb = Math.round(process.memoryUsage().heapUsed / (1024 * 1024));
+
+    const now = new Date();
+    const time = [now.getHours(), now.getMinutes(), now.getSeconds()].map(n => String(n).padStart(2, '0')).join(':');
+
+    const line = padColumns(
+      time,
+      elu.toFixed(2),
+      `${p50.toFixed(1)}ms`,
+      `${p99.toFixed(1)}ms`,
+      `${max.toFixed(1)}ms`,
+      String(heapMb),
+    );
+    appendFileSync(this.filePath, line + '\n');
+
+    // Reset histogram so next sample only reflects the new interval.
+    this.histogram.reset();
+  }
+
+  private writeSummary(): void {
+    if (this.eluSamples.length === 0 || this.testStart === undefined) {
+      return;
+    }
+
+    const mean = this.eluSamples.reduce((a, b) => a + b, 0) / this.eluSamples.length;
+    const maxElu = Math.max(...this.eluSamples);
+    const sorted = [...this.eluSamples].sort((a, b) => a - b);
+    const p90Elu = sorted[Math.floor(sorted.length * 0.9)] ?? maxElu;
+    const durationS = ((performance.now() - this.testStart) / 1000).toFixed(1);
+
+    let summary = `--- Summary: mean_elu=${mean.toFixed(2)} max_elu=${maxElu.toFixed(2)} p90_elu=${p90Elu.toFixed(2)} duration=${durationS}s`;
+    if (maxElu > 0.85) {
+      summary += ' WARNING:ELU>0.85';
+    }
+    summary += ' ---\n';
+
+    appendFileSync(this.filePath, summary);
+  }
+}
+
+function padColumns(...cols: string[]): string {
+  const widths = [11, 7, 12, 12, 12, 8];
+  return cols.map((col, i) => col.padEnd(widths[i] ?? 10)).join('');
+}