tywrap 0.8.0 → 0.10.0

package/src/core/mapper.ts

@@ -32,9 +32,9 @@ import type {
   TypePreset,
 } from '../types/index.js';
 
-export type MappingContext = 'value' | 'return';
+type MappingContext = 'value' | 'return';
 
-export interface TypeMapperOptions {
+interface TypeMapperOptions {
   presets?: readonly TypePreset[];
 }
 
@@ -94,7 +94,7 @@ export class TypeMapper {
           : type.name === 'bool'
             ? 'boolean'
             : type.name === 'bytes'
-              ? 'string'
+              ? 'Uint8Array'
               : // None
                 context === 'return'
                 ? 'void'
@@ -137,16 +137,15 @@ export class TypeMapper {
       return { kind: 'tuple', elementTypes } satisfies TSTupleType;
     }
 
-    // set[T] -> Set<T>
+    // Python sets cross the JSON bridge as arrays in both directions.
     if (type.name === 'set' || type.name === 'frozenset') {
       const elementType = this.mapPythonType(
         type.itemTypes[0] ?? { kind: 'custom', name: 'Any', module: 'typing' }
       );
       return {
-        kind: 'generic',
-        name: 'Set',
-        typeArgs: [elementType],
-      } satisfies TSGenericType;
+        kind: 'array',
+        elementType,
+      } satisfies TSArrayType;
     }
 
     // dict[K, V] -> { [key: K]: V }
@@ -204,6 +203,7 @@ export class TypeMapper {
     return {
       kind: 'generic',
       name: normalized.name,
+      module: normalized.module,
       typeArgs,
     };
   }

package/src/index.ts

@@ -1,8 +1,10 @@
 /**
- * tywrap - TypeScript wrapper for Python libraries with full type safety
+ * tywrap - TypeScript bindings for Python libraries
  *
- * @description Build-time code generation system that makes Python libraries
- * feel native in TypeScript with zero runtime overhead
+ * @description Build-time code generation that produces typed wrappers for
+ * Python modules: precise types where annotations resolve, `unknown` where
+ * they cannot, and runtime validation of decoded returns against the
+ * declared types.
  *
  * This is the package root. It intentionally exposes only the stable,
  * consumer-facing surface. Runtime plumbing (codec, transport, bridge
@@ -21,6 +23,7 @@ export {
   BridgeError,
   BridgeCodecError,
   BridgeProtocolError,
+  BridgeValidationError,
   BridgeTimeoutError,
   BridgeDisposedError,
   BridgeExecutionError,
@@ -29,6 +32,7 @@ export {
 // Core types
 export type {
   PythonModule,
+  IrContract,
   PythonFunction,
   PythonClass,
   PythonTypeAlias,
@@ -68,7 +72,6 @@ export type {
   TypeMappingConfig,
   TypePreset,
   BridgeInfo,
-  BridgeTransportInfo,
   AnalysisResult,
   AnalysisError,
   AnalysisWarning,

package/src/runtime/base-bridge.ts

@@ -3,12 +3,11 @@
  *
  * The three bridge facades (NodeBridge/HttpBridge/PyodideBridge) all extend
  * DisposableBase (lifecycle/resources) and implement PythonRuntime by HOLDING
- * an RpcClient. The PythonRuntime delegation was byte-identical across all
+ * an RpcClient. The PythonRuntime delegation is byte-identical across all
  * three: each method does `await this.ensureReady()` then forwards to the held
  * RpcClient. This base collapses that duplication onto a single
  * `getRpcClient()` accessor while leaving each facade free to own its own
- * RpcClient field (for constructor wiring, resource tracking, and — in
- * NodeBridge's case — a caching override of call()).
+ * RpcClient field for constructor wiring and resource tracking.
  *
  * It carries no transport/codec/lifecycle specifics: doInit/doDispose remain
  * abstract on DisposableBase and stay per-facade.
@@ -44,35 +43,11 @@ export abstract class BasePythonBridge extends DisposableBase implements PythonR
     module: string,
     functionName: string,
     args: unknown[],
-    kwargs?: Record<string, unknown>
+    kwargs?: Record<string, unknown>,
+    validate?: (result: T) => void
   ): Promise<T> {
     await this.ensureReady();
-    return this.getRpcClient().call<T>(module, functionName, args, kwargs);
-  }
-
-  async instantiate<T = unknown>(
-    module: string,
-    className: string,
-    args: unknown[],
-    kwargs?: Record<string, unknown>
-  ): Promise<T> {
-    await this.ensureReady();
-    return this.getRpcClient().instantiate<T>(module, className, args, kwargs);
-  }
-
-  async callMethod<T = unknown>(
-    handle: string,
-    methodName: string,
-    args: unknown[],
-    kwargs?: Record<string, unknown>
-  ): Promise<T> {
-    await this.ensureReady();
-    return this.getRpcClient().callMethod<T>(handle, methodName, args, kwargs);
-  }
-
-  async disposeInstance(handle: string): Promise<void> {
-    await this.ensureReady();
-    return this.getRpcClient().disposeInstance(handle);
+    return this.getRpcClient().call<T>(module, functionName, args, kwargs, validate);
   }
 
   /**

package/src/runtime/bounded-context.ts

@@ -2,9 +2,9 @@
  * DisposableBase - Lifecycle-and-resource base for cross-boundary components.
  *
  * Provides ONLY: init/dispose state machine, validation helpers, error
- * classification, bounded execution (timeout/retry/abort), and resource
+ * classification, single-attempt bounded execution (timeout/abort), and resource
  * ownership tracking. It carries ZERO RPC methods by design — the
- * cross-boundary RPC contract (call/instantiate/callMethod/disposeInstance)
+ * cross-boundary RPC contract (call)
  * is PythonRuntime, implemented only by the bridge facades, never by a base
  * class or a transport. This separation is what keeps transports (SubprocessTransport,
  * PooledTransport, TransportPool, PyodideTransport) and RpcClient from having to stub
@@ -53,10 +53,6 @@ export type ContextState = 'idle' | 'initializing' | 'ready' | 'disposing' | 'di
 export interface ExecuteOptions<T = unknown> {
   /** Timeout in milliseconds. Default: 30000 (30s). Set to 0 to disable. */
   timeoutMs?: number;
-  /** Number of retry attempts on retryable errors. Default: 0. */
-  retries?: number;
-  /** Base delay between retries in ms. Multiplied by attempt number. Default: 100. */
-  retryDelayMs?: number;
   /** Optional validation function applied to the result. */
   validate?: (result: T) => T;
   /** Optional abort signal for external cancellation. */
@@ -375,12 +371,11 @@ export abstract class DisposableBase {
    * This method:
    * - Auto-initializes if not ready
    * - Enforces timeout limits
-   * - Supports retry on retryable errors
    * - Respects abort signals
    * - Validates results if a validator is provided
    *
    * @param operation - The async operation to execute
-   * @param options - Execution options (timeout, retries, etc.)
+   * @param options - Execution options (timeout, validation, and abort)
    * @returns The operation result
    * @throws BridgeTimeoutError if the operation times out
    * @throws BridgeDisposedError if the context is disposed
@@ -400,35 +395,16 @@ export abstract class DisposableBase {
       throw new BridgeDisposedError('Context disposed');
     }
 
-    const { timeoutMs = 30000, retries = 0, retryDelayMs = 100, validate, signal } = options;
-
-    let lastError: BridgeError | undefined;
-
-    for (let attempt = 0; attempt <= retries; attempt++) {
-      // Check for abort before each attempt
-      if (signal?.aborted) {
-        throw new BridgeTimeoutError('Operation aborted');
-      }
-
-      try {
-        const result = await this.withTimeout(operation(), timeoutMs, signal);
-        return validate ? validate(result) : result;
-      } catch (error) {
-        lastError = this.classifyError(error);
-
-        // Retry if appropriate
-        if (attempt < retries && this.isRetryable(lastError)) {
-          await this.delay(retryDelayMs * (attempt + 1));
-          continue;
-        }
-
-        throw lastError;
-      }
+    const { timeoutMs = 30000, validate, signal } = options;
+    if (signal?.aborted) {
+      throw new BridgeTimeoutError('Operation aborted');
+    }
+    try {
+      const result = await this.withTimeout(operation(), timeoutMs, signal);
+      return validate ? validate(result) : result;
+    } catch (error) {
+      throw this.classifyError(error);
     }
-
-    // Should not reach here, but TypeScript doesn't know that
-    /* istanbul ignore next */
-    throw lastError ?? new BridgeExecutionError('Unexpected execution flow');
   }
 
   /**
@@ -498,37 +474,6 @@ export abstract class DisposableBase {
     });
   }
 
-  /**
-   * Determine if an error is retryable.
-   * Override in subclasses to customize retry logic.
-   *
-   * @param error - The error to check
-   * @returns True if the operation should be retried
-   */
-  protected isRetryable(error: BridgeError): boolean {
-    // Timeout and connection errors are typically retryable
-    if (error instanceof BridgeTimeoutError) {
-      return true;
-    }
-
-    const message = error.message.toLowerCase();
-    return (
-      message.includes('econnreset') ||
-      message.includes('econnrefused') ||
-      message.includes('epipe') ||
-      message.includes('connection reset')
-    );
-  }
-
-  /**
-   * Delay for a specified duration.
-   *
-   * @param ms - Milliseconds to delay
-   */
-  private delay(ms: number): Promise<void> {
-    return new Promise(resolve => setTimeout(resolve, ms));
-  }
-
   // ═══════════════════════════════════════════════════════════════════════════
   // RESOURCE OWNERSHIP (addresses #144, #148)
   // ═══════════════════════════════════════════════════════════════════════════

package/src/runtime/bridge-codec.ts

@@ -10,7 +10,11 @@
 
 import { BridgeCodecError, BridgeProtocolError, BridgeExecutionError } from './errors.js';
 import { containsSpecialFloat } from './validators.js';
-import { decodeValueAsync as decodeArrowValue } from '../utils/codec.js';
+import {
+  decodeValueAsync as decodeScientificValue,
+  isScientificMarker,
+  ScientificDecodeError,
+} from '../utils/codec.js';
 import { PROTOCOL_ID } from './transport.js';
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -28,7 +32,7 @@ export interface CodecOptions {
   /** Max payload size in bytes. Default: 10MB */
   maxPayloadBytes?: number;
   /** How to handle bytes/bytearray. Default: 'base64' */
-  bytesHandling?: 'base64' | 'reject' | 'passthrough';
+  bytesHandling?: 'base64' | 'reject';
 }
 
 /**
@@ -77,6 +81,10 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
   return proto === Object.prototype || proto === null;
 }
 
+function isPlainArray(value: unknown): value is unknown[] {
+  return Array.isArray(value) && Object.getPrototypeOf(value) === Array.prototype;
+}
+
 /**
  * Build a path string for error messages.
  */
@@ -87,67 +95,126 @@ function buildPath(basePath: string, key: string | number): string {
   return typeof key === 'number' ? `${basePath}[${key}]` : `${basePath}.${key}`;
 }
 
+function containsScientificEnvelope(value: unknown): boolean {
+  const pending: unknown[] = [value];
+  while (pending.length > 0) {
+    const current = pending.pop();
+    if (isPlainArray(current)) {
+      for (const item of current) {
+        pending.push(item);
+      }
+      continue;
+    }
+    if (!isPlainObject(current)) {
+      continue;
+    }
+    if (typeof current.__tywrap__ === 'string') {
+      return isScientificMarker(current.__tywrap__);
+    }
+    for (const item of Object.values(current)) {
+      pending.push(item);
+    }
+  }
+  return false;
+}
+
 /**
- * Recursively check for non-string keys in objects and Maps.
- * Throws BridgeCodecError with path indication if found.
+ * Validate request-only restrictions in one traversal.
+ *
+ * Request validation historically checked every finite number before checking
+ * structure. Keep that precedence while combining the walks: capture the first
+ * structural error (Map, Set, or symbol key) in traversal order, and prefer
+ * the special-float error after the traversal.
  */
-function assertStringKeys(
+function assertValidRequestValues(
   value: unknown,
-  path: string = '',
-  visited: WeakSet<object> = new WeakSet<object>()
+  rejectSpecialFloats: boolean,
+  rejectNonStringKeys: boolean,
+  path: string = ''
 ): void {
-  if (value === null || typeof value !== 'object') {
-    return;
-  }
-  if (visited.has(value)) {
-    return;
-  }
-  visited.add(value);
+  let specialFloatPath: string | undefined;
+  let structuralError: BridgeCodecError | undefined;
+  const specialVisited = new WeakSet<object>();
+  const structVisited = new WeakSet<object>();
+
+  const visit = (current: unknown, currentPath: string, structuralScope: boolean): void => {
+    if (typeof current === 'number' && !Number.isFinite(current)) {
+      if (rejectSpecialFloats) {
+        specialFloatPath ??= currentPath || 'root';
+      }
+      return;
+    }
+    if (current === null || typeof current !== 'object') {
+      return;
+    }
 
-  // Check Map instances for non-string keys
-  if (value instanceof Map) {
-    for (const key of value.keys()) {
-      if (typeof key !== 'string') {
-        const keyDesc = typeof key === 'symbol' ? key.toString() : String(key);
-        const location = path ? ` at ${path}` : '';
-        throw new BridgeCodecError(
-          `Non-string key found in Map${location}: ${keyDesc} (${typeof key})`,
+    if (current instanceof Map || current instanceof Set) {
+      // JSON.stringify serializes every Map and Set as {}, including Maps with
+      // string keys — reject unconditionally. Special-float validation
+      // historically does not inspect Map/Set contents, so no recursion.
+      if (structuralScope && !structVisited.has(current)) {
+        structVisited.add(current);
+        const location = currentPath ? ` at ${currentPath}` : '';
+        structuralError ??= new BridgeCodecError(
+          current instanceof Map
+            ? `Cannot encode request: Map found${location}; convert it to a plain object before sending`
+            : `Cannot encode request: Set found${location}; convert it to an array before sending`,
           { codecPhase: 'encode' }
         );
       }
+      return;
     }
-    // Recurse into Map values
-    for (const [key, val] of value.entries()) {
-      assertStringKeys(val, buildPath(path, key), visited);
-    }
-    return;
-  }
 
-  // Check arrays
-  if (Array.isArray(value)) {
-    for (const [index, item] of value.entries()) {
-      assertStringKeys(item, buildPath(path, index), visited);
+    const needsSpecialWalk = rejectSpecialFloats && !specialVisited.has(current);
+    const needsStructWalk = structuralScope && !structVisited.has(current);
+    if (!needsSpecialWalk && !needsStructWalk) {
+      return;
+    }
+    if (needsSpecialWalk) {
+      specialVisited.add(current);
+    }
+    if (needsStructWalk) {
+      structVisited.add(current);
     }
-    return;
-  }
 
-  // Check plain objects for symbol keys
-  if (isPlainObject(value)) {
-    // Symbol keys are not enumerated by Object.keys, use getOwnPropertySymbols
-    const symbolKeys = Object.getOwnPropertySymbols(value);
-    const firstSymbol = symbolKeys[0];
-    if (firstSymbol !== undefined) {
-      const symbolDesc = firstSymbol.toString();
-      const location = path ? ` at ${path}` : '';
-      throw new BridgeCodecError(`Symbol key found in object${location}: ${symbolDesc}`, {
-        codecPhase: 'encode',
-      });
+    if (Array.isArray(current)) {
+      for (const [index, item] of current.entries()) {
+        visit(item, buildPath(currentPath, index), structuralScope);
+      }
+      return;
     }
 
-    // Recurse into object values
-    for (const [key, item] of Object.entries(value)) {
-      assertStringKeys(item, buildPath(path, key), visited);
+    const plainObject = isPlainObject(current);
+    if (plainObject && needsStructWalk && rejectNonStringKeys) {
+      // Symbol keys are not enumerated by Object.keys, use getOwnPropertySymbols
+      const firstSymbol = Object.getOwnPropertySymbols(current)[0];
+      if (firstSymbol !== undefined) {
+        const location = currentPath ? ` at ${currentPath}` : '';
+        structuralError ??= new BridgeCodecError(
+          `Symbol key found in object${location}: ${firstSymbol.toString()}`,
+          { codecPhase: 'encode' }
+        );
+      }
+    }
+    // Special-float detection historically traversed every non-array object
+    // with enumerable values, including class instances. Structural validation
+    // remains restricted to arrays and plain objects, matching its prior scope.
+    if (needsSpecialWalk || plainObject) {
+      for (const [key, item] of Object.entries(current)) {
+        visit(item, buildPath(currentPath, key), structuralScope && plainObject);
+      }
     }
+  };
+
+  visit(value, path, true);
+  if (rejectSpecialFloats && specialFloatPath !== undefined) {
+    throw new BridgeCodecError(
+      `Cannot encode request: contains non-finite number (NaN or Infinity) at ${specialFloatPath}`,
+      { codecPhase: 'encode', valueType: 'number' }
+    );
+  }
+  if (structuralError !== undefined) {
+    throw structuralError;
   }
 }
 
@@ -318,7 +385,7 @@ export class BridgeCodec {
   private readonly rejectSpecialFloats: boolean;
   private readonly rejectNonStringKeys: boolean;
   private readonly maxPayloadBytes: number;
-  private readonly bytesHandling: 'base64' | 'reject' | 'passthrough';
+  private readonly bytesHandling: 'base64' | 'reject';
   private readonly reviveValueBound: (key: string, value: unknown) => unknown;
   private static readonly base64Pattern =
     /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
@@ -506,19 +573,9 @@ export class BridgeCodec {
    * @throws BridgeCodecError if validation fails or encoding fails
    */
   encodeRequest(message: unknown): string {
-    // Validate special floats if enabled
-    if (this.rejectSpecialFloats && containsSpecialFloat(message)) {
-      const floatPath = findSpecialFloatPath(message);
-      throw new BridgeCodecError(
-        `Cannot encode request: contains non-finite number (NaN or Infinity) at ${floatPath}`,
-        { codecPhase: 'encode', valueType: 'number' }
-      );
-    }
-
-    // Validate string keys if enabled
-    if (this.rejectNonStringKeys) {
-      assertStringKeys(message);
-    }
+    // Reject, in one traversal, values JSON.stringify would silently mangle:
+    // non-finite numbers, Map/Set, and (optionally) non-string keys.
+    assertValidRequestValues(message, this.rejectSpecialFloats, this.rejectNonStringKeys);
 
     // Serialize to JSON with error handling
     let payload: string;
@@ -537,9 +594,6 @@ export class BridgeCodec {
               const b64 = this.toBase64(bytes);
               return { __tywrap_bytes__: true, b64 };
             }
-            case 'passthrough':
-            default:
-              return value;
           }
         }
         return value;
@@ -558,7 +612,10 @@ export class BridgeCodec {
     }
 
     // Check payload size
-    const payloadBytes = new TextEncoder().encode(payload).length;
+    const payloadBytes =
+      typeof Buffer !== 'undefined'
+        ? Buffer.byteLength(payload, 'utf8')
+        : new TextEncoder().encode(payload).length;
     if (payloadBytes > this.maxPayloadBytes) {
       throw new BridgeCodecError(
         `Payload size ${payloadBytes} bytes exceeds maximum ${this.maxPayloadBytes} bytes`,
@@ -582,6 +639,13 @@ export class BridgeCodec {
   decodeResponse<T>(payload: string): T {
     const result = this.parseResponseResult(payload);
 
+    if (containsScientificEnvelope(result)) {
+      throw new BridgeCodecError('scientific envelopes require decodeResponseAsync', {
+        codecPhase: 'decode',
+        valueType: 'scientific-envelope',
+      });
+    }
+
     // Post-decode validation for special floats if enabled
     this.assertNoSpecialFloats(result);
 
@@ -589,8 +653,8 @@ export class BridgeCodec {
   }
 
   /**
-   * Async version that applies Arrow decoders.
-   * Use this when the response may contain encoded DataFrames or ndarrays.
+   * Async version that decodes scientific envelopes.
+   * Use this when the response may contain encoded scientific values.
    *
    * @param payload - The JSON string received from Python
    * @returns Decoded and validated result with Arrow decoding applied
@@ -601,22 +665,42 @@ export class BridgeCodec {
   async decodeResponseAsync<T>(payload: string): Promise<T> {
     const result = this.parseResponseResult(payload);
 
-    // Apply Arrow decoding to the result
+    // Decode scientific envelopes in the result.
     let decoded: unknown;
     try {
-      decoded = await decodeArrowValue(result);
+      decoded = await decodeScientificValue(result);
     } catch (err) {
       const errorMessage = err instanceof Error ? err.message : String(err);
-      throw new BridgeCodecError(`Arrow decoding failed: ${errorMessage}`, {
-        codecPhase: 'decode',
-        valueType: 'arrow',
-      });
+      const decodeError = err instanceof ScientificDecodeError ? err : undefined;
+      const marker =
+        decodeError?.marker ??
+        (isPlainObject(result) && isScientificMarker(result.__tywrap__)
+          ? result.__tywrap__
+          : 'unknown');
+      const genuineArrowError = decodeError?.kind === 'arrow';
+      const valueType = genuineArrowError
+        ? 'arrow'
+        : marker === 'unknown'
+          ? 'scientific-envelope'
+          : marker;
+      throw new BridgeCodecError(
+        genuineArrowError
+          ? `Arrow decoding failed: ${errorMessage}`
+          : `Scientific envelope decoding failed (${marker}): ${errorMessage}`,
+        {
+          codecPhase: 'decode',
+          valueType,
+        }
+      );
     }
 
     // Post-decode validation for special floats if enabled
     // Note: Arrow decoders can introduce NaN/Infinity from binary representations.
     this.assertNoSpecialFloats(decoded);
 
+    // Return-contract validation is intentionally downstream of this codec. At
+    // this boundary we guarantee only a sound wire envelope and decoded value;
+    // generated wrappers validate the Python annotation after Arrow/JSON decode.
     return decoded as T;
   }
 

package/src/runtime/errors.ts

@@ -14,6 +14,27 @@ export class BridgeProtocolError extends BridgeError {}
 export class BridgeTimeoutError extends BridgeError {}
 export class BridgeDisposedError extends BridgeError {}
 
+/**
+ * A decoded value did not match the return annotation emitted into a wrapper.
+ *
+ * This is deliberately separate from protocol/codec errors: the wire response
+ * was sound, but the Python implementation violated its declared contract.
+ */
+export class BridgeValidationError extends BridgeError {
+  readonly declaredType: string;
+  readonly receivedShape: string;
+  readonly callSite: string;
+
+  constructor(options: { declaredType: string; receivedShape: string; callSite: string }) {
+    super(
+      `Return validation failed for ${options.callSite}: expected ${options.declaredType}, received ${options.receivedShape}`
+    );
+    this.declaredType = options.declaredType;
+    this.receivedShape = options.receivedShape;
+    this.callSite = options.callSite;
+  }
+}
+
 export class BridgeCodecError extends BridgeError {
   codecPhase?: string;
   valueType?: string;

package/src/runtime/http-transport.ts

@@ -148,7 +148,12 @@ export class HttpTransport implements Transport {
    * @throws BridgeExecutionError if the server returns a non-2xx status
    * @throws BridgeProtocolError if the response cannot be read
    */
-  async send(message: string, timeoutMs: number, signal?: AbortSignal): Promise<string> {
+  async send(
+    message: string,
+    timeoutMs: number,
+    signal?: AbortSignal,
+    _requestId?: number
+  ): Promise<string> {
     if (this._isDisposed) {
       throw new BridgeDisposedError('Transport has been disposed');
     }

package/src/runtime/index.ts

@@ -11,6 +11,12 @@ import type { RuntimeExecution } from '../types/index.js';
 
 // BridgeCodec — validation and serialization for the JS<->Python boundary
 export { BridgeCodec, type CodecOptions } from './bridge-codec.js';
+export {
+  createReturnValidator,
+  describeReceivedShape,
+  type ReturnSchema,
+  type ReturnValidator,
+} from './validators.js';
 
 // Transport contract — abstract I/O channel interface and guards
 export type {