tywrap 0.1.1 → 0.2.0

package/src/runtime/node.ts

@@ -1,64 +1,143 @@
 /**
- * Node.js runtime bridge (minimal MVP)
+ * Node.js Runtime Bridge with Optional Connection Pooling
+ *
+ * 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.
+ *
+ * For high-throughput workloads, configure pooling via minProcesses/maxProcesses options.
  */
 
 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 { decodeValueAsync } from '../utils/codec.js';
+import { globalCache } from '../utils/cache.js';
+import { autoRegisterArrowDecoder, decodeValueAsync } 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 {
-  BridgeDisposedError,
-  BridgeExecutionError,
-  BridgeProtocolError,
-  BridgeTimeoutError,
-} from './errors.js';
-import { TYWRAP_PROTOCOL, TYWRAP_PROTOCOL_VERSION } from './protocol.js';
-
-interface RpcRequest {
-  id: number;
-  protocol: string;
-  method: 'call' | 'instantiate' | 'call_method' | 'dispose_instance' | 'meta';
-  params: unknown;
-}
+  BridgeCore,
+  type RpcRequest,
+  ensureJsonFallback,
+  ensurePythonEncoding,
+  getMaxLineLengthFromEnv,
+  getPathKey,
+  normalizeEnv,
+  validateBridgeInfo,
+} from './bridge-core.js';
+import { getComponentLogger } from '../utils/logger.js';
 
-interface RpcResponse<T = unknown> {
-  id: number;
-  protocol: string;
-  result?: T;
-  error?: { type: string; message: string; traceback?: string };
-}
+const log = getComponentLogger('NodeBridge');
 
+/**
+ * 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;
+  /** Path to Python executable. Auto-detected if not specified. */
   pythonPath?: string;
-  scriptPath?: string; // path to python_bridge.py
+  /** 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;
+  /** 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;
-  /**
-   * Optional extra environment variables to pass to the Python subprocess.
-   */
+  /** 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>;
+  /** Commands to run on each process at startup for warming up. */
+  warmupCommands?: Array<{ method: string; params: unknown }>;
 }
 
