tywrap 0.2.0 → 0.3.0

package/dist/runtime/node.js

@@ -1,26 +1,31 @@
 /**
- * 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 { 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 { RuntimeBridge } from './base.js';
-import { BridgeDisposedError, BridgeProtocolError } from './errors.js';
-import { BridgeCore, 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 } from './bridge-protocol.js';
+import { BridgeExecutionError, BridgeProtocolError } from './errors.js';
+import { ProcessIO } from './process-io.js';
+import { PooledTransport } from './pooled-transport.js';
+import { PROTOCOL_ID } from './transport.js';
+const WORKER_READY_TIMEOUT_MS = 5000;
+// =============================================================================
+// UTILITIES
+// =============================================================================
+/**
+ * Resolve the default bridge script path.
+ */
 function resolveDefaultScriptPath() {
     try {
         return fileURLToPath(new URL('../../runtime/python_bridge.py', import.meta.url));
@@ -29,429 +34,296 @@ function resolveDefaultScriptPath() {
         return 'runtime/python_bridge.py';
     }
 }
+/**
+ * Resolve virtual environment paths.
+ */
 function resolveVirtualEnv(virtualEnv, cwd) {
     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) {
+    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, value) {
+    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() {
+    return Object.create(null);
+}
+function setEnvValue(env, key, value) {
+    Object.defineProperty(env, key, {
+        value,
+        writable: true,
+        enumerable: true,
+        configurable: true,
+    });
+}
+function getEnvValue(env, key) {
+    const value = Reflect.get(env, key);
+    return typeof value === 'string' ? value : undefined;
+}
+function assertSafeEnvOverrideKey(key) {
+    if (DANGEROUS_ENV_OVERRIDE_KEYS.has(key)) {
+        throw new BridgeProtocolError(`Invalid environment override key "${key}" in options.env`);
+    }
+}
+function normalizeWarmupCommands(commands) {
+    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;
+        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,
+        };
+    });
+}
+// =============================================================================
+// 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 {
-    processPool = [];
-    roundRobinIndex = 0;
-    cleanupTimer;
-    options;
-    emitter = new EventEmitter();
-    disposed = false;
-    bridgeInfo;
-    initPromise;
-    // Performance monitoring
-    stats = {
-        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 {
+    resolvedOptions;
+    pooledTransport;
+    /**
+     * Create a new NodeBridge instance.
+     *
+     * @param options - Configuration options for the bridge
+     */
     constructor(options = {}) {
-        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 = {
+            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();
-    }
-    async init() {
-        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;
+        // 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: () => 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,
+        });
+        // Initialize BridgeProtocol with pooled transport
+        const protocolOptions = {
+            transport,
+            codec: resolvedOptions.codec,
+            defaultTimeoutMs: resolvedOptions.timeoutMs,
+        };
+        super(protocolOptions);
+        this.resolvedOptions = resolvedOptions;
+        this.pooledTransport = transport;
     }
+    // ===========================================================================
+    // LIFECYCLE
+    // ===========================================================================
+    /**
+     * Initialize the bridge.
+     *
+     * Validates the bridge script exists, registers Arrow decoder,
+     * and initializes the transport pool (which runs warmup commands per-worker).
+     */
     async doInit() {
+        // 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();
-        }
-    }
-    async getBridgeInfo(options = {}) {
-        await this.init();
-        if (!this.bridgeInfo || options.refresh) {
-            await this.refreshBridgeInfo();
-        }
-        if (!this.bridgeInfo) {
-            throw new BridgeProtocolError('Bridge info unavailable');
-        }
-        return this.bridgeInfo;
+        // Initialize parent (which initializes transport and runs warmup per-worker)
+        await super.doInit();
     }
