@aztec/txe 5.0.0-private.20260318 → 5.0.0-rc.1

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@aztec/txe",
-  "version": "5.0.0-private.20260318",
+  "version": "5.0.0-rc.1",
   "type": "module",
-  "exports": "./dest/index.js",
+  "exports": {
+    "./server": {
+      "types": "./dest/rpc_server.d.ts",
+      "import": "./dest/server.bundle.js"
+    }
+  },
   "bin": "./dest/bin/index.js",
   "typedocOptions": {
     "entryPoints": [
@@ -12,15 +17,18 @@
     "tsconfig": "./tsconfig.json"
   },
   "scripts": {
-    "build": "yarn clean && ../scripts/tsc.sh",
+    "build": "yarn clean && ../scripts/tsc.sh && node ./esbuild.config.mjs",
     "build:dev": "../scripts/tsc.sh --watch",
     "clean": "rm -rf ./dest .tsbuildinfo",
     "test": "NODE_NO_WARNINGS=1 node --experimental-vm-modules ../node_modules/.bin/jest --passWithNoTests --maxWorkers=${JEST_MAX_WORKERS:-8}",
     "dev": "LOG_LEVEL=\"debug; trace: simulator:state_manager; info: json-rpc:proxy\" node ./dest/bin/index.js",
-    "start": "node --no-warnings ./dest/bin/index.js"
+    "start": "node --no-warnings ./dest/bin/index.js",
+    "start:oracle-test-resolver": "node --no-warnings ./dest/bin/oracle_test_server.js",
+    "check_txe_oracle_version": "node ./dest/bin/check_txe_oracle_version.js"
   },
   "inherits": [
-    "../package.common.json"
+    "../package.common.json",
+    "./package.local.json"
   ],
   "jest": {
     "moduleNameMapper": {
@@ -61,38 +69,47 @@
     ]
   },
   "dependencies": {
-    "@aztec/accounts": "5.0.0-private.20260318",
-    "@aztec/archiver": "5.0.0-private.20260318",
-    "@aztec/aztec-node": "5.0.0-private.20260318",
-    "@aztec/aztec.js": "5.0.0-private.20260318",
-    "@aztec/bb-prover": "5.0.0-private.20260318",
-    "@aztec/constants": "5.0.0-private.20260318",
-    "@aztec/foundation": "5.0.0-private.20260318",
-    "@aztec/key-store": "5.0.0-private.20260318",
-    "@aztec/kv-store": "5.0.0-private.20260318",
-    "@aztec/protocol-contracts": "5.0.0-private.20260318",
-    "@aztec/pxe": "5.0.0-private.20260318",
-    "@aztec/simulator": "5.0.0-private.20260318",
-    "@aztec/stdlib": "5.0.0-private.20260318",
-    "@aztec/world-state": "5.0.0-private.20260318",
-    "zod": "^3.23.8"
+    "@aztec/accounts": "5.0.0-rc.1",
+    "@aztec/archiver": "5.0.0-rc.1",
+    "@aztec/aztec-node": "5.0.0-rc.1",
+    "@aztec/aztec.js": "5.0.0-rc.1",
+    "@aztec/bb-prover": "5.0.0-rc.1",
+    "@aztec/bb.js": "5.0.0-rc.1",
+    "@aztec/constants": "5.0.0-rc.1",
+    "@aztec/foundation": "5.0.0-rc.1",
+    "@aztec/key-store": "5.0.0-rc.1",
+    "@aztec/kv-store": "5.0.0-rc.1",
+    "@aztec/protocol-contracts": "5.0.0-rc.1",
+    "@aztec/pxe": "5.0.0-rc.1",
+    "@aztec/simulator": "5.0.0-rc.1",
+    "@aztec/standard-contracts": "5.0.0-rc.1",
+    "@aztec/stdlib": "5.0.0-rc.1",
+    "@aztec/world-state": "5.0.0-rc.1",
+    "msgpackr": "^1.11.2",
+    "zod": "^4"
   },
   "devDependencies": {
     "@jest/globals": "^30.0.0",
     "@types/jest": "^30.0.0",
     "@types/node": "^22.15.17",
     "@typescript/native-preview": "7.0.0-dev.20260113.1",
+    "esbuild": "^0.27.0",
     "jest": "^30.0.0",
     "jest-mock-extended": "^4.0.0",
     "ts-node": "^10.9.1",
     "typescript": "^5.3.3"
   },
   "files": [
+    "dest/bin/index.js",
+    "dest/worker.bundle.js",
+    "dest/server.bundle.js",
+    "dest/chunk-*.js",
+    "dest/*-*.js",
+    "dest/rpc_server.d.ts",
     "dest",
     "src",
     "!*.test.*"
   ],
-  "types": "./dest/index.d.ts",
   "engines": {
     "node": ">=20.10"
   }

package/src/bin/check_txe_oracle_version.ts

@@ -0,0 +1,70 @@
+import { keccak256String } from '@aztec/foundation/crypto/keccak';
+import { getOracleInterfaceSignature, readNumericGlobal } from '@aztec/pxe/bin';
+
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+import { TXE_ORACLE_INTERFACE_HASH, TXE_ORACLE_VERSION_MAJOR } from '../oracle/txe_oracle_version.js';
+
+/**
+ * Verifies that the TXE oracle interfaces match the expected interface hash.
+ *
+ * The TXE oracle interfaces need to be versioned to ensure compatibility between Aztec.nr tests and TXE. This function
+ * computes a hash of the TXE oracle interfaces and compares it against a known hash. If they don't match, it means an
+ * interface has changed and the TXE oracle version needs to be bumped:
+ *   - If the change is backward-breaking (e.g. removing/renaming an oracle), bump TXE_ORACLE_VERSION_MAJOR.
+ *   - If the change is an oracle addition (non-breaking), bump TXE_ORACLE_VERSION_MINOR.
+ */
+function assertTxeOracleInterfaceMatches(): void {
+  const currentDir = dirname(fileURLToPath(import.meta.url));
+  const packageRoot = dirname(dirname(currentDir));
+  const interfacesSourcePath = join(packageRoot, 'src/oracle/interfaces.ts');
+
+  const targets = ['IAvmExecutionOracle', 'ITxeExecutionOracle'];
+  // Not an oracle foreign call handler (see TODO(F-335) in interfaces.ts).
+  const excludedMembers = ['syncContractNonOracleMethod'];
+
+  const txeOracleInterfaceSignature = getOracleInterfaceSignature(interfacesSourcePath, targets, excludedMembers);
+
+  const txeOracleInterfaceHash = keccak256String(txeOracleInterfaceSignature);
+  if (txeOracleInterfaceHash !== TXE_ORACLE_INTERFACE_HASH) {
+    throw new Error(
+      `The TXE oracle interface has changed. Update TXE_ORACLE_INTERFACE_HASH to ${txeOracleInterfaceHash} in txe/src/oracle/txe_oracle_version.ts and bump the TXE oracle version (TXE_ORACLE_VERSION_MAJOR for breaking changes, TXE_ORACLE_VERSION_MINOR for oracle additions).`,
+    );
+  }
+}
+
+/**
+ * Verifies that `TXE_ORACLE_VERSION_MAJOR` is identical across its two hand-maintained copies: the TXE TypeScript
+ * constant and the Aztec.nr Noir test helper constant. These layers can't import each other, so the major version is
+ * duplicated by hand and a mismatch otherwise only surfaces at runtime. This is the TXE counterpart of the contract
+ * oracle version check in `pxe/src/bin/check_oracle_version.ts`; the two version families are tracked separately.
+ *
+ * Only the major version is checked: the minor version legitimately diverges under the "environment minor >= contract
+ * minor" tolerance, so asserting minor equality would false-positive.
+ */
+function assertTxeOracleVersionMajorInSync(): void {
+  const currentDir = dirname(fileURLToPath(import.meta.url));
+  // Go up from dest/bin/ or src/bin/ to the package root (txe/), then up two more to the git root.
+  const packageRoot = dirname(dirname(currentDir));
+  const gitRoot = join(packageRoot, '..', '..');
+
+  const copies = [
+    { label: 'txe/src/txe_oracle_version.ts', value: TXE_ORACLE_VERSION_MAJOR },
+    {
+      label: 'aztec-nr/aztec/src/test/helpers/txe_oracles.nr',
+      value: readNumericGlobal(
+        join(gitRoot, 'noir-projects/aztec-nr/aztec/src/test/helpers/txe_oracles.nr'),
+        'TXE_ORACLE_VERSION_MAJOR',
+      ),
+    },
+  ];
+
+  if (new Set(copies.map(copy => copy.value)).size > 1) {
+    const details = copies.map(copy => `${copy.label}=${copy.value}`).join(', ');
+    throw new Error(`TXE_ORACLE_VERSION_MAJOR is out of sync: ${details}. Bump all copies together.`);
+  }
+}
+
+assertTxeOracleInterfaceMatches();
+assertTxeOracleVersionMajorInSync();

package/src/bin/index.ts

@@ -2,7 +2,16 @@
 import { createLogger } from '@aztec/aztec.js/log';
 import { startHttpRpcServer } from '@aztec/foundation/json-rpc/server';
 
-import { createTXERpcServer } from '../index.js';
+import { createTXERpcServer } from '../rpc_server.js';
+
+// Cap the native world-state thread pool before any import touches @aztec/world-state.
+// `MAX_WORLD_STATE_THREADS` reads HARDWARE_CONCURRENCY at module load and defaults to 16; the
+// pool's worker threads inherit `process.env`, so setting the cap here covers every worker.
+//
+// CAVEAT: HARDWARE_CONCURRENCY is process-global — bb prove/verify, the LMDB reader pool, and
+// the world-state native thread pool all read it. Safe at 2 today because TXE never proves or
+// verifies and only performs light tree updates; raise it if that ever changes.
+process.env.HARDWARE_CONCURRENCY ??= '2';
 
 /**
  * Create and start a new TXE HTTP Server
@@ -23,7 +32,7 @@ async function main() {
   const logger = createLogger('txe:rpc');
   logger.info(`Setting up TXE...`);
 
-  const txeServer = createTXERpcServer(logger);
+  const txeServer = await createTXERpcServer(logger);
   const { port } = await startHttpRpcServer(txeServer, {
     host: '127.0.0.1',
     port: TXE_PORT,

package/src/bin/oracle_test_server.ts

@@ -0,0 +1,51 @@
+#!/usr/bin/env -S node --no-warnings
+import { createLogger } from '@aztec/aztec.js/log';
+import { startHttpRpcServer } from '@aztec/foundation/json-rpc/server';
+
+import { createOracleTestRpcServer } from '../oracle/test-resolver/index.js';
+
+/**
+ * Starts an HTTP RPC server that resolves oracle foreign calls using hardcoded fixture scenarios.
+ * Used by `nargo test --oracle-resolver` to run `#[oracle_test]` roundtrip tests with a dedicated oracle resolver.
+ * Logs fixture coverage on shutdown.
+ */
+async function main() {
+  const { ORACLE_TEST_PORT = 14830 } = process.env;
+
+  const logger = createLogger('txe:oracle-test');
+
+  logger.info('Setting up oracle test resolver...');
+  const { server, resolver } = createOracleTestRpcServer(logger);
+
+  function logCoverageAndExit() {
+    const uncalled = resolver.getUncalledFixtures();
+    const missing = resolver.getMissingFixtures();
+    if (uncalled.length > 0) {
+      logger.warn(`Fixtures never called by any test: ${uncalled.join(', ')}`);
+    }
+    if (missing.length > 0) {
+      logger.debug(`Oracles with no fixture defined: ${missing.join(', ')}`);
+    }
+    if (uncalled.length === 0) {
+      logger.info('All fixture oracles were called.');
+    }
+    process.exit(0);
+  }
+
+  process.on('SIGTERM', logCoverageAndExit);
+  process.on('SIGINT', logCoverageAndExit);
+
+  const { port } = await startHttpRpcServer(server, {
+    host: '127.0.0.1',
+    port: ORACLE_TEST_PORT,
+    timeoutMs: 1e3 * 60 * 5,
+  });
+
+  logger.info(`Oracle test resolver listening on port ${port}`);
+}
+
+main().catch(err => {
+  // eslint-disable-next-line no-console
+  console.error(err);
+  process.exit(1);
+});

package/src/constants.ts

@@ -1,3 +1,13 @@
+import { PRIVATE_LOG_CIPHERTEXT_LEN } from '@aztec/constants';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
 
 export const DEFAULT_ADDRESS = AztecAddress.fromNumber(42);
+
+// This is MAX_MESSAGE_CONTENT_LEN - PRIVATE_EVENT_MSG_PLAINTEXT_RESERVED_FIELDS_LEN
+export const MAX_PRIVATE_EVENT_LEN = 10;
+export const MAX_PRIVATE_EVENTS_PER_TXE_QUERY = 5;
+
+// Arbitrarily set at 64 because we need a bound. Nothing inherent about it.
+export const MAX_OFFCHAIN_EFFECTS_PER_TXE_QUERY = 64;
+// Must match MAX_OFFCHAIN_EFFECT_LEN in noir-projects/aztec-nr/aztec/src/test/helpers/txe_oracles.nr.
+export const MAX_OFFCHAIN_EFFECT_LEN = 2 + PRIVATE_LOG_CIPHERTEXT_LEN;

package/src/dispatcher_pool.ts

@@ -0,0 +1,317 @@
+import { getSchnorrAccountContractArtifact } from '@aztec/accounts/schnorr/lazy';
+import { BackendType, Barretenberg, BarretenbergSync } from '@aztec/bb.js';
+import type { Logger } from '@aztec/foundation/log';
+import { openEphemeralStore } from '@aztec/kv-store/lmdb-v2';
+import { LazyProtocolContractsProvider } from '@aztec/protocol-contracts/providers/lazy';
+import { ContractStore } from '@aztec/pxe/client/lazy';
+import { getStandardAuthRegistry } from '@aztec/standard-contracts/auth-registry/lazy';
+import { getStandardHandshakeRegistry } from '@aztec/standard-contracts/handshake-registry/lazy';
+import { getContractClassFromArtifact } from '@aztec/stdlib/contract';
+
+import { existsSync } from 'node:fs';
+import { cpus } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { Worker } from 'node:worker_threads';
+
+import { TXE_REQUIRED_PROTOCOL_CONTRACTS } from './index.js';
+import type { TXEForeignCallInput } from './index.js';
+import type { ForeignCallResult } from './utils/encoding.js';
+
+void Barretenberg.initSingleton({ backend: BackendType.Wasm, skipSrsInit: true, threads: 1 });
+void BarretenbergSync.initSingleton({ backend: BackendType.Wasm });
+
+/**
+ * Opens a fresh LMDB in a tmp dir and writes the protocol contracts in
+ * {@link TXE_REQUIRED_PROTOCOL_CONTRACTS} plus the standard AuthRegistry, HandshakeRegistry, and the SchnorrAccount artifact,
+ * returning the directory path and the SchnorrAccount class id (hex). The store handle is intentionally kept
+ * alive: closing it would trigger the ephemeral-store cleanup hook and remove the tmp
+ * directory, so any worker that has not yet cloned would find it missing.
+ */
+export async function buildSharedContractStore(): Promise<{ dataDir: string; schnorrClassId: string }> {
+  const kvStore = await openEphemeralStore('txe-shared-contracts', undefined, 2);
+  const dataDir = kvStore.dataDirectory;
+  const contractStore = new ContractStore(kvStore);
+  const provider = new LazyProtocolContractsProvider();
+  const [protocolContracts, standardContracts, schnorrArtifact] = await Promise.all([
+    Promise.all(TXE_REQUIRED_PROTOCOL_CONTRACTS.map(name => provider.getProtocolContractArtifact(name))),
+    Promise.all([getStandardAuthRegistry(), getStandardHandshakeRegistry()]),
+    getSchnorrAccountContractArtifact(),
+  ]);
+  const schnorrClass = await getContractClassFromArtifact(schnorrArtifact);
+  await Promise.all([
+    ...[...protocolContracts, ...standardContracts].flatMap(({ instance, artifact, contractClass }) => [
+      contractStore.addContractArtifact(artifact, contractClass),
+      contractStore.addContractInstance(instance),
+    ]),
+    contractStore.addContractArtifact(schnorrArtifact, schnorrClass),
+  ]);
+  return { dataDir, schnorrClassId: schnorrClass.id.toString() };
+}
+
+/**
+ * Resolves `worker.bundle.js` whether this code is running unbundled (next to dispatcher_pool.js
+ * inside `dest/`) or bundled into `dest/bin/index.js` (one directory deeper). `import.meta.url`
+ * refers to whichever module the calling code actually lives in; we try both relative locations
+ * and use whichever exists.
+ */
+function resolveWorkerBundlePath(): URL {
+  const candidates = [new URL('./worker.bundle.js', import.meta.url), new URL('../worker.bundle.js', import.meta.url)];
+  return candidates.find(u => existsSync(fileURLToPath(u))) ?? candidates[0];
+}
+
+interface SerializedError {
+  message: string;
+  name?: string;
+  stack?: string;
+}
+
+type WorkerMessage =
+  | { type: 'result'; requestId: number; ok: true; value: ForeignCallResult }
+  | { type: 'result'; requestId: number; ok: false; error: SerializedError }
+  | {
+      type: 'memstat';
+      sessions: number;
+      rss: number;
+      heapTotal: number;
+      heapUsed: number;
+      external: number;
+      arrayBuffers: number;
+    };
+
+interface WorkerSlot {
+  worker: Worker;
+  sessions: Set<number>;
+  inFlightRequestIds: Set<number>;
+}
+
+interface PendingRequest {
+  resolve: (value: ForeignCallResult) => void;
+  reject: (err: Error) => void;
+  workerIdx: number;
+}
+
+function deserializeError(payload: SerializedError | undefined): Error {
+  if (!payload) {
+    return new Error('Worker returned an error with no payload');
+  }
+  const err = new Error(payload.message);
+  if (payload.name) {
+    err.name = payload.name;
+  }
+  if (payload.stack) {
+    err.stack = payload.stack;
+  }
+  return err;
+}
+
+export interface TXEDispatcherPoolOptions {
+  /** Number of worker threads */
+  workers?: number;
+}
+
+/**
+ * Main-thread router that owns a pool of TXE worker threads. Each worker runs its own
+ * {@link TXEDispatcher} and handles foreign-call requests for the sessions assigned to it.
+ *
+ * Routing is sticky by `session_id`: new sessions go to a freshly spawned worker (up to
+ * `maxWorkers`) or, once the cap is reached, to the existing worker with the fewest sessions.
+ * Each session's state — TXESession, native world state, KV stores — stays single-threaded
+ * within its worker; different sessions run in parallel across workers.
+ *
+ * The main thread builds a shared protocol-contracts LMDB once and passes its path via
+ * `workerData`. Workers clone the data file on demand instead of re-registering the contracts.
+ */
+export class TXEDispatcherPool {
+  private readonly workers: WorkerSlot[] = [];
+  private readonly sessionToWorker = new Map<number, number>();
+  private readonly pending = new Map<number, PendingRequest>();
+  private nextRequestId = 0;
+  private readonly maxWorkers: number;
+  private readonly readyPromise: Promise<void>;
+  private contractStoreSourceDir?: string;
+  private schnorrClassId?: string;
+  private workerPath?: URL;
+
+  constructor(
+    private readonly logger: Logger,
+    opts: TXEDispatcherPoolOptions = {},
+  ) {
+    // TXE still doesn't scale well beyond 16 workers due to contention
+    this.maxWorkers = Math.max(1, opts.workers ?? Math.min(cpus().length, 16));
+    this.readyPromise = this.init();
+  }
+
+  /** Resolves once the shared protocol-contracts store is built. Workers spawn lazily on demand. */
+  public ready(): Promise<void> {
+    return this.readyPromise;
+  }
+
+  private async init(): Promise<void> {
+    const t0 = Date.now();
+    const { dataDir, schnorrClassId } = await buildSharedContractStore();
+    this.contractStoreSourceDir = dataDir;
+    this.schnorrClassId = schnorrClassId;
+    this.workerPath = resolveWorkerBundlePath();
+    this.logger.debug(`TXE dispatcher pool ready (lazy spawn, cap=${this.maxWorkers})`, {
+      contractStoreSourceDir: dataDir,
+      schnorrClassId,
+      ms: Date.now() - t0,
+    });
+  }
+
+  /**
+   * Spawns a fresh worker and returns its index in `this.workers`. Caller must have awaited
+   * `init()` so the shared contract store path is set. Messages posted before the worker has
+   * finished loading are queued by Node's worker_threads transport.
+   */
+  private spawnWorker(): number {
+    const workerIdx = this.workers.length;
+    const w = new Worker(this.workerPath!, {
+      workerData: { contractStoreSourceDir: this.contractStoreSourceDir, schnorrClassId: this.schnorrClassId },
+    });
+    const slot: WorkerSlot = {
+      worker: w,
+      sessions: new Set(),
+      inFlightRequestIds: new Set(),
+    };
+    this.workers.push(slot);
+    w.on('message', (msg: WorkerMessage) => this.handleMessage(workerIdx, msg));
+    w.on('error', err => this.handleWorkerError(workerIdx, err));
+    w.on('exit', code => {
+      if (code !== 0) {
+        this.handleWorkerError(workerIdx, new Error(`Worker ${workerIdx} exited with code ${code}`));
+      }
+    });
+    this.logger.debug(`Spawning TXE worker ${workerIdx} on demand`, {
+      cap: this.maxWorkers,
+      poolSize: this.workers.length,
+    });
+    return workerIdx;
+  }
+
+  /** Routes a session-dispose request to the worker that owns the session. Fire-and-forget. */
+  disposeSession(sessionId: number): void {
+    const workerIdx = this.sessionToWorker.get(sessionId);
+    if (workerIdx === undefined) {
+      throw new Error(`disposeSession: no worker mapped for session ${sessionId}`);
+    }
+    this.sessionToWorker.delete(sessionId);
+    const slot = this.workers[workerIdx];
+    if (!slot) {
+      throw new Error(`disposeSession: worker ${workerIdx} (session ${sessionId}) missing from pool`);
+    }
+    slot.sessions.delete(sessionId);
+    slot.worker.postMessage({ type: 'dispose-session', sessionId });
+  }
+
+  // eslint-disable-next-line camelcase
+  async resolve_foreign_call(callData: TXEForeignCallInput): Promise<ForeignCallResult> {
+    // Make sure the shared contract store + worker bundle path are in place before we spawn.
+    await this.readyPromise;
+    const sessionId = callData.session_id;
+    let workerIdx = this.sessionToWorker.get(sessionId);
+    if (workerIdx === undefined) {
+      workerIdx = this.pickOrSpawnWorker();
+      this.sessionToWorker.set(sessionId, workerIdx);
+      this.workers[workerIdx].sessions.add(sessionId);
+      this.logger.debug(`Routing new session ${sessionId} to worker ${workerIdx}`);
+    }
+
+    const slot = this.workers[workerIdx];
+    const requestId = this.nextRequestId++;
+    return new Promise<ForeignCallResult>((resolve, reject) => {
+      this.pending.set(requestId, { resolve, reject, workerIdx: workerIdx! });
+      slot.inFlightRequestIds.add(requestId);
+      slot.worker.postMessage({ type: 'foreign-call', requestId, callData });
+    });
+  }
+
+  /** Terminates all workers. Used by tests; production TXE exits the process directly. */
+  async shutdown(): Promise<void> {
+    const slots = this.workers.splice(0, this.workers.length);
+    await Promise.all(slots.map(s => s.worker.terminate()));
+    for (const [requestId, pending] of this.pending) {
+      pending.reject(new Error('TXE dispatcher pool was shut down'));
+      this.pending.delete(requestId);
+    }
+  }
+
+  /**
+   * Returns the index of the worker that should handle a new session. Spawns a fresh worker if
+   * the pool hasn't reached its cap; otherwise picks the existing worker with the fewest
+   * assigned sessions. Always returns a valid index into `this.workers`.
+   */
+  private pickOrSpawnWorker(): number {
+    if (this.workers.length < this.maxWorkers) {
+      return this.spawnWorker();
+    }
+    let minIdx = 0;
+    let minCount = this.workers[0].sessions.size;
+    for (let i = 1; i < this.workers.length; i++) {
+      const count = this.workers[i].sessions.size;
+      if (count < minCount) {
+        minIdx = i;
+        minCount = count;
+      }
+    }
+    return minIdx;
+  }
+
+  private handleMessage(workerIdx: number, msg: WorkerMessage): void {
+    switch (msg.type) {
+      case 'result':
+        this.handleResult(workerIdx, msg);
+        return;
+      case 'memstat':
+        this.logger.debug(`worker ${workerIdx} memstat`, {
+          worker: workerIdx,
+          sessions: msg.sessions,
+          rssMiB: Math.round(msg.rss / 1024 / 1024),
+          heapTotalMiB: Math.round(msg.heapTotal / 1024 / 1024),
+          heapUsedMiB: Math.round(msg.heapUsed / 1024 / 1024),
+          externalMiB: Math.round(msg.external / 1024 / 1024),
+          arrayBuffersMiB: Math.round(msg.arrayBuffers / 1024 / 1024),
+        });
+        return;
+    }
+  }
+
+  private handleResult(workerIdx: number, msg: WorkerMessage & { type: 'result' }): void {
+    const pending = this.pending.get(msg.requestId);
+    if (!pending) {
+      throw new Error(`handleResult: request ${msg.requestId} (worker ${workerIdx}) not in pending map`);
+    }
+    this.pending.delete(msg.requestId);
+    const slot = this.workers[workerIdx];
+    if (!slot) {
+      throw new Error(`handleResult: worker ${workerIdx} (request ${msg.requestId}) missing from pool`);
+    }
+    slot.inFlightRequestIds.delete(msg.requestId);
+    if (msg.ok) {
+      pending.resolve(msg.value);
+    } else {
+      pending.reject(deserializeError(msg.error));
+    }
+  }
+
+  private handleWorkerError(workerIdx: number, err: Error): void {
+    this.logger.error(`TXE worker ${workerIdx} crashed; sessions assigned to it will fail`, err);
+    const slot = this.workers[workerIdx];
+    if (!slot) {
+      throw new Error(`handleWorkerError: worker ${workerIdx} missing from pool (orig err: ${err.message})`);
+    }
+    for (const requestId of slot.inFlightRequestIds) {
+      const pending = this.pending.get(requestId);
+      if (!pending) {
+        throw new Error(`handleWorkerError: in-flight request ${requestId} (worker ${workerIdx}) not in pending map`);
+      }
+      pending.reject(err);
+      this.pending.delete(requestId);
+    }
+    slot.inFlightRequestIds.clear();
+    for (const sessionId of slot.sessions) {
+      this.sessionToWorker.delete(sessionId);
+    }
+    slot.sessions.clear();
+  }
+}