-interface ResolvedNodeBridgeOptions {
+interface ResolvedOptions {
+  minProcesses: number;
+  maxProcesses: number;
+  maxIdleTime: number;
+  maxRequestsPerProcess: number;
   pythonPath: string;
   scriptPath: string;
   virtualEnv?: string;
   cwd: string;
   timeoutMs: number;
+  maxLineLength?: number;
+  inheritProcessEnv: boolean;
   enableJsonFallback: boolean;
+  enableCache: boolean;
   env: Record<string, string | undefined>;
+  warmupCommands: Array<{ method: string; params: unknown }>;
+}
+
+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 BridgeStats {
+  totalRequests: number;
+  totalTime: number;
+  cacheHits: number;
+  poolHits: number;
+  poolMisses: number;
+  processSpawns: number;
+  processDeaths: number;
+  memoryPeak: number;
+  averageTime: number;
+  cacheHitRate: number;
+}
+
+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;
+  }>;
 }
 
 function resolveDefaultScriptPath(): string {
@@ -83,19 +162,48 @@ function resolveVirtualEnv(
   return { venvPath, binDir, pythonPath };
 }
 
+/**
+ * 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.
+ *
+ * @example
+ * ```typescript
+ * // Single-process mode (default)
+ * const bridge = new NodeBridge();
+ *
+ * // Multi-process pooling for high throughput
+ * const pooledBridge = new NodeBridge({
+ *   minProcesses: 2,
+ *   maxProcesses: 8,
+ *   enableCache: true,
+ * });
+ * ```
+ */
 export class NodeBridge extends RuntimeBridge {
-  private child?: import('child_process').ChildProcess;
-  private nextId = 1;
-  private readonly pending = new Map<
-    number,
-    { resolve: (v: unknown) => void; reject: (e: unknown) => void; timer?: NodeJS.Timeout }
-  >();
-  private readonly options: ResolvedNodeBridgeOptions;
-  private stderrBuffer = '';
+  private processPool: WorkerProcess[] = [];
+  private roundRobinIndex = 0;
+  private cleanupTimer?: NodeJS.Timeout;
+  private options: ResolvedOptions;
+  private emitter = new EventEmitter();
   private disposed = false;
-  private protocolError = false;
-  private initPromise?: Promise<void>;
   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,
+  };
 
   constructor(options: NodeBridgeOptions = {}) {
     super();
@@ -105,32 +213,65 @@ export class NodeBridge extends RuntimeBridge {
     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,
       pythonPath: options.pythonPath ?? venv?.pythonPath ?? getDefaultPythonPath(),
       scriptPath: resolvedScriptPath,
       virtualEnv,
       cwd,
       timeoutMs: options.timeoutMs ?? 30000,
+      maxLineLength: options.maxLineLength,
+      inheritProcessEnv: options.inheritProcessEnv ?? false,
       enableJsonFallback: options.enableJsonFallback ?? false,
+      enableCache: options.enableCache ?? false,
       env: options.env ?? {},
+      warmupCommands: options.warmupCommands ?? [],
     };
+
+    // Start cleanup scheduler for pooled mode
+    this.startCleanupScheduler();
   }
 
   async init(): Promise<void> {
     if (this.disposed) {
       throw new BridgeDisposedError('Bridge has been disposed');
     }
-    if (this.child) {
-      return;
+    if (this.processPool.length >= this.options.minProcesses) {
+      return; // Already initialized
     }
     if (this.initPromise) {
       return this.initPromise;
     }
+    this.initPromise = this.doInit();
+    return this.initPromise;
+  }
+
+  private async doInit(): Promise<void> {
     // 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}`);
     }
-    this.initPromise = this.startProcess();
-    return this.initPromise;
+
+    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();
+    }
   }
 
   async getBridgeInfo(options: { refresh?: boolean } = {}): Promise<BridgeInfo> {
@@ -151,7 +292,42 @@ export class NodeBridge extends RuntimeBridge {
     kwargs?: Record<string, unknown>
   ): Promise<T> {
     await this.init();
-    return this.send<T>({ method: 'call', params: { module, functionName, args, kwargs } });
+    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;
+      }
+    }
+
+    try {
+      const result = await this.executeRequest<T>({
+        method: 'call',
+        params: { 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,
+          dependencies: [module],
+        });
+      }
+
+      this.updateStats(duration);
+      return result;
+    } catch (error) {
+      this.updateStats(performance.now() - startTime, true);
+      throw error;
+    }
   }
 
   async instantiate<T = unknown>(
@@ -161,7 +337,20 @@ export class NodeBridge extends RuntimeBridge {
     kwargs?: Record<string, unknown>
   ): Promise<T> {
     await this.init();
-    return this.send<T>({ method: 'instantiate', params: { module, className, args, kwargs } });
+    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>(
@@ -171,258 +360,541 @@ export class NodeBridge extends RuntimeBridge {
     kwargs?: Record<string, unknown>
   ): Promise<T> {
     await this.init();
-    return this.send<T>({ method: 'call_method', params: { handle, methodName, args, kwargs } });
+    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.send<void>({ method: 'dispose_instance', params: { handle } });
+    await this.executeRequest<void>({
+      method: 'dispose_instance',
+      params: { handle },
+    });
   }
 
-  async dispose(): Promise<void> {
-    this.disposed = true;
-    this.initPromise = undefined;
-    this.bridgeInfo = undefined;
-    if (!this.child) {
-      return;
+  /**
+   * 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}`);
+      }
     }
-    this.child.kill('SIGTERM');
-    this.child = undefined;
+
+    // Wait for worker if all are busy
+    worker ??= await this.waitForAvailableWorker();
+
+    this.stats.poolHits++;
+    return this.sendToWorker<T>(worker, payload);
   }
 
-  private async send<T>(payload: Omit<RpcRequest, 'id' | 'protocol'>): Promise<T> {
-    if (this.disposed) {
-      throw new BridgeDisposedError('Bridge has been disposed');
+  /**
+   * Select optimal worker based on load and performance
+   */
+  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;
     }
-    const id = this.nextId++;
-    const message: RpcRequest = { id, protocol: TYWRAP_PROTOCOL, ...payload } as RpcRequest;
-    const text = `${JSON.stringify(message)}\n`;
-    let timer: NodeJS.Timeout | undefined;
-    const promise = new Promise<T>((resolvePromise, reject) => {
-      timer = setTimeout(() => {
-        this.pending.delete(id);
-        const stderrTail = this.stderrBuffer.trim();
-        const msg = stderrTail
-          ? `Python call timed out. Recent stderr from Python:\n${stderrTail}`
-          : 'Python call timed out';
-        reject(new BridgeTimeoutError(msg));
-      }, this.options.timeoutMs);
-      const resolveWrapped = (v: unknown): void => {
-        resolvePromise(v as T);
+
+    // 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);
+        }
       };
-      this.pending.set(id, { resolve: resolveWrapped, reject, timer });
+
+      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 {
-      if (!this.child?.stdin) {
-        throw new BridgeProtocolError('Python process not available');
-      }
-      this.child.stdin.write(text);
-    } catch (err) {
-      this.pending.delete(id);
-      if (timer) {
-        clearTimeout(timer);
-      }
-      throw new BridgeProtocolError(`IPC failure: ${(err as Error).message}`);
+      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;
     }
-    return promise;
   }
 
-  private errorFrom(err: { type: string; message: string; traceback?: string }): Error {
-    const e = new BridgeExecutionError(`${err.type}: ${err.message}`);
-    e.traceback = err.traceback;
-    return e;
+  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),
+        });
+      });
   }
 
