tywrap 0.8.0 → 0.9.0

package/src/runtime/timed-out-request-tracker.ts

@@ -1,4 +1,4 @@
-export interface TimedOutRequestTrackerOptions {
+interface TimedOutRequestTrackerOptions {
   ttlMs: number;
   maxSize?: number;
 }

package/src/runtime/transport.ts

@@ -57,9 +57,6 @@ export const FRAME_PROTOCOL_VERSION = Number.parseInt(FRAME_PROTOCOL_ID.split('/
  *
  * Each method corresponds to a BridgeProtocol operation:
  * - `call`: Invoke a module-level function
- * - `instantiate`: Create a new class instance
- * - `call_method`: Invoke a method on an existing instance
- * - `dispose_instance`: Release an instance handle
  * - `meta`: Get bridge metadata
  */
 export interface ProtocolMessage {
@@ -70,25 +67,16 @@ export interface ProtocolMessage {
   protocol: typeof PROTOCOL_ID;
 
   /** The method to invoke */
-  method: 'call' | 'instantiate' | 'call_method' | 'dispose_instance' | 'meta';
+  method: 'call' | 'meta';
 
   /** Method parameters */
   params: {
-    /** Python module path (for call and instantiate) */
+    /** Python module path (for call) */
     module?: string;
 
     /** Function name (for call) */
     functionName?: string;
 
-    /** Class name (for instantiate) */
-    className?: string;
-
-    /** Instance handle (for call_method and dispose_instance) */
-    handle?: string;
-
-    /** Method name (for call_method) */
-    methodName?: string;
-
     /** Positional arguments */
     args?: unknown[];
 
@@ -212,10 +200,8 @@ export interface ChunkFrame {
  * authoritative for transport-level flags; the meta report is authoritative for
  * library availability.
  *
- * Honest for TODAY's behavior: as of 0.8.0 `supportsChunking` is implemented for
- * the subprocess backend and reports the *configured* `tywrap-frame/1` path
- * (`enableChunking`) — static and lifecycle-independent, like `supportsArrow`;
- * the per-bridge negotiated fact lives on {@link BridgeInfo}'s `transport` block.
+ * `supportsChunking` is always true for the subprocess backend because the
+ * packaged Python bridge and JS transport always speak `tywrap-frame/1`.
  * HTTP and Pyodide stay `false`. `supportsStreaming` is `false` on every backend
  * (not implemented in 0.8.0). See docs/transport-capabilities.md for the full
  * matrix.
@@ -240,8 +226,8 @@ export interface TransportCapabilities {
 
   /**
    * Whether the transport splits a single logical message across multiple wire
-   * frames. Not implemented on any backend yet (planned for 0.8.0) — always
-   * `false`.
+   * frames. This is always `true` for the packaged subprocess transport and
+   * `false` for HTTP and Pyodide.
    */
   readonly supportsChunking: boolean;
 
@@ -255,7 +241,8 @@ export interface TransportCapabilities {
    * Maximum size, in bytes, of a single wire frame the transport will accept.
    * `Number.POSITIVE_INFINITY` means the transport imposes no frame ceiling of
    * its own (a higher layer — e.g. the codec's payload limit — may still cap the
-   * size). For the subprocess backend this is the JSONL line-length limit.
+   * size). For the subprocess backend this is the always-on framing ceiling for
+   * each JSONL wire frame.
    */
   readonly maxFrameBytes: number;
 }
@@ -326,7 +313,12 @@ export interface Transport extends Disposable {
    * @throws BridgeProtocolError if the message format is invalid
    * @throws BridgeError for other transport-level failures
    */
-  send(message: string, timeoutMs: number, signal?: AbortSignal): Promise<string>;
+  send(
+    message: string,
+    timeoutMs: number,
+    signal?: AbortSignal,
+    requestId?: number
+  ): Promise<string>;
 
   /**
    * Whether the transport is ready to send messages.
@@ -418,7 +410,7 @@ export function isProtocolMessage(value: unknown): value is ProtocolMessage {
     typeof msg.id === 'number' &&
     msg.protocol === PROTOCOL_ID &&
     typeof msg.method === 'string' &&
-    ['call', 'instantiate', 'call_method', 'dispose_instance', 'meta'].includes(msg.method) &&
+    (msg.method === 'call' || msg.method === 'meta') &&
     typeof msg.params === 'object' &&
     msg.params !== null
   );

package/src/runtime/validators.ts

@@ -1,3 +1,5 @@
+import { BridgeValidationError } from './errors.js';
+
 /**
  * Pure validation functions for runtime value checking.
  *
@@ -15,6 +17,208 @@ export class ValidationError extends Error {
   }
 }
 
+/** A serializable return-contract description emitted by the code generator. */
+export type ReturnSchema =
+  | { kind: 'any' }
+  | {
+      kind: 'primitive';
+      type: 'number' | 'string' | 'boolean' | 'null' | 'undefined' | 'Uint8Array' | 'object';
+    }
+  | { kind: 'literal'; value: string | number | boolean | null }
+  | { kind: 'array'; element: ReturnSchema }
+  | { kind: 'tuple'; elements: ReturnSchema[] }
+  | {
+      kind: 'record';
+      fields?: Record<string, { schema: ReturnSchema; optional?: boolean }>;
+      values?: ReturnSchema;
+    }
+  | { kind: 'union'; options: ReturnSchema[] }
+  | { kind: 'ref'; name: string }
+  | { kind: 'marker'; marker: 'dataframe' | 'series' | 'ndarray'; dims?: number; dtype?: string };
+
+export type ReturnValidator<T = unknown> = (result: T) => T;
+
+export interface DecodedShapeMetadata {
+  marker: 'dataframe' | 'series' | 'ndarray';
+  dims?: number;
+  dtype?: string;
+}
+
+const decodedShapeMetadata = new WeakMap<object, DecodedShapeMetadata>();
+
+/** @internal Preserve wire provenance after codec decoding changes the JS shape. */
+export function tagDecodedShape<T>(value: T, metadata: DecodedShapeMetadata): T {
+  if (value !== null && (typeof value === 'object' || typeof value === 'function')) {
+    decodedShapeMetadata.set(value as object, metadata);
+  }
+  return value;
+}
+
+function isObjectLike(value: unknown): value is object {
+  return value !== null && (typeof value === 'object' || typeof value === 'function');
+}
+
+/** A short, bounded description suitable for an error message. */
+export function describeReceivedShape(value: unknown): string {
+  if (value === null) {
+    return 'null';
+  }
+  if (value === undefined) {
+    return 'undefined';
+  }
+  if (value instanceof Uint8Array) {
+    return `Uint8Array(${value.byteLength})`;
+  }
+  if (Array.isArray(value)) {
+    return `array(${value.length})`;
+  }
+  if (typeof value === 'object') {
+    const marker = decodedShapeMetadata.get(value);
+    if (marker) {
+      const details = [marker.dims === undefined ? undefined : `${marker.dims}d`, marker.dtype]
+        .filter(Boolean)
+        .join(', ');
+      return `${marker.marker}${details ? ` (${details})` : ''}`;
+    }
+    const name = (value as { constructor?: { name?: unknown } }).constructor?.name;
+    return typeof name === 'string' && name !== 'Object' ? name : 'object';
+  }
+  return typeof value;
+}
+
+function renderSchema(schema: ReturnSchema): string {
+  switch (schema.kind) {
+    case 'any':
+      return 'unknown';
+    case 'primitive':
+      return schema.type;
+    case 'literal':
+      return JSON.stringify(schema.value);
+    case 'array':
+      return `${renderSchema(schema.element)}[]`;
+    case 'tuple':
+      return `[${schema.elements.map(renderSchema).join(', ')}]`;
+    case 'record':
+      return 'record';
+    case 'union':
+      return schema.options.map(renderSchema).join(' | ');
+    case 'ref':
+      return schema.name;
+    case 'marker':
+      return schema.marker;
+  }
+}
+
+interface CheckState {
+  readonly definitions: Readonly<Record<string, ReturnSchema>>;
+  readonly pairs: WeakMap<object, Set<string>>;
+}
+
+function check(schema: ReturnSchema, value: unknown, state: CheckState): boolean {
+  if (schema.kind === 'any') {
+    return true;
+  }
+
+  if (schema.kind === 'ref') {
+    const definition = state.definitions[schema.name];
+    if (!definition) {
+      return true;
+    } // unresolved/erased types deliberately degrade to unknown.
+    if (isObjectLike(value)) {
+      const seen = state.pairs.get(value) ?? new Set<string>();
+      if (seen.has(schema.name)) {
+        return true;
+      }
+      seen.add(schema.name);
+      state.pairs.set(value, seen);
+    }
+    return check(definition, value, state);
+  }
+
+  switch (schema.kind) {
+    case 'primitive':
+      if (schema.type === 'null') {
+        return value === null;
+      }
+      if (schema.type === 'undefined') {
+        return value === undefined;
+      }
+      if (schema.type === 'Uint8Array') {
+        return value instanceof Uint8Array;
+      }
+      if (schema.type === 'object') {
+        return isPlainObject(value);
+      }
+      return typeof value === schema.type;
+    case 'literal':
+      return Object.is(value, schema.value);
+    case 'array':
+      return Array.isArray(value) && value.every(item => check(schema.element, item, state));
+    case 'tuple':
+      return (
+        Array.isArray(value) &&
+        value.length === schema.elements.length &&
+        schema.elements.every((entry, index) => check(entry, value[index], state))
+      );
+    case 'record': {
+      if (!isPlainObject(value)) {
+        return false;
+      }
+      if (schema.fields) {
+        for (const [key, field] of Object.entries(schema.fields)) {
+          if (!(key in value)) {
+            if (field.optional) {
+              continue;
+            }
+            return false;
+          }
+          if (!check(field.schema, value[key], state)) {
+            return false;
+          }
+        }
+      }
+      return (
+        !schema.values ||
+        Object.values(value).every(item => check(schema.values as ReturnSchema, item, state))
+      );
+    }
+    case 'union':
+      return schema.options.some(option => check(option, value, state));
+    case 'marker': {
+      const metadata = isObjectLike(value) ? decodedShapeMetadata.get(value) : undefined;
+      if (metadata?.marker !== schema.marker) {
+        return false;
+      }
+      return (
+        (schema.dims === undefined || metadata.dims === schema.dims) &&
+        (schema.dtype === undefined || metadata.dtype === schema.dtype)
+      );
+    }
+  }
+}
+
+/**
+ * Construct a cycle-safe structural validator for one generated callable.
+ * Unknown/Any/void schemas intentionally validate nothing.
+ */
+export function createReturnValidator<T = unknown>(
+  schema: ReturnSchema,
+  callSite: string,
+  definitions: Readonly<Record<string, ReturnSchema>> = {}
+): ReturnValidator<T> {
+  const declaredType = renderSchema(schema);
+  return (result: T): T => {
+    if (!check(schema, result, { definitions, pairs: new WeakMap<object, Set<string>>() })) {
+      throw new BridgeValidationError({
+        declaredType,
+        receivedShape: describeReceivedShape(result),
+        callSite,
+      });
+    }
+    return result;
+  };
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 // TYPE GUARDS
 // ═══════════════════════════════════════════════════════════════════════════

package/src/types/index.ts

@@ -13,6 +13,13 @@ export interface PythonModule {
   exports: string[];
 }
 
+/** A pinned, versioned JSON IR artifact emitted alongside generated wrappers. */
+export interface IrContract {
+  ir_version: string;
+  module: string;
+  [key: string]: unknown;
+}
+
 /**
  * How a callable is bound on its owning class.
  *
@@ -261,7 +268,8 @@ export interface TSPrimitiveType {
     | 'void'
     | 'unknown'
     | 'never'
-    | 'object';
+    | 'object'
+    | 'Uint8Array';
 }
 
 export interface TSArrayType {
@@ -314,6 +322,7 @@ export interface TSParameter {
 export interface TSGenericType {
   kind: 'generic';
   name: string;
+  module?: string;
   typeArgs: TypescriptType[];
 }
 
@@ -338,6 +347,11 @@ export interface TywrapOptions {
    * and discovery (IR extraction). Useful for local modules not installed in site-packages.
    */
   pythonImportPath?: string[];
+  /**
+   * Read one pinned IR contract instead of spawning Python. A string applies to
+   * every configured module; a record selects a contract path per module.
+   */
+  contractInput?: string | Record<string, string>;
   output: OutputConfig;
   runtime: RuntimeConfig;
   performance: PerformanceConfig;
@@ -404,6 +418,8 @@ export interface PerformanceConfig {
   compression: 'auto' | 'gzip' | 'brotli' | 'none';
 }
 
+// `numpy` is intentionally accepted as a no-op in 0.9: decoded ndarrays are JS
+// arrays, and a faithful static shape awaits #268 return validation.
 export type TypePreset = 'numpy' | 'pandas' | 'pydantic' | 'stdlib' | 'scipy' | 'torch' | 'sklearn';
 
 export interface TypeMappingConfig {
@@ -413,25 +429,6 @@ export interface TypeMappingConfig {
 /** Known bridge backends. Each speaks the identical "tywrap/1" protocol. */
 export type BridgeBackend = 'python-subprocess' | 'pyodide' | 'http';
 
-/**
- * Optional chunked-transport negotiation block in {@link BridgeInfo}.
- *
- * Reported by a bridge that understands the `tywrap-frame/1` framing protocol
- * (subprocess only, 0.8.0). It lets the JS side learn, via the `meta` probe,
- * whether the bridge can reassemble chunked frames and the maximum single-frame
- * size it will accept. Absent on old bridges (and on HTTP/Pyodide, which stay
- * single-frame in 0.8.0) — absence means "no chunking", which is backward
- * compatible. See docs/transport-framing.md.
- */
-export interface BridgeTransportInfo {
-  /** Framing protocol the bridge speaks (e.g. `'tywrap-frame/1'`). */
-  frameProtocol: string;
-  /** Whether the bridge can fragment/reassemble chunked frames. */
-  supportsChunking: boolean;
-  /** Maximum size, in bytes, of a single wire frame the bridge will accept. */
-  maxFrameBytes: number;
-}
-
 export interface BridgeInfo {
   protocol: string;
   protocolVersion: number;
@@ -445,12 +442,6 @@ export interface BridgeInfo {
   torchAvailable: boolean;
   sklearnAvailable: boolean;
   instances: number;
-  /**
-   * Optional chunked-transport negotiation block. Present only when the bridge
-   * advertises `tywrap-frame/1` framing; absent on old bridges and on
-   * HTTP/Pyodide (single-frame in 0.8.0). See {@link BridgeTransportInfo}.
-   */
-  transport?: BridgeTransportInfo;
 }
 
 // Analysis and generation results
@@ -499,7 +490,7 @@ export interface GenerationMetadata {
   optimizations: string[];
 }
 
-// PythonRuntime — the four cross-boundary RPC methods generated wrappers call.
+// PythonRuntime — the call-only cross-boundary RPC method 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
@@ -511,45 +502,15 @@ export interface PythonRuntime {
     module: string,
     functionName: string,
     args: unknown[],
-    kwargs?: Record<string, unknown>
+    kwargs?: Record<string, unknown>,
+    validate?: (result: T) => void
   ): Promise<T>;
-
-  instantiate<T = unknown>(
-    module: string,
-    className: string,
-    args: unknown[],
-    kwargs?: Record<string, unknown>
-  ): Promise<T>;
-
-  callMethod<T = unknown>(
-    handle: string,
-    methodName: string,
-    args: unknown[],
-    kwargs?: Record<string, unknown>
-  ): Promise<T>;
-
-  disposeInstance(handle: string): Promise<void>;
 }
 
-// Runtime bridge interface — the four RPC methods plus lifecycle dispose().
+// Runtime bridge interface — the call RPC method 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>;
 }
-
-// Utility types
-export type DeepReadonly<T> = {
-  readonly [P in keyof T]: T[P] extends object ? DeepReadonly<T[P]> : T[P];
-};
-
-export type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
-
-export type RequiredKeys<T> = {
-  [K in keyof T]-?: {} extends Pick<T, K> ? never : K;
-}[keyof T];
-
-export type OptionalKeys<T> = {
-  [K in keyof T]-?: {} extends Pick<T, K> ? K : never;
-}[keyof T];