tywrap 0.3.0 → 0.4.0

package/src/index.ts

@@ -121,7 +121,6 @@ export type {
   NodeConfig,
   HttpConfig,
   PerformanceConfig,
-  DevelopmentConfig,
   TypeMappingConfig,
   TypePreset,
   BridgeInfo,
@@ -135,6 +134,7 @@ export type {
 // Main API
 export { tywrap } from './tywrap.js';
 export { generate } from './tywrap.js';
+export type { GenerateFailure, GenerateResult, GenerateRunOptions } from './tywrap.js';
 
 // Runtime detection utilities
 export { detectRuntime, isNodejs, isDeno, isBun, isBrowser } from './utils/runtime.js';

package/src/runtime/node.ts

@@ -340,16 +340,14 @@ export class NodeBridge extends BridgeProtocol {
       codec: options.codec,
       warmupCommands,
     };
-
     // 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);
+    const onWorkerReady = createWorkerReadyCallback(resolvedOptions.timeoutMs, userWarmup);
 
     // Create pooled transport with ProcessIO workers
     const transport = new PooledTransport({
@@ -364,8 +362,8 @@ export class NodeBridge extends BridgeProtocol {
       minWorkers: resolvedOptions.minProcesses,
       queueTimeoutMs: resolvedOptions.queueTimeoutMs,
       maxConcurrentPerWorker: resolvedOptions.maxConcurrentPerProcess,
-      onWorkerReady: userWarmup,
-      onReplacementWorkerReady: replacementWorkerReady,
+      onWorkerReady,
+      onReplacementWorkerReady: onWorkerReady,
     });
 
     // Initialize BridgeProtocol with pooled transport
@@ -565,6 +563,72 @@ function generateWarmupId(): number {
   return ++warmupRequestId;
 }
 
+async function sendWarmupRequest(
+  worker: PooledWorker,
+  timeoutMs: number,
+  requestId: number,
+  label: string,
+  messagePayload: Record<string, unknown>
+): Promise<void> {
+  let message: string;
+  try {
+    message = JSON.stringify({
+      id: requestId,
+      protocol: PROTOCOL_ID,
+      ...messagePayload,
+    });
+  } catch (error) {
+    throw new BridgeExecutionError(
+      `${label} failed to encode request: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error instanceof Error ? error : undefined }
+    );
+  }
+
+  let response: string;
+  try {
+    response = await worker.transport.send(message, timeoutMs);
+  } catch (error) {
+    throw new BridgeExecutionError(
+      `${label} failed to send: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error instanceof Error ? error : undefined }
+    );
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(response);
+  } catch (error) {
+    throw new BridgeExecutionError(`${label} returned invalid JSON response`, {
+      cause: error instanceof Error ? error : undefined,
+    });
+  }
+
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new BridgeExecutionError(
+      `${label} returned malformed response envelope for request ${requestId}`
+    );
+  }
+
+  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 warmup error';
+      throw new BridgeExecutionError(`${label} failed: ${errType}: ${errMessage}`);
+    }
+
+    throw new BridgeExecutionError(`${label} failed with malformed error payload`);
+  }
+
+  if (!('result' in envelope)) {
+    throw new BridgeExecutionError(
+      `${label} returned malformed response envelope for request ${requestId}`
+    );
+  }
+}
+
 /**
  * Create a callback that runs warmup commands on each worker.
  *
@@ -604,29 +668,11 @@ function createWorkerReadyCallback(
   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',
-      }
-    );
-
-    if (result !== 0) {
-      throw new BridgeExecutionError(
-        `Worker readiness probe (builtins.len) returned unexpected result: ${JSON.stringify(result)}`
-      );
-    }
+    const readyTimeoutMs = timeoutMs > 0 ? Math.max(timeoutMs, WORKER_READY_TIMEOUT_MS) : 0;
+    await sendWarmupRequest(worker, readyTimeoutMs, generateWarmupId(), 'Worker warmup check', {
+      method: 'meta',
+      params: {},
+    });
 
     await extraWarmup?.(worker);
   };

package/src/runtime/optimized-node.ts

@@ -1,9 +1,9 @@
 /**
  * @deprecated Import from './node.js' instead.
  *
- * OptimizedNodeBridge has been unified with NodeBridge. The NodeBridge class
- * now supports both single-process mode (default) and multi-process pooling
- * via the minProcesses/maxProcesses options.
+ * Backward-compat shim for older deep imports. NodeBridge is the public API,
+ * and it now supports both single-process mode (default) and multi-process
+ * pooling via the minProcesses/maxProcesses options.
  *
  * Migration:
  * ```typescript
@@ -16,7 +16,8 @@
  * const bridge = new NodeBridge({ minProcesses: 2, maxProcesses: 4 });
  * ```
  *
- * This file is maintained for backward compatibility only.
+ * This file is not exposed through the package exports map and is maintained
+ * for backward compatibility only.
  */
 export {
   NodeBridge as OptimizedNodeBridge,

package/src/runtime/worker-pool.ts

@@ -162,13 +162,7 @@ export class WorkerPool extends BoundedContext {
    */
   protected async doInit(): Promise<void> {
     // Pre-spawn minimum workers if configured
-    if (this.options.minWorkers > 0) {
-      const spawns: Promise<PooledWorker>[] = [];
-      for (let i = 0; i < this.options.minWorkers; i++) {
-        spawns.push(this.createWorker());
-      }
-      await Promise.all(spawns);
-    }
+    await this.fillToMinimumWorkers();
   }
 
   /**
@@ -224,7 +218,7 @@ export class WorkerPool extends BoundedContext {
    */
   async acquire(): Promise<PooledWorker> {
     // Check for disposed state
-    if (this.isDisposed) {
+    if (this.isDisposed || this.state === 'disposing') {
       throw new BridgeExecutionError('Pool has been disposed');
     }
 
@@ -243,7 +237,12 @@ export class WorkerPool extends BoundedContext {
       this.pendingCreations++;
       try {
         const newWorker = await this.createWorker();
+        if (this.isShuttingDown()) {
+          this.removeWorker(newWorker);
+          throw new BridgeExecutionError('Pool has been disposed');
+        }
         newWorker.inFlightCount++;
+        this.publishAvailableWorker(newWorker);
         return newWorker;
       } finally {
         this.pendingCreations--;
@@ -270,16 +269,7 @@ export class WorkerPool extends BoundedContext {
 
     // Decrement in-flight count (minimum 0)
     worker.inFlightCount = Math.max(0, worker.inFlightCount - 1);
-
-    // If there are waiters and this worker has capacity, fulfill the first waiter
-    if (this.waitQueue.length > 0 && worker.inFlightCount < this.options.maxConcurrentPerWorker) {
-      const waiter = this.waitQueue.shift();
-      if (waiter) {
-        clearTimeout(waiter.timer);
-        worker.inFlightCount++;
-        waiter.resolve(worker);
-      }
-    }
+    this.publishAvailableWorker(worker);
   }
 
   /**
@@ -331,14 +321,8 @@ export class WorkerPool extends BoundedContext {
    * - Process exited unexpectedly
    * - Pipe errors (EPIPE)
    * - Connection reset errors (ECONNRESET)
-   * - Request timeouts (the worker may still be busy with an uncancellable request)
    */
   private isFatalWorkerError(error: unknown): boolean {
-    // If a request times out, the underlying transport may still be executing it.
-    // Quarantine this worker so subsequent requests don't get stuck behind it.
-    if (error instanceof BridgeTimeoutError) {
-      return true;
-    }
     if (error instanceof BridgeProtocolError) {
       const msg = error.message.toLowerCase();
       return (
@@ -365,7 +349,9 @@ export class WorkerPool extends BoundedContext {
       worker.transport.dispose().catch(() => {
         // Ignore disposal errors for dead workers
       });
-      this.scheduleReplacementWorker();
+      if (this.state === 'ready') {
+        this.scheduleReplacementWorker();
+      }
     }
   }
 
@@ -405,6 +391,30 @@ export class WorkerPool extends BoundedContext {
     return this.workers.find(w => w.inFlightCount < this.options.maxConcurrentPerWorker);
   }
 
+  private getMinimumWorkerDeficit(): number {
+    return Math.max(0, this.options.minWorkers - (this.workers.length + this.pendingCreations));
+  }
+
+  private isShuttingDown(): boolean {
+    return this.isDisposed || this.state === 'disposing';
+  }
+
+  private async fillToMinimumWorkers(): Promise<void> {
+    await this.spawnWorkers(this.getMinimumWorkerDeficit());
+  }
+
+  private async spawnWorkers(count: number): Promise<void> {
+    if (count === 0) {
+      return;
+    }
+    this.pendingCreations += count;
+    try {
+      await Promise.all(Array.from({ length: count }, () => this.spawnWorkerToPool()));
+    } finally {
+      this.pendingCreations = Math.max(0, this.pendingCreations - count);
+    }
+  }
+
   /**
    * Replace a removed worker in the background so the next caller does not pay
    * the full worker cold-start penalty after a timeout or crash.
@@ -419,11 +429,7 @@ export class WorkerPool extends BoundedContext {
 
     this.pendingCreations++;
     const replacementReady = this.options.onReplacementWorkerReady ?? this.options.onWorkerReady;
-    this.createWorker(replacementReady)
-      .then(worker => {
-        // Reuse release() to wake queued callers if one is waiting.
-        this.release(worker);
-      })
+    this.spawnWorkerToPool(replacementReady)
       .catch(() => {
         // Ignore background replacement failures. A later acquire() can retry.
       })
@@ -432,6 +438,35 @@ export class WorkerPool extends BoundedContext {
       });
   }
 
+  private async spawnWorkerToPool(onWorkerReady = this.options.onWorkerReady): Promise<void> {
+    if (this.isShuttingDown()) {
+      return;
+    }
+
+    const worker = await this.createWorker(onWorkerReady);
+    if (this.isShuttingDown()) {
+      this.removeWorker(worker);
+      return;
+    }
+
+    this.publishAvailableWorker(worker);
+  }
+
+  private publishAvailableWorker(worker: PooledWorker): void {
+    while (
+      this.waitQueue.length > 0 &&
+      worker.inFlightCount < this.options.maxConcurrentPerWorker
+    ) {
+      const waiter = this.waitQueue.shift();
+      if (!waiter) {
+        return;
+      }
+      clearTimeout(waiter.timer);
+      worker.inFlightCount++;
+      waiter.resolve(worker);
+    }
+  }
+
   /**
    * Create a new worker and add it to the pool.
    *

package/src/types/index.ts

@@ -304,7 +304,6 @@ export interface TywrapOptions {
   output: OutputConfig;
   runtime: RuntimeConfig;
   performance: PerformanceConfig;
-  development: DevelopmentConfig;
   types?: TypeMappingConfig;
   debug?: boolean;
 }
@@ -320,7 +319,6 @@ export interface PythonModuleConfig {
   excludePatterns?: string[];
   alias?: string;
   typeHints: 'strict' | 'loose' | 'ignore';
-  watch?: boolean;
 }
 
 export interface OutputConfig {
@@ -360,12 +358,6 @@ export interface PerformanceConfig {
   compression: 'auto' | 'gzip' | 'brotli' | 'none';
 }
 
-export interface DevelopmentConfig {
-  hotReload: boolean;
-  sourceMap: boolean;
-  validation: 'runtime' | 'compile' | 'both' | 'none';
-}
-
 export type TypePreset = 'numpy' | 'pandas' | 'pydantic' | 'stdlib' | 'scipy' | 'torch' | 'sklearn';
 
 export interface TypeMappingConfig {

package/src/tywrap.ts

@@ -86,9 +86,16 @@ export interface GenerateRunOptions {
   check?: boolean;
 }
 
+export interface GenerateFailure {
+  module: string;
+  code: 'ir-unavailable';
+  message: string;
+}
+
 export interface GenerateResult {
   written: string[];
   warnings: string[];
+  failures: GenerateFailure[];
   /**
    * Only set when `GenerateRunOptions.check === true`.
    * Lists files that are missing or differ from what would be generated.
@@ -123,6 +130,7 @@ export async function generate(
   const written: string[] = [];
   const outOfDate: string[] = [];
   const warnings: string[] = [];
+  const failures: GenerateFailure[] = [];
   const outputDir = resolvedOptions.output.dir;
   const caching = resolvedOptions.performance.caching;
   const cacheDir = '.tywrap/cache';
@@ -173,7 +181,13 @@ export async function generate(
       }
     }
     if (!ir) {
-      warnings.push(`No IR produced for module ${moduleKey}${irError ? `: ${irError}` : ''}`);
+      const message = `No IR produced for module ${moduleKey}${irError ? `: ${irError}` : ''}`;
+      warnings.push(message);
+      failures.push({
+        module: moduleKey,
+        code: 'ir-unavailable',
+        message,
+      });
       continue;
     }
 
@@ -324,10 +338,10 @@ export async function generate(
   }
 
   if (checkMode) {
-    return { written: [], warnings, outOfDate };
+    return { written: [], warnings, failures, outOfDate };
   }
 
-  return { written, warnings };
+  return { written, warnings, failures };
 }
 
 /**