-  private handleProtocolError(details: string, line?: string): void {
-    if (this.protocolError) {
+  /**
+   * 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,
+      },
+    };
+
+    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
+   */
+  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);
+    });
+  }
+
+  /**
+   * Handle worker process exit
+   */
+  private handleWorkerExit(worker: WorkerProcess, _code: number | null): void {
+    if (!this.processPool.includes(worker)) {
       return;
     }
-    this.protocolError = true;
-    const snippet = line ? (line.length > 500 ? `${line.slice(0, 500)}…` : line) : undefined;
-    const hint =
-      'Ensure your Python code does not print to stdout and that the bridge outputs only JSON lines.';
-    const msg = snippet
-      ? `Protocol error from Python bridge. ${details}\n${hint}\nOffending line: ${snippet}`
-      : `Protocol error from Python bridge. ${details}\n${hint}`;
-    const error = new BridgeProtocolError(msg);
-    for (const [, p] of this.pending) {
-      p.reject(error);
-    }
-    this.pending.clear();
-    this.child?.kill('SIGTERM');
-    this.child = undefined;
-    this.initPromise = undefined;
-    this.bridgeInfo = undefined;
+
+    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 async startProcess(): Promise<void> {
-    try {
-      const { spawn } = await import('child_process');
-      const allowedPrefixes = ['TYWRAP_'];
-      const allowedKeys = new Set(['PATH', 'PYTHONPATH', 'VIRTUAL_ENV', 'PYTHONHOME']);
-      const baseEnv = new Map<string, string | undefined>();
-      for (const [k, v] of Object.entries(process.env)) {
-        if (allowedKeys.has(k) || allowedPrefixes.some(p => k.startsWith(p))) {
-          baseEnv.set(k, v);
+  /**
+   * Warm up processes with configured commands
+   */
+  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) });
         }
       }
