tywrap 0.4.0 → 0.5.1

package/src/runtime/{bridge-protocol.ts → rpc-client.ts}

@@ -1,24 +1,26 @@
 /**
- * BridgeProtocol - Unified abstraction for JS<->Python communication.
+ * RpcClient - the single correlated-RPC client for JS<->Python communication.
  *
- * Combines BoundedContext + SafeCodec + Transport into a single base class
- * that handles all cross-boundary concerns:
- * - Lifecycle management (init/dispose state machine)
- * - Request/response encoding with validation
- * - Transport-agnostic message passing
- * - Bounded execution (timeout, retry, abort)
+ * It HOLDS a Transport and a codec (SafeCodec) and is, in turn, HELD by the
+ * bridge facades (NodeBridge/HttpBridge/PyodideBridge) via composition — it is
+ * NOT a base class bridges extend. It owns the one place where the wire frame
+ * is built and correlated: id generation, {id, protocol} stamping, codec
+ * encode/decode, and transport.send. It composes DisposableBase to obtain its
+ * lifecycle (init/dispose) and bounded execution (timeout/retry/abort), but it
+ * carries no PythonRuntime contract obligation — the facade implements
+ * PythonRuntime and delegates the four RPC methods to this client.
  *
- * Subclasses (NodeBridge, HttpBridge, PyodideBridge) only need to:
- * 1. Create their transport in their constructor
- * 2. Pass it to super() via BridgeProtocolOptions
- * 3. Optionally override doInit() and doDispose() for additional setup/teardown
+ * Why composition (not inheritance): inheritance previously forced the RPC
+ * contract onto a lifecycle base, leaking throwing RPC stubs into transports.
+ * Holding one RpcClient keeps exactly one encode/decode/correlation site and
+ * lets transports stay pure byte-movers.
  *
  * @see https://github.com/bbopen/tywrap/issues/149
  */
 
 import type { BridgeInfo } from '../types/index.js';
 
-import { BoundedContext, type ExecuteOptions } from './bounded-context.js';
+import { DisposableBase, type ExecuteOptions } from './bounded-context.js';
 import { BridgeProtocolError } from './errors.js';
 import { SafeCodec, type CodecOptions } from './safe-codec.js';
 import { TYWRAP_PROTOCOL_VERSION } from './protocol.js';
@@ -37,9 +39,9 @@ export interface GetBridgeInfoOptions {
 }
 
 /**
- * Configuration options for BridgeProtocol.
+ * Configuration options for RpcClient.
  */