+    // ===========================================================================
+    // CACHING OVERRIDE
+    // ===========================================================================
+    /**
+     * Override call() to add optional caching.
+     */
     async call(module, functionName, args, kwargs) {
-        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(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(cacheKey);
+                if (cached !== null) {
+                    return cached;
+                }
             }
-        }
-        try {
-            const result = await this.executeRequest({
-                method: 'call',
-                params: { module, functionName, args, kwargs },
-            });
+            // Execute and cache if pure function
+            const startTime = performance.now();
+            const result = await super.call(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(module, className, args, kwargs) {
-        await this.init();
-        const startTime = performance.now();
-        try {
-            const result = await this.executeRequest({
-                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(handle, methodName, args, kwargs) {
-        await this.init();
-        const startTime = performance.now();
-        try {
-            const result = await this.executeRequest({
-                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) {
-        await this.init();
-        await this.executeRequest({
-            method: 'dispose_instance',
-            params: { handle },
-        });
+        // No caching - direct call
+        return super.call(module, functionName, args, kwargs);
     }
+    // ===========================================================================
+    // POOL STATISTICS
+    // ===========================================================================
     /**
-     * Execute request with intelligent process selection
+     * Get current pool statistics.
      */
-    async executeRequest(payload) {
-        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(worker, payload);
-    }
-    /**
-     * Select optimal worker based on load and performance
-     */
-    selectOptimalWorker() {
-        // 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
-     */
-    async waitForAvailableWorker(timeoutMs = 5000) {
-        return new Promise((resolvePromise, reject) => {
-            const timeout = setTimeout(() => {
-                reject(new Error('Timeout waiting for available worker'));
-            }, timeoutMs);
-            const checkWorker = () => {
-                const worker = this.selectOptimalWorker();
-                if (worker) {
-                    clearTimeout(timeout);
-                    resolvePromise(worker);
-                }
-                else {
-                    // Check again in 10ms
-                    setTimeout(checkWorker, 10);
-                }
-            };
-            checkWorker();
-        });
-    }
-    /**
-     * Send request to specific worker
-     */
-    async sendToWorker(worker, payload) {
-        worker.busy = true;
-        worker.requestCount++;
-        worker.lastUsed = Date.now();
-        const startTime = performance.now();
-        try {
-            const result = await worker.core.send(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;
-        }
-    }
-    quarantineWorker(worker, error) {
-        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
-     */
-    async spawnProcess() {
-        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 = {
-            process: childProcess,
-            id: workerId,
-            requestCount: 0,
-            lastUsed: Date.now(),
-            busy: false,
-            quarantined: false,
-            core: null,
-            stats: {
-                totalRequests: 0,
-                totalTime: 0,
-                averageTime: 0,
-                errorCount: 0,
-            },
+    getPoolStats() {
+        return {
+            workerCount: this.pooledTransport.workerCount,
+            queueLength: this.pooledTransport.queueLength,
+            totalInFlight: this.pooledTransport.totalInFlight,
         };
-        worker.core = new BridgeCore({
-            write: (data) => {
-                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) => this.quarantineWorker(worker, error),
-            onTimeout: (error) => 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
-     */
-    setupProcessHandlers(worker) {
-        const childProcess = worker.process;
-        childProcess.stdout?.on('data', (chunk) => {
-            worker.core.handleStdoutData(chunk);
-        });
-        childProcess.stderr?.on('data', (chunk) => {
-            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
+     * Get bridge statistics.
+     *
+     * @deprecated Use getPoolStats() instead. This method is provided for
+     * backwards compatibility and returns a subset of the previous stats.
      */
-    handleWorkerExit(worker, _code) {
-        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) });
-            });
-        }
+    getStats() {
+        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,
+        };
     }
+    // ===========================================================================
+    // PRIVATE HELPERS
+    // ===========================================================================
     /**
-     * Warm up processes with configured commands
+     * Generate a cache key, returning null if generation fails.
      */
-    async warmupProcesses() {
-        const warmupPromises = this.processPool.map(async (worker) => {
-            for (const cmd of this.options.warmupCommands) {
-                try {
-                    await this.sendToWorker(worker, {
-                        method: cmd.method,
-                        params: cmd.params,
-                    });
-                }
-                catch (error) {
-                    log.warn('Warmup command failed', { workerId: worker.id, error: String(error) });
-                }
-            }
-        });
-        await Promise.all(warmupPromises);
-    }
     safeCacheKey(prefix, ...inputs) {
         try {
             return globalCache.generateKey(prefix, ...inputs);
@@ -461,10 +333,9 @@ export class NodeBridge extends RuntimeBridge {
         }
     }
     /**
-     * Heuristic to determine if function result should be cached
+     * Heuristic to determine if function result should be cached.
      */
     isPureFunctionCandidate(functionName, args) {
-        // Simple heuristics - could be made more sophisticated
         const pureFunctionPatterns = [
             /^(get|fetch|read|load|find|search|query|select)_/i,
             /^(compute|calculate|process|transform|convert)_/i,
@@ -475,176 +346,176 @@ export class NodeBridge extends RuntimeBridge {
             /^(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
+        return !hasComplexArgs && args.length <= 3;
     }
-    /**
-     * Update performance statistics
-     */
-    updateStats(duration, _error = false) {
-        this.stats.totalRequests++;
-        this.stats.totalTime += duration;
-        const currentMemory = process.memoryUsage().heapUsed;
-        if (currentMemory > this.stats.memoryPeak) {
-            this.stats.memoryPeak = currentMemory;
+}
+// =============================================================================
+// WARMUP CALLBACK
+// =============================================================================
+/**
+ * Simple request ID generator for warmup commands.
+ */
+let warmupRequestId = 0;
+function generateWarmupId() {
+    return ++warmupRequestId;
+}
+/**
+ * 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, timeoutMs) {
+    return async (worker) => {
+        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',
+            });
         }
+    };
+}
+function createWorkerReadyCallback(timeoutMs, extraWarmup) {
+    return async (worker) => {
+        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',
+        });
+        if (result !== 0) {
+            throw new BridgeExecutionError(`Worker readiness probe (builtins.len) returned unexpected result: ${JSON.stringify(result)}`);
+        }
+        await extraWarmup?.(worker);
+    };
+}
+async function executeWorkerCall(worker, request, timeoutMs, messages) {
+    const requestId = generateWarmupId();
+    let message;
+    try {
+        message = JSON.stringify({
+            id: requestId,
+            protocol: PROTOCOL_ID,
+            method: 'call',
+            params: {
+                module: request.module,
+                functionName: request.functionName,
+                args: request.args,
+                kwargs: {},
+            },
+        });
     }
-    /**
-     * Get performance statistics
-     */
-    getStats() {
-        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(),
-            })),
-        };
+    catch (error) {
+        throw new BridgeExecutionError(`${messages.label} failed to encode request: ${error instanceof Error ? error.message : String(error)}`, { cause: error instanceof Error ? error : undefined });
     }
-    /**
-     * Cleanup idle processes
-     */
-    async cleanup() {
-        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();
-            }
-        }
+    let response;
+    try {
+        response = await worker.transport.send(message, timeoutMs);
     }
-    /**
-     * Gracefully terminate a worker
-     */
-    async terminateWorker(worker, options = {}) {
-        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) });
-        }
+    catch (error) {
+        throw new BridgeExecutionError(`${messages.label} failed to send: ${error instanceof Error ? error.message : String(error)}`, { cause: error instanceof Error ? error : undefined });
     }
-    /**
-     * Start cleanup scheduler
-     */
-    startCleanupScheduler() {
-        this.cleanupTimer = setInterval(async () => {
-            try {
-                await this.cleanup();
-            }
-            catch (error) {
-                log.error('Cleanup error', { error: String(error) });
-            }
-        }, 60000); // Cleanup every minute
+    let parsed;
+    try {
+        parsed = JSON.parse(response);
     }
-    /**
-     * Dispose all resources
-     */
-    async dispose() {
-        if (this.disposed) {
-            return;
-        }
-        this.disposed = true;
-        if (this.cleanupTimer) {
-            clearInterval(this.cleanupTimer);
-            this.cleanupTimer = undefined;
-        }
-        // Terminate all workers
-        const terminationPromises = this.processPool.map(worker => this.terminateWorker(worker, { force: true }));
-        await Promise.all(terminationPromises);
-        this.processPool.length = 0;
-        this.emitter.removeAllListeners();
+    catch (error) {
+        throw new BridgeExecutionError(`${messages.label} ${messages.invalidJsonMessage}`, {
+            cause: error instanceof Error ? error : undefined,
+        });
     }
-    buildEnv() {
-        const allowedPrefixes = ['TYWRAP_'];
-        const allowedKeys = new Set(['path', 'pythonpath', 'virtual_env', 'pythonhome']);
-        const baseEnv = {};
-        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;
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new BridgeExecutionError(`${messages.label} ${messages.malformedEnvelopeMessage(requestId)}`);
+    }
+    const envelope = parsed;
+    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;
+            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)}`);
+        }
+        throw new BridgeExecutionError(`${messages.label} ${messages.malformedErrorPayloadMessage}`);
+    }
+    if (!('result' in envelope)) {
+        throw new BridgeExecutionError(`${messages.label} ${messages.malformedEnvelopeMessage(requestId)}`);
+    }
+    return envelope.result;
+}
+// =============================================================================
+// ENVIRONMENT BUILDING
+// =============================================================================
+/**
+ * Build environment variables for ProcessIO.
+ */
+function buildProcessEnv(options) {
+    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;
     }
-    async refreshBridgeInfo() {
-        const info = await this.executeRequest({ method: 'meta', params: {} });
-        validateBridgeInfo(info);
-        this.bridgeInfo = info;
+    // 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);
     }
+    // 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;
+    }
+    // Ensure Python uses UTF-8
+    env.PYTHONUTF8 = '1';
+    env.PYTHONIOENCODING = 'UTF-8';
+    env.PYTHONUNBUFFERED = '1';
+    env.PYTHONDONTWRITEBYTECODE = '1';
+    return env;
 }
-/**
- * @deprecated Use NodeBridge with minProcesses/maxProcesses options instead.
- * This alias is provided for backward compatibility.
- */
-export { NodeBridge as OptimizedNodeBridge };
 //# sourceMappingURL=node.js.map