-      const env: NodeJS.ProcessEnv = {
-        ...(Object.fromEntries(baseEnv) as NodeJS.ProcessEnv),
-        ...this.options.env,
-      };
-      if (this.options.virtualEnv) {
-        const venv = resolveVirtualEnv(this.options.virtualEnv, this.options.cwd);
-        env.VIRTUAL_ENV = venv.venvPath;
-        const currentPath = env.PATH ?? process.env.PATH ?? '';
-        env.PATH = `${venv.binDir}${delimiter}${currentPath}`;
-      }
-      if (!env.PYTHONUTF8) {
-        env.PYTHONUTF8 = '1';
-      }
-      if (!env.PYTHONIOENCODING) {
-        env.PYTHONIOENCODING = 'UTF-8';
+    });
+
+    await Promise.all(warmupPromises);
+  }
+
+  private safeCacheKey(prefix: string, ...inputs: unknown[]): string | null {
+    try {
+      return globalCache.generateKey(prefix, ...inputs);
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * 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,
+      /^(encode|decode|serialize|deserialize)_/i,
+    ];
+
+    const impureFunctionPatterns = [
+      /^(set|save|write|update|insert|delete|create|modify)_/i,
+      /^(send|post|put|patch)_/i,
+      /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;
+    }
+  }
+
+  /**
+   * 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;
+
+    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
+    );
+
+    for (const worker of idleWorkers) {
+      await this.terminateWorker(worker);
+    }
+
+    // Restart workers that have handled too many requests
+    const overusedWorkers = this.processPool.filter(
+      w => !w.busy && w.requestCount >= this.options.maxRequestsPerProcess
+    );
+
+    for (const worker of overusedWorkers) {
+      await this.terminateWorker(worker);
+      if (this.processPool.length < this.options.minProcesses) {
+        await this.spawnProcess();
       }
-      // Respect explicit request for JSON fallback only; otherwise fast-fail by default
-      if (this.options.enableJsonFallback && !env.TYWRAP_CODEC_FALLBACK) {
-        env.TYWRAP_CODEC_FALLBACK = 'json';
+    }
+  }
+
+  /**
+   * Gracefully terminate a worker
+   */
+  private async terminateWorker(
+    worker: WorkerProcess,
+    options: { force?: boolean } = {}
+  ): Promise<void> {
+    if (worker.busy && !options.force) {
+      return;
+    }
+
+    const index = this.processPool.indexOf(worker);
+    if (index >= 0) {
+      this.processPool.splice(index, 1);
+      this.stats.processDeaths++;
+    }
+
+    worker.core.handleProcessExit();
+    worker.core.clear();
+
+    // 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) });
+    }
+  }
 
-      let child: ReturnType<typeof spawn>;
+  /**
+   * Start cleanup scheduler
+   */
+  private startCleanupScheduler(): void {
+    this.cleanupTimer = setInterval(async () => {
       try {
-        child = spawn(this.options.pythonPath, [this.options.scriptPath], {
-          cwd: this.options.cwd,
-          stdio: ['pipe', 'pipe', 'pipe'],
-          env,
-        });
-      } catch (err) {
-        throw new BridgeProtocolError(`Failed to start Python process: ${(err as Error).message}`);
+        await this.cleanup();
+      } catch (error) {
+        log.error('Cleanup error', { error: String(error) });
       }
+    }, 60000); // Cleanup every minute
+  }
 
-      const startupError = await new Promise<Error | null>(done => {
-        child.once('error', e => done(e));
-        child.once('spawn', () => done(null));
-      });
-      if (startupError) {
-        throw new BridgeProtocolError(`Failed to start Python process: ${startupError.message}`);
-      }
+  /**
+   * Dispose all resources
+   */
+  async dispose(): Promise<void> {
+    if (this.disposed) {
+      return;
+    }
 
-      this.child = child;
-      this.protocolError = false;
+    this.disposed = true;
 
-      this.child?.on('error', err => {
-        const msg = `Python process error: ${err instanceof Error ? err.message : String(err)}`;
-        for (const [, p] of this.pending) {
-          p.reject(new BridgeProtocolError(msg));
-        }
-        this.pending.clear();
-        this.child = undefined;
-        this.initPromise = undefined;
-        this.bridgeInfo = undefined;
-      });
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = undefined;
+    }
 