-export interface BridgeProtocolOptions {
+export interface RpcClientOptions {
   /** The transport to use for communication */
   transport: Transport;
 
@@ -174,43 +176,37 @@ function validateBridgeInfoPayload(value: unknown): BridgeInfo {
 }
 
 // =============================================================================
-// BRIDGE PROTOCOL BASE CLASS
+// RPC CLIENT
 // =============================================================================
 
 /**
- * BridgeProtocol combines BoundedContext + SafeCodec + Transport
- * into a unified abstraction for all JS<->Python communication.
- *
- * This class provides:
- * - Automatic transport lifecycle management
- * - Request encoding with guardrails (special float rejection, key validation)
- * - Response decoding with Arrow support
- * - Full RuntimeExecution interface implementation
- *
- * Subclasses should:
- * 1. Create their transport in their constructor
- * 2. Pass it to super() via BridgeProtocolOptions
- * 3. Optionally override doInit() and doDispose() for additional setup/teardown
+ * RpcClient holds a SafeCodec + Transport and composes DisposableBase for
+ * lifecycle/bounded-execution. It is the one correlated-RPC client; bridge
+ * facades HOLD an instance and delegate their PythonRuntime methods to it.
  *
  * @example
  * ```typescript
- * class NodeBridge extends BridgeProtocol {
+ * class NodeBridge extends DisposableBase implements PythonRuntime {
+ *   private readonly rpc: RpcClient;
  *   constructor(options: NodeBridgeOptions) {
+ *     super();
  *     const transport = new ProcessIO(options);
- *     super({ transport, defaultTimeoutMs: options.timeout });
+ *     this.rpc = new RpcClient({ transport, defaultTimeoutMs: options.timeout });
+ *     this.trackResource(this.rpc);
  *   }
+ *   // call/instantiate/callMethod/disposeInstance delegate to this.rpc.*
  * }
  * ```
  */
-export class BridgeProtocol extends BoundedContext {
+export class RpcClient extends DisposableBase {
   /** Codec instance for validation and serialization */
-  protected readonly codec: SafeCodec;
+  readonly codec: SafeCodec;
 
   /** Transport instance for message passing */
-  protected readonly transport: Transport;
+  readonly transport: Transport;
 
   /** Default timeout for operations in milliseconds */
-  protected readonly defaultTimeoutMs: number;
+  readonly defaultTimeoutMs: number;
 
   /** Counter for generating unique request IDs */
   private requestId = 0;
@@ -219,11 +215,11 @@ export class BridgeProtocol extends BoundedContext {
   private bridgeInfoCache?: BridgeInfo;
 
   /**
-   * Create a new BridgeProtocol instance.
+   * Create a new RpcClient instance.
    *
    * @param options - Configuration options including transport and codec settings
    */
-  constructor(options: BridgeProtocolOptions) {
+  constructor(options: RpcClientOptions) {
     super();
     this.codec = new SafeCodec(options.codec);
     this.transport = options.transport;
@@ -238,26 +234,22 @@ export class BridgeProtocol extends BoundedContext {
   // ===========================================================================
 
   /**
-   * Initialize the protocol.
-   *
-   * Initializes the underlying transport. Subclasses can override this
-   * to add additional initialization logic, but must call super.doInit().
+   * Initialize the client by initializing the underlying transport.
+   * Driven by the holding facade's lifecycle (facade.init() -> rpc.init()).
    */
   protected async doInit(): Promise<void> {
     await this.transport.init();
   }
 
   /**
-   * Dispose the protocol.
+   * Dispose the client.
    *
-   * The transport is tracked as a resource and will be disposed automatically
-   * by BoundedContext. Subclasses can override this to add additional cleanup,
-   * but should not need to dispose the transport manually.
+   * The transport is tracked as a resource and is disposed automatically by
+   * DisposableBase. Here we only clear the cached bridge info.
    */
   protected async doDispose(): Promise<void> {
     this.bridgeInfoCache = undefined;
-    // Transport is tracked and will be disposed by BoundedContext
-    // Subclasses can override to add additional cleanup
+    // Transport is tracked and will be disposed by DisposableBase.
   }
 
   // ===========================================================================
@@ -281,7 +273,7 @@ export class BridgeProtocol extends BoundedContext {
    * @throws BridgeExecutionError if Python returns an error
    * @throws BridgeTimeoutError if the operation times out
    */
-  protected async sendMessage<T>(
+  async sendMessage<T>(
     message: Omit<ProtocolMessage, 'id' | 'protocol'>,
     options?: ExecuteOptions<T>
   ): Promise<T> {
@@ -321,7 +313,7 @@ export class BridgeProtocol extends BoundedContext {
    * @throws BridgeExecutionError if Python returns an error
    * @throws BridgeTimeoutError if the operation times out
    */
-  protected async sendMessageAsync<T>(
+  async sendMessageAsync<T>(
     message: Omit<ProtocolMessage, 'id' | 'protocol'>,
     options?: ExecuteOptions<T>
   ): Promise<T> {
@@ -347,6 +339,41 @@ export class BridgeProtocol extends BoundedContext {
     }, options);
   }
 
+  /**
+   * Send a message over an EXPLICIT transport (not this.transport) with the
+   * same id-generation + codec encode/decode as the normal send path, but
+   * WITHOUT this.execute() and WITHOUT auto-init.
+   *
+   * This is the warmup path: NodeBridge runs warmup commands inside
+   * transport.init() (worker spawn -> onWorkerReady), which happens DURING
+   * rpc.init(). Routing those through this.execute() would auto-init this same
+   * client and re-await the in-flight init() that is itself waiting on warmup,
+   * deadlocking. So sendOn deliberately skips lifecycle: it only unifies the
+   * id counter + codec, never the state machine.
+   *
+   * @param transport - The specific worker transport to send on
+   * @param message - The protocol message (without id/protocol; stamped here)
+   * @param opts - Optional timeout / abort signal
+   */
+  async sendOn<T>(
+    transport: Transport,
+    message: Omit<ProtocolMessage, 'id' | 'protocol'>,
+    opts?: { timeoutMs?: number; signal?: AbortSignal }
+  ): Promise<T> {
+    const fullMessage: ProtocolMessage = {
+      ...message,
+      id: this.generateId(),
+      protocol: PROTOCOL_ID,
+    };
+    const encoded = this.codec.encodeRequest(fullMessage);
+    const responseStr = await transport.send(
+      encoded,
+      opts?.timeoutMs ?? this.defaultTimeoutMs,
+      opts?.signal
+    );
+    return this.codec.decodeResponseAsync<T>(responseStr);
+  }
+
   /**
    * Generate a unique request ID.
    *
@@ -358,7 +385,7 @@ export class BridgeProtocol extends BoundedContext {
   }
 
   // ===========================================================================
-  // RUNTIME EXECUTION INTERFACE
+  // RPC METHODS (delegated to by the facade's PythonRuntime implementation)
   // ===========================================================================
 
   /**

package/src/runtime/worker-pool.ts

@@ -7,7 +7,7 @@
  * @see https://github.com/bbopen/tywrap/issues/149
  */
 
-import { BoundedContext } from './bounded-context.js';
+import { DisposableBase } from './bounded-context.js';
 import { BridgeTimeoutError, BridgeExecutionError, BridgeProtocolError } from './errors.js';
 import type { Transport } from './transport.js';
 
@@ -105,7 +105,7 @@ interface QueuedWaiter {
  * await pool.dispose();
  * ```
  */
-export class WorkerPool extends BoundedContext {
+export class WorkerPool extends DisposableBase {
   private readonly options: Omit<
     Required<WorkerPoolOptions>,
     'onWorkerReady' | 'onReplacementWorkerReady'
@@ -535,60 +535,4 @@ export class WorkerPool extends BoundedContext {
       this.waitQueue.push({ resolve, reject, timer });
     });
   }
-
-  // ===========================================================================
-  // RUNTIME EXECUTION (Not implemented - WorkerPool is just for worker management)
-  // ===========================================================================
-
-  /**
-   * Not implemented - WorkerPool does not execute Python calls directly.
-   * Use the BridgeProtocol layer with a pooled worker's transport.
-   */
-  async call<T = unknown>(
-    _module: string,
-    _functionName: string,
-    _args: unknown[],
-    _kwargs?: Record<string, unknown>
-  ): Promise<T> {
-    throw new BridgeExecutionError(
-      'WorkerPool does not implement call() - use withWorker() to get a transport'
-    );
-  }
-
-  /**
-   * Not implemented - WorkerPool does not execute Python calls directly.
-   */
-  async instantiate<T = unknown>(
-    _module: string,
-    _className: string,
-    _args: unknown[],
-    _kwargs?: Record<string, unknown>
-  ): Promise<T> {
-    throw new BridgeExecutionError(
-      'WorkerPool does not implement instantiate() - use withWorker() to get a transport'
-    );
-  }
-
-  /**
-   * Not implemented - WorkerPool does not execute Python calls directly.
-   */
-  async callMethod<T = unknown>(
-    _handle: string,
-    _methodName: string,
-    _args: unknown[],
-    _kwargs?: Record<string, unknown>
-  ): Promise<T> {
-    throw new BridgeExecutionError(
-      'WorkerPool does not implement callMethod() - use withWorker() to get a transport'
-    );
-  }
-
-  /**
-   * Not implemented - WorkerPool does not execute Python calls directly.
-   */
-  async disposeInstance(_handle: string): Promise<void> {
-    throw new BridgeExecutionError(
-      'WorkerPool does not implement disposeInstance() - use withWorker() to get a transport'
-    );
-  }
 }

package/src/types/index.ts

@@ -364,12 +364,16 @@ export interface TypeMappingConfig {
   presets?: TypePreset[];
 }
 
+/** Known bridge backends. Each speaks the identical "tywrap/1" protocol. */
+export type BridgeBackend = 'python-subprocess' | 'pyodide' | 'http';
+
 export interface BridgeInfo {
   protocol: string;
   protocolVersion: number;
-  bridge: 'python-subprocess';
+  bridge: BridgeBackend;
   pythonVersion: string;
-  pid: number;
+  /** OS process id for subprocess backends; null for in-WASM (Pyodide). */
+  pid: number | null;
   codecFallback: 'json' | 'none';
   arrowAvailable: boolean;
   scipyAvailable: boolean;
@@ -424,8 +428,14 @@ export interface GenerationMetadata {
   optimizations: string[];
 }
 
-// Runtime bridge interface
-export interface RuntimeExecution {
+// PythonRuntime — the four cross-boundary RPC methods generated wrappers call.
+// This is the contract that, after the composition rework, is implemented ONLY
+// by the bridge facades (NodeBridge/HttpBridge/PyodideBridge); the facades
+// satisfy it by delegating to an owned RpcClient. It deliberately carries NO
+// lifecycle method — dispose() is a separate lifecycle concern (see Disposable
+// in runtime/disposable.ts), so transports and the lifecycle base class
+// (DisposableBase) never have to stub these methods.
+export interface PythonRuntime {
   call<T = unknown>(
     module: string,
     functionName: string,
@@ -448,7 +458,13 @@ export interface RuntimeExecution {
   ): Promise<T>;
 
   disposeInstance(handle: string): Promise<void>;
+}
 
+// Runtime bridge interface — the four RPC methods plus lifecycle dispose().
+// Kept as PythonRuntime + dispose() so getRuntimeBridge() and every existing
+// `RuntimeExecution` reference (registry, dev.ts) compile with zero churn. The
+// RuntimeExecution -> PythonRuntime symbol rename is deferred to the T9 pass.
+export interface RuntimeExecution extends PythonRuntime {
   dispose(): Promise<void>;
 }
 

package/src/tywrap.ts

@@ -18,7 +18,6 @@ import type {
 } from './types/index.js';
 import { fsUtils, pathUtils, processUtils, isWindows } from './utils/runtime.js';
 import { globalCache } from './utils/cache.js';
-import { globalParallelProcessor } from './utils/parallel-processor.js';
 import { resolvePythonExecutable } from './utils/python.js';
 import { computeIrCacheFilename } from './utils/ir-cache.js';
 
@@ -45,7 +44,6 @@ export async function tywrap(options: Partial<TywrapOptions> = {}): Promise<Tywr
   const generator = new CodeGenerator(mapper);
 
   globalCache.setDebug(options.debug ?? false);
-  globalParallelProcessor.setDebug(options.debug ?? false);
 
   return {
     mapper,
@@ -155,7 +153,7 @@ export async function generate(
     const moduleConfig = entry[1];
     // reset collector for each module
     unknownTypeNamesCollector = new Map();
-    // Prefer Python IR extractor over TS analyzer with optional cache
+    // Resolve module IR via the Python extractor (with optional cache)
     const cacheKey = await computeCacheKey(moduleKey, resolvedOptions);
     let ir: unknown | null = null;
     let irError: string | undefined;

package/dist/core/analyzer.d.ts

@@ -1,64 +0,0 @@
-/**
- * PyAnalyzer - Python AST analysis and type extraction
- */
-import type { SyntaxNode } from 'tree-sitter';
-import type { AnalysisResult, PythonFunction, PythonClass, PythonType } from '../types/index.js';
-export declare class PyAnalyzer {
-    private parser;
-    private initialized;
-    constructor();
-    /**
-     * Initialize the tree-sitter parser with Python grammar
-     */
-    initialize(): Promise<void>;
-    /**
-     * Analyze Python module source code and extract structure with caching
-     */
-    analyzePythonModule(source: string, modulePath?: string): Promise<AnalysisResult>;
-    /**
-     * Extract function definitions from AST
-     */
-    extractFunctions(node: SyntaxNode): Promise<PythonFunction[]>;
-    /**
-     * Extract class definitions from AST
-     */
-    extractClasses(node: SyntaxNode): Promise<PythonClass[]>;
-    /**
-     * Extract single function from function_definition node
-     */
-    private extractFunction;
-    /**
-     * Extract single class from class_definition node
-     */
-    private extractClass;
-    /**
-     * Extract function parameters from parameters node
-     */
-    private extractParameters;
-    /**
-     * Parse type annotation node into PythonType
-     */
-    parseTypeAnnotation(node: SyntaxNode): PythonType;
-    private parseGenericType;
-    private parseUnionType;
-    private parseGenericArguments;
-    /**
-     * Extract import statements
-     */
-    private extractImports;
-    /**
-     * Utility methods
-     */
-    private findNodesByType;
-    private findDirectDefinitions;
-    private extractModuleName;
-    private extractDecorators;
-    private extractDocstring;
-    private containsYield;
-    private extractBases;
-    private extractProperty;
-    private extractExports;
-    private collectSyntaxErrors;
-    private generateStatistics;
-}
-//# sourceMappingURL=analyzer.d.ts.map

package/dist/core/analyzer.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../../src/core/analyzer.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAI9C,OAAO,KAAK,EACV,cAAc,EAKd,cAAc,EACd,WAAW,EAEX,UAAU,EAIX,MAAM,mBAAmB,CAAC;AAS3B,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAAS;;IAM5B;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAajC;;OAEG;IACG,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAiFvF;;OAEG;IACG,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAiBnE;;OAEG;IACG,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAiB9D;;OAEG;YACW,eAAe;IAyC7B;;OAEG;YACW,YAAY;IAuD1B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAkHzB;;OAEG;IACH,mBAAmB,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU;IA0FjD,OAAO,CAAC,gBAAgB;IAqBxB,OAAO,CAAC,cAAc;IAatB,OAAO,CAAC,qBAAqB;IAiC7B;;OAEG;IACH,OAAO,CAAC,cAAc;IAwFtB;;OAEG;IACH,OAAO,CAAC,eAAe;IAqBvB,OAAO,CAAC,qBAAqB;IAoB7B,OAAO,CAAC,iBAAiB;IAQzB,OAAO,CAAC,iBAAiB;IAYzB,OAAO,CAAC,gBAAgB;IAyBxB,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,cAAc;IAiBtB,OAAO,CAAC,mBAAmB;IAe3B,OAAO,CAAC,kBAAkB;CA0B3B"}