tywrap 0.2.0 → 0.3.0

package/src/runtime/node.ts

@@ -1,145 +1,143 @@
 /**
- * Node.js Runtime Bridge with Optional Connection Pooling
+ * Node.js runtime bridge for BridgeProtocol.
  *
- * NodeBridge is the unified Node.js runtime bridge that supports both single-process
- * (correctness-first) and multi-process (pooled) configurations. By default, it runs
- * in single-process mode for maximum compatibility with the original NodeBridge behavior.
+ * NodeBridge extends BridgeProtocol and uses ProcessIO transports with
+ * optional pooling for concurrent Python execution.
  *
- * For high-throughput workloads, configure pooling via minProcesses/maxProcesses options.
+ * @see https://github.com/bbopen/tywrap/issues/149
  */
 
 import { existsSync } from 'node:fs';
 import { delimiter, isAbsolute, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
-import type { ChildProcess } from 'child_process';
-import { EventEmitter } from 'events';
 
-import { globalCache } from '../utils/cache.js';
-import { autoRegisterArrowDecoder, decodeValueAsync } from '../utils/codec.js';
+import { autoRegisterArrowDecoder } from '../utils/codec.js';
 import { getDefaultPythonPath } from '../utils/python.js';
 import { getVenvBinDir, getVenvPythonExe } from '../utils/runtime.js';
-import type { BridgeInfo } from '../types/index.js';
-
-import { RuntimeBridge } from './base.js';
-import { BridgeDisposedError, BridgeProtocolError } from './errors.js';
-import {
-  BridgeCore,
-  type RpcRequest,
-  ensureJsonFallback,
-  ensurePythonEncoding,
-  getMaxLineLengthFromEnv,
-  getPathKey,
-  normalizeEnv,
-  validateBridgeInfo,
-} from './bridge-core.js';
-import { getComponentLogger } from '../utils/logger.js';
-
-const log = getComponentLogger('NodeBridge');
+import { globalCache } from '../utils/cache.js';
+
+import { BridgeProtocol, type BridgeProtocolOptions } from './bridge-protocol.js';
+import { BridgeExecutionError, BridgeProtocolError } from './errors.js';
+import { ProcessIO } from './process-io.js';
+import { PooledTransport } from './pooled-transport.js';
+import type { CodecOptions } from './safe-codec.js';
+import { PROTOCOL_ID } from './transport.js';
+import type { PooledWorker } from './worker-pool.js';
+
+// =============================================================================
+// OPTIONS
+// =============================================================================
 
 /**
  * Configuration options for NodeBridge.
- *
- * By default, NodeBridge runs in single-process mode (minProcesses=1, maxProcesses=1).
- * For high-throughput workloads, increase these values to enable process pooling.
  */
 export interface NodeBridgeOptions {
   /** Minimum number of Python processes to keep alive. Default: 1 */
   minProcesses?: number;
+
   /** Maximum number of Python processes to spawn. Default: 1 (single-process mode) */
   maxProcesses?: number;
-  /** Time in ms to keep idle processes alive before termination. Default: 300000 (5 min) */
-  maxIdleTime?: number;
-  /** Restart process after this many requests. Default: 1000 */
-  maxRequestsPerProcess?: number;
+
+  /** Maximum concurrent requests per process. Default: 10 */
+  maxConcurrentPerProcess?: number;
+
   /** Path to Python executable. Auto-detected if not specified. */
   pythonPath?: string;
+
   /** Path to python_bridge.py script. Auto-detected if not specified. */
   scriptPath?: string;
+
   /** Path to Python virtual environment. */
   virtualEnv?: string;
+
   /** Working directory for Python process. Default: process.cwd() */
   cwd?: string;
+
   /** Timeout in ms for Python calls. Default: 30000 */
   timeoutMs?: number;
-  /** Maximum line length for JSONL protocol. */
-  maxLineLength?: number;
+
+  /** Timeout in ms for waiting in pool queue. Default: 30000 */
+  queueTimeoutMs?: number;
+
   /** Inherit all environment variables from parent process. Default: false */
   inheritProcessEnv?: boolean;
-  /**
-   * When true, sets TYWRAP_CODEC_FALLBACK=json for the Python process to prefer JSON encoding
-   * for rich types (ndarray/dataframe/series). Default: false for fast-fail on Arrow path issues.
-   */
-  enableJsonFallback?: boolean;
+
   /** Enable result caching for pure functions. Default: false */
   enableCache?: boolean;
+
   /** Optional extra environment variables to pass to the Python subprocess. */
   env?: Record<string, string | undefined>;
+
+  /** Codec options for validation/serialization */
+  codec?: CodecOptions;
+
   /** Commands to run on each process at startup for warming up. */
-  warmupCommands?: Array<{ method: string; params: unknown }>;
+  warmupCommands?: Array<
+    { module: string; functionName: string; args?: unknown[] } | { method: string; params: unknown } // Legacy shape preserved so runtime can surface a migration error
+  >;
+
+  // ===========================================================================
+  // DEPRECATED OPTIONS (kept for backwards compatibility, ignored internally)
+  // ===========================================================================
+
+  /**
+   * @deprecated No longer used. Pool idle time is managed by WorkerPool.
+   */
+  maxIdleTime?: number;
+
+  /**
+   * @deprecated No longer used. Process restart is managed by ProcessIO.
+   */
+  maxRequestsPerProcess?: number;
+
+  /**
+   * @deprecated Use codec.bytesHandling option instead.
+   */
+  enableJsonFallback?: boolean;
+
+  /**
+   * @deprecated Use ProcessIO options instead.
+   */
+  maxLineLength?: number;
 }
 
+// =============================================================================
+// INTERNAL TYPES
+// =============================================================================
+
 interface ResolvedOptions {
   minProcesses: number;
   maxProcesses: number;
-  maxIdleTime: number;
-  maxRequestsPerProcess: number;
+  maxConcurrentPerProcess: number;
   pythonPath: string;
   scriptPath: string;
   virtualEnv?: string;
   cwd: string;
   timeoutMs: number;
-  maxLineLength?: number;
+  queueTimeoutMs: number;
   inheritProcessEnv: boolean;
-  enableJsonFallback: boolean;
   enableCache: boolean;
   env: Record<string, string | undefined>;
-  warmupCommands: Array<{ method: string; params: unknown }>;
+  codec?: CodecOptions;
+  warmupCommands: WarmupCommand[];
 }
 
-interface WorkerProcess {
-  process: ChildProcess;
-  id: string;
-  requestCount: number;
-  lastUsed: number;
-  busy: boolean;
-  quarantined: boolean;
-  core: BridgeCore;
-  stats: {
-    totalRequests: number;
-    totalTime: number;
-    averageTime: number;
-    errorCount: number;
-  };
+interface WarmupCommand {
+  module: string;
+  functionName: string;
+  args?: unknown[];
 }
 
-interface BridgeStats {
-  totalRequests: number;
-  totalTime: number;
-  cacheHits: number;
-  poolHits: number;
-  poolMisses: number;
-  processSpawns: number;
-  processDeaths: number;
-  memoryPeak: number;
-  averageTime: number;
-  cacheHitRate: number;
-}
+const WORKER_READY_TIMEOUT_MS = 5000;
 
-interface BridgeStatsSnapshot extends BridgeStats {
-  poolSize: number;
-  busyWorkers: number;
-  memoryUsage: NodeJS.MemoryUsage;
-  workerStats: Array<{
-    id: string;
-    requestCount: number;
-    averageTime: number;
-    errorCount: number;
-    busy: boolean;
-    pendingRequests: number;
-  }>;
-}
+// =============================================================================
+// UTILITIES
+// =============================================================================
 
+/**
+ * Resolve the default bridge script path.
+ */
 function resolveDefaultScriptPath(): string {
   try {
     return fileURLToPath(new URL('../../runtime/python_bridge.py', import.meta.url));
@@ -148,173 +146,298 @@ function resolveDefaultScriptPath(): string {
   }
 }
 
+/**
+ * Resolve virtual environment paths.
+ */
 function resolveVirtualEnv(
   virtualEnv: string,
   cwd: string
-): {
-  venvPath: string;
-  binDir: string;
-  pythonPath: string;
-} {
+): { venvPath: string; binDir: string; pythonPath: string } {
   const venvPath = resolve(cwd, virtualEnv);
   const binDir = join(venvPath, getVenvBinDir());
   const pythonPath = join(binDir, getVenvPythonExe());
   return { venvPath, binDir, pythonPath };
 }
 
+/**
+ * Get the environment variable key for PATH (case-insensitive on Windows).
+ */
+function getPathKey(env: Record<string, string | undefined>): string {
+  if (Object.prototype.hasOwnProperty.call(env, 'PATH')) {
+    return 'PATH';
+  }
+
+  for (const key of Object.keys(env)) {
+    if (key.toLowerCase() === 'path') {
+      return key;
+    }
+  }
+  return 'PATH';
+}
+
+function setPathValue(env: Record<string, string>, value: string): void {
+  setEnvValue(env, 'PATH', value);
+
+  if (process.platform !== 'win32') {
+    return;
+  }
+
+  for (const key of Object.keys(env)) {
+    if (key !== 'PATH' && key.toLowerCase() === 'path') {
+      setEnvValue(env, key, value);
+    }
+  }
+}
+
+const DANGEROUS_ENV_OVERRIDE_KEYS = new Set(['__proto__', 'prototype', 'constructor']);
+
+function createNullPrototypeEnv(): Record<string, string> {
+  return Object.create(null) as Record<string, string>;
+}
+
+function setEnvValue(env: Record<string, string>, key: string, value: string): void {
+  Object.defineProperty(env, key, {
+    value,
+    writable: true,
+    enumerable: true,
+    configurable: true,
+  });
+}
+
+function getEnvValue(env: Record<string, string>, key: string): string | undefined {
+  const value = Reflect.get(env, key);
+  return typeof value === 'string' ? value : undefined;
+}
+
+function assertSafeEnvOverrideKey(key: string): void {
+  if (DANGEROUS_ENV_OVERRIDE_KEYS.has(key)) {
+    throw new BridgeProtocolError(`Invalid environment override key "${key}" in options.env`);
+  }
+}
+
+function normalizeWarmupCommands(commands: NodeBridgeOptions['warmupCommands']): WarmupCommand[] {
+  if (commands === undefined) {
+    return [];
+  }
+  if (!Array.isArray(commands)) {
+    throw new BridgeProtocolError('warmupCommands must be an array when provided');
+  }
+
+  const warmups = commands;
+  return warmups.map((command, index) => {
+    if (!command || typeof command !== 'object' || Array.isArray(command)) {
+      throw new BridgeProtocolError(
+        `Invalid warmup command at index ${index + 1}: expected { module, functionName, args? }`
+      );
+    }
+
+    const candidate = command as Record<string, unknown>;
+    if ('method' in candidate || 'params' in candidate) {
+      throw new BridgeProtocolError(
+        `Invalid warmup command at index ${index + 1}: legacy { method, params } format is no longer supported. Use { module, functionName, args? }.`
+      );
+    }
+
+    if (typeof candidate.module !== 'string' || candidate.module.trim().length === 0) {
+      throw new BridgeProtocolError(
+        `Invalid warmup command at index ${index + 1}: "module" must be a non-empty string`
+      );
+    }
+    if (typeof candidate.functionName !== 'string' || candidate.functionName.trim().length === 0) {
+      throw new BridgeProtocolError(
+        `Invalid warmup command at index ${index + 1}: "functionName" must be a non-empty string`
+      );
+    }
+    if (candidate.args !== undefined && !Array.isArray(candidate.args)) {
+      throw new BridgeProtocolError(
+        `Invalid warmup command at index ${index + 1}: "args" must be an array when provided`
+      );
+    }
+
+    return {
+      module: candidate.module,
+      functionName: candidate.functionName,
+      args: candidate.args as unknown[] | undefined,
+    };
+  });
+}
+
+// =============================================================================
+// NODE BRIDGE
+// =============================================================================
+
 /**
  * Node.js runtime bridge for executing Python code.
  *
- * By default, runs in single-process mode for correctness-first behavior.
- * Configure minProcesses/maxProcesses for process pooling in high-throughput scenarios.
+ * NodeBridge provides subprocess-based Python execution with optional pooling
+ * for high-throughput workloads. By default, it runs in single-process mode.
+ *
+ * Features:
+ * - Single or multi-process execution via process pooling
+ * - Virtual environment support
+ * - Full SafeCodec validation (NaN/Infinity rejection, key validation)
+ * - Automatic Arrow decoding for DataFrames/ndarrays
+ * - Optional result caching for pure functions
+ * - Process warmup commands
  *
  * @example
  * ```typescript
  * // Single-process mode (default)
  * const bridge = new NodeBridge();
+ * await bridge.init();
+ *
+ * const result = await bridge.call('math', 'sqrt', [16]);
+ * console.log(result); // 4.0
  *
+ * await bridge.dispose();
+ * ```
+ *
+ * @example
+ * ```typescript
  * // Multi-process pooling for high throughput
  * const pooledBridge = new NodeBridge({
- *   minProcesses: 2,
- *   maxProcesses: 8,
+ *   maxProcesses: 4,
+ *   maxConcurrentPerProcess: 2,
  *   enableCache: true,
  * });
+ * await pooledBridge.init();
  * ```
  */
-export class NodeBridge extends RuntimeBridge {
-  private processPool: WorkerProcess[] = [];
-  private roundRobinIndex = 0;
-  private cleanupTimer?: NodeJS.Timeout;
-  private options: ResolvedOptions;
-  private emitter = new EventEmitter();
-  private disposed = false;
-  private bridgeInfo?: BridgeInfo;
-  private initPromise?: Promise<void>;
-
-  // Performance monitoring
-  private stats: BridgeStats = {
-    totalRequests: 0,
-    totalTime: 0,
-    cacheHits: 0,
-    poolHits: 0,
-    poolMisses: 0,
-    processSpawns: 0,
-    processDeaths: 0,
-    memoryPeak: 0,
-    averageTime: 0,
-    cacheHitRate: 0,
-  };
+export class NodeBridge extends BridgeProtocol {
+  private readonly resolvedOptions: ResolvedOptions;
+  private readonly pooledTransport: PooledTransport;
 
+  /**
+   * Create a new NodeBridge instance.
+   *
+   * @param options - Configuration options for the bridge
+   */
   constructor(options: NodeBridgeOptions = {}) {
-    super();
     const cwd = options.cwd ?? process.cwd();
     const virtualEnv = options.virtualEnv ? resolve(cwd, options.virtualEnv) : undefined;
     const venv = virtualEnv ? resolveVirtualEnv(virtualEnv, cwd) : undefined;
     const scriptPath = options.scriptPath ?? resolveDefaultScriptPath();
     const resolvedScriptPath = isAbsolute(scriptPath) ? scriptPath : resolve(cwd, scriptPath);
-    this.options = {
-      // Default to single-process mode for backward compatibility
-      minProcesses: options.minProcesses ?? 1,
-      maxProcesses: options.maxProcesses ?? 1,
-      maxIdleTime: options.maxIdleTime ?? 300000, // 5 minutes
-      maxRequestsPerProcess: options.maxRequestsPerProcess ?? 1000,
+
+    const maxProcesses = options.maxProcesses ?? 1;
+    const minProcesses = Math.min(options.minProcesses ?? 1, maxProcesses);
+
+    const warmupCommands = normalizeWarmupCommands(options.warmupCommands);
+
+    const resolvedOptions: ResolvedOptions = {
+      minProcesses,
+      maxProcesses,
+      maxConcurrentPerProcess: options.maxConcurrentPerProcess ?? 10,
       pythonPath: options.pythonPath ?? venv?.pythonPath ?? getDefaultPythonPath(),
       scriptPath: resolvedScriptPath,
       virtualEnv,
       cwd,
       timeoutMs: options.timeoutMs ?? 30000,
-      maxLineLength: options.maxLineLength,
+      queueTimeoutMs: options.queueTimeoutMs ?? 30000,
       inheritProcessEnv: options.inheritProcessEnv ?? false,
-      enableJsonFallback: options.enableJsonFallback ?? false,
       enableCache: options.enableCache ?? false,
       env: options.env ?? {},
-      warmupCommands: options.warmupCommands ?? [],
+      codec: options.codec,
+      warmupCommands,
     };
 
-    // Start cleanup scheduler for pooled mode
-    this.startCleanupScheduler();
-  }
+    // Build environment for ProcessIO
+    const processEnv = buildProcessEnv(resolvedOptions);
+
+    // Create warmup callback for per-worker initialization
+    const userWarmup =
+      resolvedOptions.warmupCommands.length > 0
+        ? createWarmupCallback(resolvedOptions.warmupCommands, resolvedOptions.timeoutMs)
+        : undefined;
+    const replacementWorkerReady = createWorkerReadyCallback(resolvedOptions.timeoutMs, userWarmup);
+
+    // Create pooled transport with ProcessIO workers
+    const transport = new PooledTransport({
+      createTransport: (): ProcessIO =>
+        new ProcessIO({
+          pythonPath: resolvedOptions.pythonPath,
+          bridgeScript: resolvedOptions.scriptPath,
+          env: processEnv,
+          cwd: resolvedOptions.cwd,
+        }),
+      maxWorkers: resolvedOptions.maxProcesses,
+      minWorkers: resolvedOptions.minProcesses,
+      queueTimeoutMs: resolvedOptions.queueTimeoutMs,
+      maxConcurrentPerWorker: resolvedOptions.maxConcurrentPerProcess,
+      onWorkerReady: userWarmup,
+      onReplacementWorkerReady: replacementWorkerReady,
+    });
 
-  async init(): Promise<void> {
-    if (this.disposed) {
-      throw new BridgeDisposedError('Bridge has been disposed');
-    }
-    if (this.processPool.length >= this.options.minProcesses) {
-      return; // Already initialized
-    }
-    if (this.initPromise) {
-      return this.initPromise;
-    }
-    this.initPromise = this.doInit();
-    return this.initPromise;
+    // Initialize BridgeProtocol with pooled transport
+    const protocolOptions: BridgeProtocolOptions = {
+      transport,
+      codec: resolvedOptions.codec,
+      defaultTimeoutMs: resolvedOptions.timeoutMs,
+    };
+
+    super(protocolOptions);
+
+    this.resolvedOptions = resolvedOptions;
+    this.pooledTransport = transport;
   }
 
-  private async doInit(): Promise<void> {
+  // ===========================================================================
+  // LIFECYCLE
+  // ===========================================================================
+
+  /**
+   * Initialize the bridge.
+   *
+   * Validates the bridge script exists, registers Arrow decoder,
+   * and initializes the transport pool (which runs warmup commands per-worker).
+   */
+  protected override async doInit(): Promise<void> {
+    // Validate script exists
     // eslint-disable-next-line security/detect-non-literal-fs-filename -- script path is user-configured
-    if (!existsSync(this.options.scriptPath)) {
-      throw new BridgeProtocolError(`Python bridge script not found at ${this.options.scriptPath}`);
+    if (!existsSync(this.resolvedOptions.scriptPath)) {
+      throw new BridgeProtocolError(
+        `Python bridge script not found at ${this.resolvedOptions.scriptPath}`
+      );
     }
 
+    // Register Arrow decoder for DataFrames/ndarrays
     const require = createRequire(import.meta.url);
     await autoRegisterArrowDecoder({
       loader: () => require('apache-arrow'),
     });
 
-    // Ensure minimum processes are available
-    while (this.processPool.length < this.options.minProcesses) {
-      await this.spawnProcess();
-    }
-
-    // Validate protocol version
-    await this.refreshBridgeInfo();
-
-    // Warm up processes if configured
-    if (this.options.warmupCommands.length > 0) {
-      await this.warmupProcesses();
-    }
+    // Initialize parent (which initializes transport and runs warmup per-worker)
+    await super.doInit();
   }
 
-  async getBridgeInfo(options: { refresh?: boolean } = {}): Promise<BridgeInfo> {
-    await this.init();
-    if (!this.bridgeInfo || options.refresh) {
-      await this.refreshBridgeInfo();
-    }
-    if (!this.bridgeInfo) {
-      throw new BridgeProtocolError('Bridge info unavailable');
-    }
-    return this.bridgeInfo;
-  }
+  // ===========================================================================
+  // CACHING OVERRIDE
+  // ===========================================================================
 
-  async call<T = unknown>(
+  /**
+   * Override call() to add optional caching.
+   */
+  override async call<T = unknown>(
     module: string,
     functionName: string,
     args: unknown[],
     kwargs?: Record<string, unknown>
   ): Promise<T> {
-    await this.init();
-    const startTime = performance.now();
-
-    const cacheKey = this.options.enableCache
-      ? this.safeCacheKey('runtime_call', module, functionName, args, kwargs)
-      : null;
-    if (cacheKey) {
-      const cached = await globalCache.get<T>(cacheKey);
-      if (cached !== null) {
-        this.stats.cacheHits++;
-        this.updateStats(performance.now() - startTime);
-        return cached;
+    // Check cache if enabled
+    if (this.resolvedOptions.enableCache) {
+      const cacheKey = this.safeCacheKey('runtime_call', module, functionName, args, kwargs);
+      if (cacheKey) {
+        const cached = await globalCache.get<T>(cacheKey);
+        if (cached !== null) {
+          return cached;
+        }
       }
-    }
-
-    try {
-      const result = await this.executeRequest<T>({
-        method: 'call',
-        params: { module, functionName, args, kwargs },
-      });
 
+      // Execute and cache if pure function
+      const startTime = performance.now();
+      const result = await super.call<T>(module, functionName, args, kwargs);
       const duration = performance.now() - startTime;
 
-      // Cache result for pure functions (simple heuristic)
       if (cacheKey && this.isPureFunctionCandidate(functionName, args)) {
         await globalCache.set(cacheKey, result, {
           computeTime: duration,
@@ -322,338 +445,74 @@ export class NodeBridge extends RuntimeBridge {
         });
       }
 
-      this.updateStats(duration);
-      return result;
-    } catch (error) {
-      this.updateStats(performance.now() - startTime, true);
-      throw error;
-    }
-  }
-
-  async instantiate<T = unknown>(
-    module: string,
-    className: string,
-    args: unknown[],
-    kwargs?: Record<string, unknown>
-  ): Promise<T> {
-    await this.init();
-    const startTime = performance.now();
-
-    try {
-      const result = await this.executeRequest<T>({
-        method: 'instantiate',
-        params: { module, className, args, kwargs },
-      });
-
-      this.updateStats(performance.now() - startTime);
       return result;
-    } catch (error) {
-      this.updateStats(performance.now() - startTime, true);
-      throw error;
     }
-  }
-
-  async callMethod<T = unknown>(
-    handle: string,
-    methodName: string,
-    args: unknown[],
-    kwargs?: Record<string, unknown>
-  ): Promise<T> {
-    await this.init();
-    const startTime = performance.now();
-
-    try {
-      const result = await this.executeRequest<T>({
-        method: 'call_method',
-        params: { handle, methodName, args, kwargs },
-      });
-
-      this.updateStats(performance.now() - startTime);
-      return result;
-    } catch (error) {
-      this.updateStats(performance.now() - startTime, true);
-      throw error;
-    }
-  }
 
-  async disposeInstance(handle: string): Promise<void> {
-    await this.init();
-    await this.executeRequest<void>({
-      method: 'dispose_instance',
-      params: { handle },
-    });
+    // No caching - direct call
+    return super.call<T>(module, functionName, args, kwargs);
   }
 
-  /**
-   * Execute request with intelligent process selection
-   */
-  private async executeRequest<T>(payload: Omit<RpcRequest, 'id' | 'protocol'>): Promise<T> {
-    let worker = this.selectOptimalWorker();
-
-    // Spawn new process if none available and under limit
-    if (!worker && this.processPool.length < this.options.maxProcesses) {
-      try {
-        worker = await this.spawnProcess();
-        this.stats.poolMisses++;
-      } catch (error) {
-        throw new Error(`Failed to spawn worker process: ${error}`);
-      }
-    }
-
-    // Wait for worker if all are busy
-    worker ??= await this.waitForAvailableWorker();
-
-    this.stats.poolHits++;
-    return this.sendToWorker<T>(worker, payload);
-  }
+  // ===========================================================================
+  // POOL STATISTICS
+  // ===========================================================================
 
   /**
-   * Select optimal worker based on load and performance
+   * Get current pool statistics.
    */
-  private selectOptimalWorker(): WorkerProcess | null {
-    // For single-process mode, allow concurrent requests to the same worker.
-    // BridgeCore handles request ID multiplexing, so multiple in-flight requests are safe.
-    // This preserves original NodeBridge behavior where concurrent calls were allowed.
-    if (this.options.maxProcesses === 1 && this.processPool.length === 1) {
-      const worker = this.processPool[0];
-      if (worker && !worker.quarantined && worker.process.exitCode === null) {
-        return worker;
-      }
-      return null;
-    }
-
-    // For multi-worker pools, use busy status for load balancing
-    const availableWorkers = this.processPool.filter(
-      w => !w.busy && !w.quarantined && w.process.exitCode === null
-    );
-
-    if (availableWorkers.length === 0) {
-      return null;
-    }
-
-    // Simple round-robin for now, could be enhanced with load-based selection
-    const worker = availableWorkers[this.roundRobinIndex % availableWorkers.length];
-    this.roundRobinIndex = (this.roundRobinIndex + 1) % availableWorkers.length;
-
-    return worker ?? null;
-  }
-
-  /**
-   * Wait for any worker to become available
-   */
-  private async waitForAvailableWorker(timeoutMs: number = 5000): Promise<WorkerProcess> {
-    return new Promise((resolvePromise, reject) => {
-      const timeout = setTimeout(() => {
-        reject(new Error('Timeout waiting for available worker'));
-      }, timeoutMs);
-
-      const checkWorker = (): void => {
-        const worker = this.selectOptimalWorker();
-        if (worker) {
-          clearTimeout(timeout);
-          resolvePromise(worker);
-        } else {
-          // Check again in 10ms
-          setTimeout(checkWorker, 10);
-        }
-      };
-
-      checkWorker();
-    });
-  }
-
-  /**
-   * Send request to specific worker
-   */
-  private async sendToWorker<T>(
-    worker: WorkerProcess,
-    payload: Omit<RpcRequest, 'id' | 'protocol'>
-  ): Promise<T> {
-    worker.busy = true;
-    worker.requestCount++;
-    worker.lastUsed = Date.now();
-
-    const startTime = performance.now();
-
-    try {
-      const result = await worker.core.send<T>(payload);
-      const duration = performance.now() - startTime;
-      worker.stats.totalTime += duration;
-      worker.stats.totalRequests++;
-      worker.stats.averageTime = worker.stats.totalTime / worker.stats.totalRequests;
-      return result;
-    } catch (error) {
-      worker.stats.errorCount++;
-      throw error;
-    } finally {
-      worker.busy = false;
-    }
-  }
-
-  private quarantineWorker(worker: WorkerProcess, error: Error): void {
-    if (worker.quarantined) {
-      return;
-    }
-    worker.quarantined = true;
-    log.warn('Quarantining worker', { workerId: worker.id, error: String(error) });
-    this.terminateWorker(worker, { force: true })
-      .then(() => {
-        if (!this.disposed && this.processPool.length < this.options.minProcesses) {
-          this.spawnProcess().catch(spawnError => {
-            log.error('Failed to spawn replacement worker after quarantine', {
-              error: String(spawnError),
-            });
-          });
-        }
-      })
-      .catch(terminateError => {
-        log.warn('Failed to terminate quarantined worker', {
-          workerId: worker.id,
-          error: String(terminateError),
-        });
-      });
-  }
-
-  /**
-   * Spawn new worker process with optimizations
-   */
-  private async spawnProcess(): Promise<WorkerProcess> {
-    const { spawn } = await import('child_process');
-
-    const workerId = `worker_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
-
-    const env = this.buildEnv();
-    env.PYTHONUNBUFFERED = '1'; // Ensure immediate output
-    env.PYTHONDONTWRITEBYTECODE = '1'; // Skip .pyc files for faster startup
-    const maxLineLength = this.options.maxLineLength ?? getMaxLineLengthFromEnv(env);
-
-    const childProcess = spawn(this.options.pythonPath, [this.options.scriptPath], {
-      cwd: this.options.cwd,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      env,
-    });
-
-    const worker: WorkerProcess = {
-      process: childProcess,
-      id: workerId,
-      requestCount: 0,
-      lastUsed: Date.now(),
-      busy: false,
-      quarantined: false,
-      core: null as unknown as BridgeCore,
-      stats: {
-        totalRequests: 0,
-        totalTime: 0,
-        averageTime: 0,
-        errorCount: 0,
-      },
+  getPoolStats(): { workerCount: number; queueLength: number; totalInFlight: number } {
+    return {
+      workerCount: this.pooledTransport.workerCount,
+      queueLength: this.pooledTransport.queueLength,
+      totalInFlight: this.pooledTransport.totalInFlight,
     };
-
-    worker.core = new BridgeCore(
-      {
-        write: (data: string): void => {
-          if (!worker.process.stdin?.writable) {
-            throw new BridgeProtocolError('Worker process stdin not writable');
-          }
-          worker.process.stdin.write(data);
-        },
-      },
-      {
-        timeoutMs: this.options.timeoutMs,
-        maxLineLength,
-        decodeValue: decodeValueAsync,
-        onFatalError: (error: Error): void => this.quarantineWorker(worker, error),
-        onTimeout: (error: Error): void => this.quarantineWorker(worker, error),
-      }
-    );
-
-    // Setup process event handlers
-    this.setupProcessHandlers(worker);
-
-    this.processPool.push(worker);
-    this.stats.processSpawns++;
-
-    return worker;
   }
 
   /**
-   * Setup event handlers for worker process
+   * Get bridge statistics.
+   *
+   * @deprecated Use getPoolStats() instead. This method is provided for
+   * backwards compatibility and returns a subset of the previous stats.
    */
-  private setupProcessHandlers(worker: WorkerProcess): void {
-    const childProcess = worker.process;
-
-    childProcess.stdout?.on('data', (chunk: Buffer) => {
-      worker.core.handleStdoutData(chunk);
-    });
-
-    childProcess.stderr?.on('data', (chunk: Buffer) => {
-      worker.core.handleStderrData(chunk);
-      const errorText = chunk.toString().trim();
-      if (errorText) {
-        log.warn('Worker stderr', { workerId: worker.id, output: errorText });
-      }
-    });
-
-    // Handle process exit
-    childProcess.on('exit', code => {
-      log.warn('Worker exited', { workerId: worker.id, code });
-      worker.core.handleProcessExit();
-      this.handleWorkerExit(worker, code);
-    });
-
-    // Handle process errors
-    childProcess.on('error', error => {
-      log.error('Worker error', { workerId: worker.id, error: String(error) });
-      worker.core.handleProcessError(error);
-      this.handleWorkerExit(worker, -1);
-    });
+  getStats(): {
+    totalRequests: number;
+    totalTime: number;
+    cacheHits: number;
+    poolHits: number;
+    poolMisses: number;
+    processSpawns: number;
+    processDeaths: number;
+    memoryPeak: number;
+    averageTime: number;
+    cacheHitRate: number;
+    poolSize: number;
+    busyWorkers: number;
+  } {
+    const poolStats = this.getPoolStats();
+    return {
+      // Legacy stats (no longer tracked, return 0)
+      totalRequests: 0,
+      totalTime: 0,
+      cacheHits: 0,
+      poolHits: 0,
+      poolMisses: 0,
+      processSpawns: 0,
+      processDeaths: 0,
+      memoryPeak: 0,
+      averageTime: 0,
+      cacheHitRate: 0,
+      // Current pool stats
+      poolSize: poolStats.workerCount,
+      busyWorkers: poolStats.totalInFlight,
+    };
   }
 
-  /**
-   * Handle worker process exit
-   */
-  private handleWorkerExit(worker: WorkerProcess, _code: number | null): void {
-    if (!this.processPool.includes(worker)) {
-      return;
-    }
-
-    worker.core.clear();
-
-    // Remove from pool
-    const index = this.processPool.indexOf(worker);
-    if (index >= 0) {
-      this.processPool.splice(index, 1);
-      this.stats.processDeaths++;
-    }
-
-    // Spawn replacement if needed and not disposing
-    if (!this.disposed && this.processPool.length < this.options.minProcesses) {
-      this.spawnProcess().catch(error => {
-        log.error('Failed to spawn replacement worker', { error: String(error) });
-      });
-    }
-  }
+  // ===========================================================================
+  // PRIVATE HELPERS
+  // ===========================================================================
 
   /**
-   * Warm up processes with configured commands
+   * Generate a cache key, returning null if generation fails.
    */
-  private async warmupProcesses(): Promise<void> {
-    const warmupPromises = this.processPool.map(async worker => {
-      for (const cmd of this.options.warmupCommands) {
-        try {
-          await this.sendToWorker(worker, {
-            method: cmd.method as 'call' | 'instantiate' | 'call_method' | 'dispose_instance',
-            params: cmd.params,
-          });
-        } catch (error) {
-          log.warn('Warmup command failed', { workerId: worker.id, error: String(error) });
-        }
-      }
-    });
-
-    await Promise.all(warmupPromises);
-  }
-
   private safeCacheKey(prefix: string, ...inputs: unknown[]): string | null {
     try {
       return globalCache.generateKey(prefix, ...inputs);
@@ -663,10 +522,9 @@ export class NodeBridge extends RuntimeBridge {
   }
 
   /**
-   * Heuristic to determine if function result should be cached
+   * Heuristic to determine if function result should be cached.
    */
   private isPureFunctionCandidate(functionName: string, args: unknown[]): boolean {
-    // Simple heuristics - could be made more sophisticated
     const pureFunctionPatterns = [
       /^(get|fetch|read|load|find|search|query|select)_/i,
       /^(compute|calculate|process|transform|convert)_/i,
@@ -679,222 +537,251 @@ export class NodeBridge extends RuntimeBridge {
       /random|uuid|timestamp|now|current/i,
     ];
 
-    // Don't cache if function name suggests mutation
     if (impureFunctionPatterns.some(pattern => pattern.test(functionName))) {
       return false;
     }
 
-    // Cache if function name suggests pure computation
     if (pureFunctionPatterns.some(pattern => pattern.test(functionName))) {
       return true;
     }
 
-    // Don't cache if args contain mutable objects (very basic check)
     const hasComplexArgs = args.some(
       arg => arg !== null && typeof arg === 'object' && !(arg instanceof Date)
     );
 
-    return !hasComplexArgs && args.length <= 3; // Cache simple calls with few args
-  }
-
-  /**
-   * Update performance statistics
-   */
-  private updateStats(duration: number, _error: boolean = false): void {
-    this.stats.totalRequests++;
-    this.stats.totalTime += duration;
-
-    const currentMemory = process.memoryUsage().heapUsed;
-    if (currentMemory > this.stats.memoryPeak) {
-      this.stats.memoryPeak = currentMemory;
-    }
+    return !hasComplexArgs && args.length <= 3;
   }
+}
 
-  /**
-   * Get performance statistics
-   */
-  getStats(): BridgeStatsSnapshot {
-    const avgTime =
-      this.stats.totalRequests > 0 ? this.stats.totalTime / this.stats.totalRequests : 0;
-    const hitRate =
-      this.stats.totalRequests > 0 ? this.stats.cacheHits / this.stats.totalRequests : 0;
+// =============================================================================
+// WARMUP CALLBACK
+// =============================================================================
 
-    return {
-      ...this.stats,
-      averageTime: avgTime,
-      cacheHitRate: hitRate,
-      poolSize: this.processPool.length,
-      busyWorkers: this.processPool.filter(w => w.busy).length,
-      memoryUsage: process.memoryUsage(),
-      workerStats: this.processPool.map(w => ({
-        id: w.id,
-        requestCount: w.requestCount,
-        averageTime: w.stats.averageTime,
-        errorCount: w.stats.errorCount,
-        busy: w.busy,
-        pendingRequests: w.core.getPendingCount(),
-      })),
-    };
-  }
-
-  /**
-   * Cleanup idle processes
-   */
-  private async cleanup(): Promise<void> {
-    const now = Date.now();
-    const idleWorkers = this.processPool.filter(
-      w =>
-        !w.busy &&
-        now - w.lastUsed > this.options.maxIdleTime &&
-        this.processPool.length > this.options.minProcesses
-    );
+/**
+ * Simple request ID generator for warmup commands.
+ */
+let warmupRequestId = 0;
+function generateWarmupId(): number {
+  return ++warmupRequestId;
+}
 
-    for (const worker of idleWorkers) {
-      await this.terminateWorker(worker);
+/**
+ * Create a callback that runs warmup commands on each worker.
+ *
+ * The callback sends warmup commands directly to the worker's transport,
+ * bypassing the pool to ensure each worker gets warmed up individually.
+ */
+function createWarmupCallback(
+  warmupCommands: WarmupCommand[],
+  timeoutMs: number
+): (worker: PooledWorker) => Promise<void> {
+  return async (worker: PooledWorker) => {
+    for (const [index, cmd] of warmupCommands.entries()) {
+      const commandLabel = `${cmd.module}.${cmd.functionName}`;
+      await executeWorkerCall(
+        worker,
+        {
+          module: cmd.module,
+          functionName: cmd.functionName,
+          args: cmd.args ?? [],
+        },
+        timeoutMs,
+        {
+          label: `Warmup command #${index + 1} (${commandLabel})`,
+          invalidJsonMessage: 'returned invalid JSON response',
+          malformedEnvelopeMessage: requestId =>
+            `returned malformed response envelope for request ${requestId}`,
+          pythonErrorMessage: (errorType, errorMessage) => `failed: ${errorType}: ${errorMessage}`,
+          malformedErrorPayloadMessage: 'failed with malformed error payload',
+        }
+      );
     }
+  };
+}
 
-    // Restart workers that have handled too many requests
-    const overusedWorkers = this.processPool.filter(
-      w => !w.busy && w.requestCount >= this.options.maxRequestsPerProcess
+function createWorkerReadyCallback(
+  timeoutMs: number,
+  extraWarmup?: (worker: PooledWorker) => Promise<void>
+): (worker: PooledWorker) => Promise<void> {
+  return async (worker: PooledWorker) => {
+    const result = await executeWorkerCall(
+      worker,
+      {
+        module: 'builtins',
+        functionName: 'len',
+        args: [[]],
+      },
+      Math.max(timeoutMs, WORKER_READY_TIMEOUT_MS),
+      {
+        label: 'Worker readiness probe (builtins.len)',
+        invalidJsonMessage: 'returned invalid JSON response',
+        malformedEnvelopeMessage: requestId =>
+          `returned malformed response envelope for request ${requestId}`,
+        pythonErrorMessage: (errorType, errorMessage) => `failed: ${errorType}: ${errorMessage}`,
+        malformedErrorPayloadMessage: 'failed with malformed error payload',
+      }
     );
 
-    for (const worker of overusedWorkers) {
-      await this.terminateWorker(worker);
-      if (this.processPool.length < this.options.minProcesses) {
-        await this.spawnProcess();
-      }
+    if (result !== 0) {
+      throw new BridgeExecutionError(
+        `Worker readiness probe (builtins.len) returned unexpected result: ${JSON.stringify(result)}`
+      );
     }
-  }
 
-  /**
-   * Gracefully terminate a worker
-   */
-  private async terminateWorker(
-    worker: WorkerProcess,
-    options: { force?: boolean } = {}
-  ): Promise<void> {
-    if (worker.busy && !options.force) {
-      return;
-    }
+    await extraWarmup?.(worker);
+  };
+}
 
-    const index = this.processPool.indexOf(worker);
-    if (index >= 0) {
-      this.processPool.splice(index, 1);
-      this.stats.processDeaths++;
-    }
+interface WorkerCallSpec {
+  module: string;
+  functionName: string;
+  args: unknown[];
+}
 
-    worker.core.handleProcessExit();
-    worker.core.clear();
+interface WorkerCallErrorMessages {
+  label: string;
+  invalidJsonMessage: string;
+  malformedEnvelopeMessage: (requestId: number) => string;
+  pythonErrorMessage: (errorType: string, errorMessage: string) => string;
+  malformedErrorPayloadMessage: string;
+}
 
-    // Graceful termination
-    try {
-      if (worker.process.exitCode === null) {
-        worker.process.kill('SIGTERM');
-
-        // Force kill if not terminated in 5 seconds
-        setTimeout(() => {
-          if (worker.process.exitCode === null) {
-            worker.process.kill('SIGKILL');
-          }
-        }, 5000);
-      }
-    } catch (error) {
-      log.warn('Error terminating worker', { workerId: worker.id, error: String(error) });
-    }
+async function executeWorkerCall(
+  worker: PooledWorker,
+  request: WorkerCallSpec,
+  timeoutMs: number,
+  messages: WorkerCallErrorMessages
+): Promise<unknown> {
+  const requestId = generateWarmupId();
+  let message: string;
+  try {
+    message = JSON.stringify({
+      id: requestId,
+      protocol: PROTOCOL_ID,
+      method: 'call',
+      params: {
+        module: request.module,
+        functionName: request.functionName,
+        args: request.args,
+        kwargs: {},
+      },
+    });
+  } catch (error) {
+    throw new BridgeExecutionError(
+      `${messages.label} failed to encode request: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error instanceof Error ? error : undefined }
+    );
   }
 
-  /**
-   * Start cleanup scheduler
-   */
-  private startCleanupScheduler(): void {
-    this.cleanupTimer = setInterval(async () => {
-      try {
-        await this.cleanup();
-      } catch (error) {
-        log.error('Cleanup error', { error: String(error) });
-      }
-    }, 60000); // Cleanup every minute
+  let response: string;
+  try {
+    response = await worker.transport.send(message, timeoutMs);
+  } catch (error) {
+    throw new BridgeExecutionError(
+      `${messages.label} failed to send: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error instanceof Error ? error : undefined }
+    );
   }
 
-  /**
-   * Dispose all resources
-   */
-  async dispose(): Promise<void> {
-    if (this.disposed) {
-      return;
-    }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(response);
+  } catch (error) {
+    throw new BridgeExecutionError(`${messages.label} ${messages.invalidJsonMessage}`, {
+      cause: error instanceof Error ? error : undefined,
+    });
+  }
 
-    this.disposed = true;
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new BridgeExecutionError(
+      `${messages.label} ${messages.malformedEnvelopeMessage(requestId)}`
+    );
+  }
 
-    if (this.cleanupTimer) {
-      clearInterval(this.cleanupTimer);
-      this.cleanupTimer = undefined;
+  const envelope = parsed as { result?: unknown; error?: unknown };
+  if ('error' in envelope && envelope.error !== undefined && envelope.error !== null) {
+    const errorPayload = envelope.error;
+    if (errorPayload && typeof errorPayload === 'object' && !Array.isArray(errorPayload)) {
+      const err = errorPayload as { type?: unknown; message?: unknown };
+      const errType = typeof err.type === 'string' ? err.type : 'Error';
+      const errMessage = typeof err.message === 'string' ? err.message : 'Unknown error';
+      throw new BridgeExecutionError(
+        `${messages.label} ${messages.pythonErrorMessage(errType, errMessage)}`
+      );
     }
 
-    // Terminate all workers
-    const terminationPromises = this.processPool.map(worker =>
-      this.terminateWorker(worker, { force: true })
-    );
-    await Promise.all(terminationPromises);
+    throw new BridgeExecutionError(`${messages.label} ${messages.malformedErrorPayloadMessage}`);
+  }
 
-    this.processPool.length = 0;
-    this.emitter.removeAllListeners();
+  if (!('result' in envelope)) {
+    throw new BridgeExecutionError(
+      `${messages.label} ${messages.malformedEnvelopeMessage(requestId)}`
+    );
   }
 
-  private buildEnv(): NodeJS.ProcessEnv {
-    const allowedPrefixes = ['TYWRAP_'];
-    const allowedKeys = new Set(['path', 'pythonpath', 'virtual_env', 'pythonhome']);
-    const baseEnv: Record<string, string | undefined> = {};
-    if (this.options.inheritProcessEnv) {
-      for (const [key, value] of Object.entries(process.env)) {
-        // eslint-disable-next-line security/detect-object-injection -- env keys are dynamic by design
-        baseEnv[key] = value;
+  return envelope.result;
+}
+
+// =============================================================================
+// ENVIRONMENT BUILDING
+// =============================================================================
+
+/**
+ * Build environment variables for ProcessIO.
+ */
+function buildProcessEnv(options: ResolvedOptions): Record<string, string> {
+  const allowedPrefixes = ['TYWRAP_'];
+  const allowedKeys = new Set(['path', 'pythonpath', 'virtual_env', 'pythonhome']);
+  const env = createNullPrototypeEnv();
+
+  // Copy allowed env vars from process.env
+  if (options.inheritProcessEnv) {
+    for (const [key, value] of Object.entries(process.env)) {
+      if (value !== undefined) {
+        setEnvValue(env, key, value);
       }
-    } else {
-      for (const [key, value] of Object.entries(process.env)) {
-        if (
-          allowedKeys.has(key.toLowerCase()) ||
-          allowedPrefixes.some(prefix => key.startsWith(prefix))
-        ) {
-          // eslint-disable-next-line security/detect-object-injection -- env keys are dynamic by design
-          baseEnv[key] = value;
-        }
+    }
+  } else {
+    for (const [key, value] of Object.entries(process.env)) {
+      if (
+        value !== undefined &&
+        (allowedKeys.has(key.toLowerCase()) || allowedPrefixes.some(p => key.startsWith(p)))
+      ) {
+        setEnvValue(env, key, value);
       }
     }
+  }
 
-    let env = normalizeEnv(baseEnv, this.options.env);
-
-    if (this.options.virtualEnv) {
-      const venv = resolveVirtualEnv(this.options.virtualEnv, this.options.cwd);
-      env.VIRTUAL_ENV = venv.venvPath;
-      const pathKey = getPathKey(env);
-      // eslint-disable-next-line security/detect-object-injection -- env keys are dynamic by design
-      const currentPath = env[pathKey] ?? '';
-      // eslint-disable-next-line security/detect-object-injection -- env keys are dynamic by design
-      env[pathKey] = `${venv.binDir}${delimiter}${currentPath}`;
+  // Apply user overrides
+  for (const [key, value] of Object.entries(options.env)) {
+    assertSafeEnvOverrideKey(key);
+    if (value !== undefined) {
+      setEnvValue(env, key, value);
     }
+  }
 
-    ensurePythonEncoding(env);
-    ensureJsonFallback(env, this.options.enableJsonFallback);
-
-    env = normalizeEnv(env, {});
-    return env;
+  // Configure virtual environment
+  if (options.virtualEnv) {
+    const venv = resolveVirtualEnv(options.virtualEnv, options.cwd);
+    env.VIRTUAL_ENV = venv.venvPath;
+    const pathKey = getPathKey(env);
+    const currentPath = getEnvValue(env, pathKey);
+    setPathValue(env, currentPath ? `${venv.binDir}${delimiter}${currentPath}` : venv.binDir);
   }
 
-  private async refreshBridgeInfo(): Promise<void> {
-    const info = await this.executeRequest<BridgeInfo>({ method: 'meta', params: {} });
-    validateBridgeInfo(info);
-    this.bridgeInfo = info;
+  // Add cwd to PYTHONPATH so Python can find modules in the working directory
+  if (options.cwd) {
+    const currentPythonPath = env.PYTHONPATH ?? '';
+    env.PYTHONPATH = currentPythonPath
+      ? `${options.cwd}${delimiter}${currentPythonPath}`
+      : options.cwd;
   }
-}
 
-/**
- * @deprecated Use NodeBridge with minProcesses/maxProcesses options instead.
- * This alias is provided for backward compatibility.
- */
-export { NodeBridge as OptimizedNodeBridge };
+  // Ensure Python uses UTF-8
+  env.PYTHONUTF8 = '1';
+  env.PYTHONIOENCODING = 'UTF-8';
+  env.PYTHONUNBUFFERED = '1';
+  env.PYTHONDONTWRITEBYTECODE = '1';
 
-/**
- * @deprecated Use NodeBridgeOptions instead.
- */
-export type { NodeBridgeOptions as ProcessPoolOptions };
+  return env;
+}