tywrap 0.5.1 → 0.6.1

package/src/runtime/{worker-pool.ts → transport-pool.ts}

@@ -1,5 +1,5 @@
 /**
- * WorkerPool - Manages multiple Transport instances for concurrent request handling.
+ * TransportPool - Manages multiple Transport instances for concurrent request handling.
  *
  * Provides semaphore-based concurrency control with configurable limits per worker
  * and a wait queue for callers when all workers are at capacity.
@@ -16,9 +16,9 @@ import type { Transport } from './transport.js';
 // =============================================================================
 
 /**
- * Configuration options for the WorkerPool.
+ * Configuration options for the TransportPool.
  */
-export interface WorkerPoolOptions {
+export interface TransportPoolOptions {
   /** Factory function to create transports */
   createTransport: () => Transport;
 
@@ -38,20 +38,20 @@ export interface WorkerPoolOptions {
    * Callback invoked after each worker is created and initialized.
    * Use this for per-worker warmup (e.g., importing modules, running setup).
    */
-  onWorkerReady?: (worker: PooledWorker) => Promise<void>;
+  onWorkerReady?: (worker: TransportLease) => Promise<void>;
 
   /**
    * Optional callback used only for background replacement workers after a
    * fatal timeout/crash. This lets callers publish a replacement only after it
    * is proven ready, without charging hidden work to normal request startup.
    */
-  onReplacementWorkerReady?: (worker: PooledWorker) => Promise<void>;
+  onReplacementWorkerReady?: (worker: TransportLease) => Promise<void>;
 }
 
 /**
  * A pooled worker with its transport and current in-flight request count.
  */
-export interface PooledWorker {
+export interface TransportLease {
   /** The underlying transport instance */
   transport: Transport;
 
@@ -64,7 +64,7 @@ export interface PooledWorker {
  */
 interface QueuedWaiter {
   /** Resolve function to fulfill the promise with a worker */
-  resolve: (worker: PooledWorker) => void;
+  resolve: (worker: TransportLease) => void;
 
   /** Reject function to reject the promise with an error */
   reject: (error: Error) => void;
@@ -88,8 +88,8 @@ interface QueuedWaiter {
  *
  * @example
  * ```typescript
- * const pool = new WorkerPool({
- *   createTransport: () => new ProcessIO({ pythonPath: 'python3' }),
+ * const pool = new TransportPool({
+ *   createTransport: () => new SubprocessTransport({ pythonPath: 'python3' }),
  *   maxWorkers: 4,
  *   maxConcurrentPerWorker: 2,
  *   queueTimeoutMs: 5000,
@@ -105,25 +105,25 @@ interface QueuedWaiter {
  * await pool.dispose();
  * ```
  */
-export class WorkerPool extends DisposableBase {
+export class TransportPool extends DisposableBase {
   private readonly options: Omit<
-    Required<WorkerPoolOptions>,
+    Required<TransportPoolOptions>,
     'onWorkerReady' | 'onReplacementWorkerReady'
   > & {
-    onWorkerReady?: (worker: PooledWorker) => Promise<void>;
-    onReplacementWorkerReady?: (worker: PooledWorker) => Promise<void>;
+    onWorkerReady?: (worker: TransportLease) => Promise<void>;
+    onReplacementWorkerReady?: (worker: TransportLease) => Promise<void>;
   };
-  private readonly workers: PooledWorker[] = [];
+  private readonly workers: TransportLease[] = [];
   private readonly waitQueue: QueuedWaiter[] = [];
   /** Tracks workers being created to prevent race condition in acquire() */
   private pendingCreations = 0;
 
   /**
-   * Create a new WorkerPool.
+   * Create a new TransportPool.
    *
    * @param options - Pool configuration options
    */
-  constructor(options: WorkerPoolOptions) {
+  constructor(options: TransportPoolOptions) {
     super();
 
     // Validate required options
@@ -216,7 +216,7 @@ export class WorkerPool extends DisposableBase {
    * @throws BridgeTimeoutError if queue timeout expires
    * @throws BridgeExecutionError if pool is disposed while waiting
    */
-  async acquire(): Promise<PooledWorker> {
+  async acquire(): Promise<TransportLease> {
     // Check for disposed state
     if (this.isDisposed || this.state === 'disposing') {
       throw new BridgeExecutionError('Pool has been disposed');
@@ -261,7 +261,7 @@ export class WorkerPool extends DisposableBase {
    *
    * @param worker - The worker to release
    */
-  release(worker: PooledWorker): void {
+  release(worker: TransportLease): void {
     // Validate the worker belongs to this pool
     if (!this.workers.includes(worker)) {
       return;
@@ -288,7 +288,7 @@ export class WorkerPool extends DisposableBase {
    * });
    * ```
    */
-  async withWorker<T>(fn: (worker: PooledWorker) => Promise<T>): Promise<T> {
+  async withWorker<T>(fn: (worker: TransportLease) => Promise<T>): Promise<T> {
     const worker = await this.acquire();
     let workerRemoved = false;
 
@@ -341,7 +341,7 @@ export class WorkerPool extends DisposableBase {
    * This is called when a worker is detected as dead (crashed, pipe error, etc.).
    * The worker's transport is disposed in the background.
    */
-  private removeWorker(worker: PooledWorker): void {
+  private removeWorker(worker: TransportLease): void {
     const index = this.workers.indexOf(worker);
     if (index !== -1) {
       this.workers.splice(index, 1);
@@ -387,7 +387,7 @@ export class WorkerPool extends DisposableBase {
   /**
    * Find an available worker with capacity for another request.
    */
-  private findAvailableWorker(): PooledWorker | undefined {
+  private findAvailableWorker(): TransportLease | undefined {
     return this.workers.find(w => w.inFlightCount < this.options.maxConcurrentPerWorker);
   }
 
@@ -452,7 +452,7 @@ export class WorkerPool extends DisposableBase {
     this.publishAvailableWorker(worker);
   }
 
-  private publishAvailableWorker(worker: PooledWorker): void {
+  private publishAvailableWorker(worker: TransportLease): void {
     while (
       this.waitQueue.length > 0 &&
       worker.inFlightCount < this.options.maxConcurrentPerWorker
@@ -473,13 +473,13 @@ export class WorkerPool extends DisposableBase {
    * If onWorkerReady is configured, calls it after the transport is initialized.
    * This is useful for per-worker warmup (importing modules, running setup).
    */
-  private async createWorker(onWorkerReady = this.options.onWorkerReady): Promise<PooledWorker> {
+  private async createWorker(onWorkerReady = this.options.onWorkerReady): Promise<TransportLease> {
     const transport = this.options.createTransport();
 
     // Initialize the transport
     await transport.init();
 
-    const worker: PooledWorker = {
+    const worker: TransportLease = {
       transport,
       inFlightCount: 0,
     };
@@ -512,8 +512,8 @@ export class WorkerPool extends DisposableBase {
   /**
    * Wait in queue for a worker to become available.
    */
-  private waitForWorker(): Promise<PooledWorker> {
-    return new Promise<PooledWorker>((resolve, reject) => {
+  private waitForWorker(): Promise<TransportLease> {
+    return new Promise<TransportLease>((resolve, reject) => {
       const timer = setTimeout(() => {
         // Remove this waiter from the queue
         const index = this.waitQueue.findIndex(w => w.timer === timer);

package/src/runtime/transport.ts

@@ -3,9 +3,9 @@
  *
  * Provides an abstract I/O channel for all bridge communications across
  * the JS-Python boundary. Concrete implementations handle different runtimes:
- * - ProcessIO: Child process with stdio streams (Node.js)
- * - HttpIO: HTTP POST requests (remote Python server)
- * - PyodideIO: In-memory Pyodide calls (browser/WASM)
+ * - SubprocessTransport: Child process with stdio streams (Node.js)
+ * - HttpTransport: HTTP POST requests (remote Python server)
+ * - PyodideTransport: In-memory Pyodide calls (browser/WASM)
  *
  * @see https://github.com/bbopen/tywrap/issues/149
  */
@@ -16,9 +16,16 @@ import type { Disposable } from './disposable.js';
 // PROTOCOL CONSTANTS
 // =============================================================================
 
-/** Protocol identifier for tywrap communication */
+/** Protocol identifier for tywrap communication. Single source of truth for the version. */
 export const PROTOCOL_ID = 'tywrap/1';
 
+/**
+ * Numeric protocol version negotiated with the Python bridge. Derived from the
+ * trailing number of {@link PROTOCOL_ID} so the two cannot drift — bump
+ * PROTOCOL_ID alone and this follows.
+ */
+export const TYWRAP_PROTOCOL_VERSION = Number.parseInt(PROTOCOL_ID.split('/')[1] ?? '', 10);
+
 // =============================================================================
 // PROTOCOL TYPES
 // =============================================================================
@@ -112,13 +119,13 @@ export interface ProtocolResponse {
  * 4. Call `dispose()` to release resources
  *
  * Implementations:
- * - ProcessIO: Spawns a Python child process, communicates via stdio
- * - HttpIO: Sends HTTP POST requests to a Python server
- * - PyodideIO: Calls Pyodide directly in-memory (WASM)
+ * - SubprocessTransport: Spawns a Python child process, communicates via stdio
+ * - HttpTransport: Sends HTTP POST requests to a Python server
+ * - PyodideTransport: Calls Pyodide directly in-memory (WASM)
  *
  * @example
  * ```typescript
- * const transport = new ProcessIO({ pythonPath: 'python3' });
+ * const transport = new SubprocessTransport({ pythonPath: 'python3' });
  * await transport.init();
  *
  * const response = await transport.send(

package/src/types/index.ts

@@ -310,7 +310,14 @@ export interface TywrapOptions {
 
 export interface PythonModuleConfig {
   version?: string;
-  runtime: RuntimeStrategy;
+  /**
+   * @deprecated Dead input. The per-module runtime is never read during code
+   * generation — the active runtime is resolved from the top-level
+   * {@link RuntimeConfig} (`runtime.node`, etc.). Kept optional so existing
+   * configs that still set it continue to validate; it has no effect and will
+   * be removed in a future major release.
+   */
+  runtime?: RuntimeStrategy;
   functions?: string[];
   classes?: string[];
   /** Exclude specific exports by exact name. */
@@ -343,11 +350,13 @@ export interface PyodideConfig {
 export interface NodeConfig {
   pythonPath?: string;
   virtualEnv?: string;
+  /** Per-call timeout in milliseconds for the subprocess bridge. */
   timeout?: number;
 }
 
 export interface HttpConfig {
   baseURL: string;
+  /** Per-request timeout in milliseconds for the HTTP bridge. */
   timeout?: number;
   headers?: Record<string, string>;
 }

package/src/tywrap.ts

@@ -52,30 +52,6 @@ export async function tywrap(options: Partial<TywrapOptions> = {}): Promise<Tywr
   };
 }
 
-export default tywrap;
-
-/**
- * Append minimal tsd tests for a generated module (optional dev aid)
- */
-export async function emitTypeTestsForModule(
-  moduleName: string,
-  outDir = 'test-d/generated'
-): Promise<void> {
-  const { writeFile, mkdir } = await import('fs/promises');
-  const { join } = await import('path');
-  try {
-    await mkdir(outDir, { recursive: true });
-  } catch {}
-  const filePath = join(outDir, `${moduleName}.test-d.ts`);
-  const content = `import { expectType } from 'tsd';
-import * as mod from '../../generated/${moduleName}.generated.ts';
-
-// Opportunistic: ensure module namespace is an object
-expectType<Record<string, unknown>>(mod);
-`;
-  await writeFile(filePath, content, 'utf-8');
-}
-
 export interface GenerateRunOptions {
   /**
    * If true, do not write files; instead compare generated output to what's on disk.

package/src/utils/cache.ts

@@ -47,7 +47,7 @@ export interface CacheConfig {
   debug?: boolean;
 }
 
-export class IntelligentCache {
+export class ArtifactCache {
   private memoryCache = new Map<string, CacheEntry>();
   private stats = {
     hits: 0,
@@ -149,75 +149,73 @@ export class IntelligentCache {
     hash.update(prefix);
     hash.update('\0');
 
-    // Add inputs
+    // Add inputs. Each input contributes a type tag, an optional payload, and a
+    // boundary separator so that "1" vs 1 and ["a","bc"] vs ["ab","c"] never collide.
     for (const input of inputs) {
-      // Why: disambiguate types so "1" and 1 don't collide, and keep input boundaries so
-      // ["a", "bc"] doesn't collide with ["ab", "c"].
-      if (input === undefined) {
-        hash.update('undef:');
-        hash.update('\0');
-        continue;
+      const { tag, payload } = ArtifactCache.encodeKeyInput(input);
+      hash.update(tag);
+      if (payload !== undefined) {
+        hash.update(payload);
       }
-      if (input === null) {
-        hash.update('null:');
-        hash.update('\0');
-        continue;
-      }
-      if (typeof input === 'string') {
-        hash.update('str:');
-        hash.update(input);
-        hash.update('\0');
-        continue;
-      }
-      if (typeof input === 'number') {
-        hash.update('num:');
-        hash.update(String(input));
-        hash.update('\0');
-        continue;
-      }
-      if (typeof input === 'boolean') {
-        hash.update('bool:');
-        hash.update(input ? '1' : '0');
-        hash.update('\0');
-        continue;
-      }
-      if (typeof input === 'bigint') {
-        hash.update('bigint:');
-        hash.update(input.toString());
-        hash.update('\0');
-        continue;
-      }
-      if (Buffer.isBuffer(input)) {
-        hash.update('buf:');
-        hash.update(input);
-        hash.update('\0');
-        continue;
-      }
-
-      if (typeof input === 'symbol') {
-        hash.update('sym:');
-        hash.update(input.toString());
-        hash.update('\0');
-        continue;
-      }
-
-      hash.update('json:');
-      let json: string;
-      try {
-        json =
-          JSON.stringify(input, (_key, value) =>
-            typeof value === 'symbol' ? value.toString() : value
-          ) ?? 'undefined';
-      } catch {
-        json = String(input);
-      }
-      hash.update(json);
       hash.update('\0');
     }
 
     return hash.digest('hex').substring(0, 16); // Use first 16 chars for readability
   }
 
+  /**
+   * Encode a single key input as a type tag plus optional payload.
+   * Why: disambiguate types so "1" and 1 don't collide, and keep input boundaries so
+   * ["a", "bc"] doesn't collide with ["ab", "c"].
+   */
+  private static encodeKeyInput(input: unknown): {
+    tag: string;
+    payload?: string | Buffer;
+  } {
+    if (input === undefined) {
+      return { tag: 'undef:' };
+    }
+    if (input === null) {
+      return { tag: 'null:' };
+    }
+    if (typeof input === 'string') {
+      return { tag: 'str:', payload: input };
+    }
+    if (typeof input === 'number') {
+      return { tag: 'num:', payload: String(input) };
+    }
+    if (typeof input === 'boolean') {
+      return { tag: 'bool:', payload: input ? '1' : '0' };
+    }
+    if (typeof input === 'bigint') {
+      return { tag: 'bigint:', payload: input.toString() };
+    }
+    if (Buffer.isBuffer(input)) {
+      return { tag: 'buf:', payload: input };
+    }
+    if (typeof input === 'symbol') {
+      return { tag: 'sym:', payload: input.toString() };
+    }
+
+    return { tag: 'json:', payload: ArtifactCache.stringifyKeyInput(input) };
+  }
+
+  /**
+   * Stringify an arbitrary key input for hashing, normalizing symbols and
+   * falling back to String() when JSON serialization fails.
+   */
+  private static stringifyKeyInput(input: unknown): string {
+    try {
+      return (
+        JSON.stringify(input, (_key, value) =>
+          typeof value === 'symbol' ? value.toString() : value
+        ) ?? 'undefined'
+      );
+    } catch {
+      return String(input);
+    }
+  }
+
   /**
    * Get entry from cache with performance tracking
    */
@@ -685,4 +683,4 @@ export class IntelligentCache {
 }
 
 // Export singleton instance
-export const globalCache = new IntelligentCache();
+export const globalCache = new ArtifactCache();