-      let buffer = '';
-      this.child.stdout?.on('data', (chunk: Buffer): void => {
-        buffer += chunk.toString();
-        let idx: number;
-        while ((idx = buffer.indexOf('\n')) !== -1) {
-          const line = buffer.slice(0, idx);
-          buffer = buffer.slice(idx + 1);
-          if (!line.trim()) {
-            continue;
-          }
-          (async (): Promise<void> => {
-            try {
-              const msg = JSON.parse(line) as RpcResponse;
-              if (msg.protocol !== TYWRAP_PROTOCOL) {
-                this.handleProtocolError(
-                  `Invalid protocol. Expected ${TYWRAP_PROTOCOL} but received ${String(
-                    msg.protocol
-                  )}`,
-                  line
-                );
-                return;
-              }
-              if (typeof msg.id !== 'number') {
-                this.handleProtocolError('Invalid response id', line);
-                return;
-              }
-              const pending = this.pending.get(msg.id);
-              if (!pending) {
-                this.handleProtocolError(`Unexpected response id ${msg.id}`, line);
-                return;
-              }
-              this.pending.delete(msg.id);
-              if (pending.timer) {
-                clearTimeout(pending.timer);
-              }
-              if (msg.error) {
-                pending.reject(this.errorFrom(msg.error));
-              } else {
-                try {
-                  const decoded = await decodeValueAsync(msg.result);
-                  pending.resolve(decoded);
-                } catch (err) {
-                  pending.reject(
-                    new BridgeProtocolError(
-                      `Failed to decode Python response: ${
-                        err instanceof Error ? err.message : String(err)
-                      }`
-                    )
-                  );
-                }
-              }
-            } catch (err) {
-              const parseMessage = err instanceof Error ? err.message : String(err);
-              this.handleProtocolError(`Invalid JSON: ${parseMessage}`, line);
-            }
-          })().catch(() => {
-            /* ignore */
-          });
-        }
-      });
+    // Terminate all workers
+    const terminationPromises = this.processPool.map(worker =>
+      this.terminateWorker(worker, { force: true })
+    );
+    await Promise.all(terminationPromises);
 
-      this.child?.stderr?.on('data', (chunk: Buffer) => {
-        // Buffer stderr for better error diagnostics on failures/exits
-        try {
-          this.stderrBuffer += chunk.toString();
-          // Truncate to last 8KB to avoid unbounded growth
-          const MAX = 8 * 1024;
-          if (this.stderrBuffer.length > MAX) {
-            this.stderrBuffer = this.stderrBuffer.slice(this.stderrBuffer.length - MAX);
-          }
-        } catch {
-          // ignore
-        }
-      });
+    this.processPool.length = 0;
+    this.emitter.removeAllListeners();
+  }
 
-      this.child?.on('exit', () => {
-        for (const [, p] of this.pending) {
-          const stderrTail = this.stderrBuffer.trim();
-          const msg = stderrTail
-            ? `Python process exited. Stderr:\n${stderrTail}`
-            : 'Python process exited';
-          p.reject(new BridgeProtocolError(msg));
+  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;
+      }
+    } 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;
         }
-        this.pending.clear();
-        this.child = undefined;
-        this.initPromise = undefined;
-        this.bridgeInfo = undefined;
-      });
+      }
+    }
 
-      await this.refreshBridgeInfo();
-    } catch (err) {
-      this.child?.kill('SIGTERM');
-      this.child = undefined;
-      this.initPromise = undefined;
-      throw err;
+    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}`;
     }
+
+    ensurePythonEncoding(env);
+    ensureJsonFallback(env, this.options.enableJsonFallback);
+
+    env = normalizeEnv(env, {});
+    return env;
   }
 
   private async refreshBridgeInfo(): Promise<void> {
-    const info = await this.send<BridgeInfo>({ method: 'meta', params: {} });
-    if (info.protocol !== TYWRAP_PROTOCOL || info.protocolVersion !== TYWRAP_PROTOCOL_VERSION) {
-      throw new BridgeProtocolError('Invalid bridge info payload');
-    }
+    const info = await this.executeRequest<BridgeInfo>({ method: 'meta', params: {} });
+    validateBridgeInfo(info);
     this.bridgeInfo = info;
   }
 }
+
+/**
+ * @deprecated Use NodeBridge with minProcesses/maxProcesses options instead.
+ * This alias is provided for backward compatibility.
+ */
+export { NodeBridge as OptimizedNodeBridge };
+
+/**
+ * @deprecated Use NodeBridgeOptions instead.
+ */
+export type { NodeBridgeOptions as ProcessPoolOptions };