tywrap 0.7.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

@@ -26,6 +26,28 @@ export const PROTOCOL_ID = 'tywrap/1';
  */
 export const TYWRAP_PROTOCOL_VERSION = Number.parseInt(PROTOCOL_ID.split('/')[1] ?? '', 10);
 
+/**
+ * Framing protocol identifier for chunked large-payload transport.
+ *
+ * This is DISTINCT from {@link PROTOCOL_ID}: the logical RPC stays `tywrap/1`,
+ * while `tywrap-frame/1` describes a separate layer (below {@link Transport.send})
+ * that fragments one logical message across multiple wire frames and reassembles
+ * it. An old bridge rejects any non-`tywrap/1` request, so the logical protocol
+ * must NOT be bumped to negotiate chunking — a separate framing protocol,
+ * advertised through a `tywrap/1` `meta` extension, is used instead.
+ *
+ * Subprocess-only for 0.8.0 (it is the only backend with a real frame ceiling —
+ * the JSONL line-length limit). See docs/transport-framing.md.
+ */
+export const FRAME_PROTOCOL_ID = 'tywrap-frame/1';
+
+/**
+ * Numeric framing-protocol version. Derived from the trailing number of
+ * {@link FRAME_PROTOCOL_ID} so the two cannot drift — bump FRAME_PROTOCOL_ID
+ * alone and this follows (same pattern as {@link TYWRAP_PROTOCOL_VERSION}).
+ */
+export const FRAME_PROTOCOL_VERSION = Number.parseInt(FRAME_PROTOCOL_ID.split('/')[1] ?? '', 10);
+
 // =============================================================================
 // PROTOCOL TYPES
 // =============================================================================
@@ -35,9 +57,6 @@ export const TYWRAP_PROTOCOL_VERSION = Number.parseInt(PROTOCOL_ID.split('/')[1]
  *
  * 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 {
@@ -48,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[];
 
@@ -102,6 +112,78 @@ export interface ProtocolResponse {
   };
 }
 
+// =============================================================================
+// CHUNK FRAMING (tywrap-frame/1)
+// =============================================================================
+
+/**
+ * Per-frame encoding for a {@link ChunkFrame}'s `data` field.
+ *
+ * - `utf8-slice` (the chosen default for 0.8.0): `data` is a raw substring of the
+ *   complete logical JSON message, split on UTF-8 codepoint boundaries. Because
+ *   the logical payload is already valid-UTF-8 JSON, the slices reassemble by
+ *   simple concatenation — no inflation, no extra decode. See
+ *   docs/transport-framing.md for the rationale (decision #6).
+ * - `utf8-base64`: `data` is a base64-encoded chunk of the UTF-8 bytes, safe for
+ *   arbitrary byte splits but ~33% larger on the wire with a memory-amplification
+ *   cost. Reserved as an alternative; not emitted by tywrap in 0.8.0.
+ */
+export type ChunkFrameEncoding = 'utf8-base64' | 'utf8-slice';
+
+/**
+ * A single wire frame of the `tywrap-frame/1` framing protocol.
+ *
+ * A frame envelope is DISTINCT from the logical {@link ProtocolMessage} /
+ * {@link ProtocolResponse}: it carries a slice of the bytes of ONE complete
+ * logical JSON message (a request or a response), fragmented because the payload
+ * exceeds the transport's frame ceiling. The framing layer reassembles all
+ * frames for a given {@link ChunkFrame.id} back into the single logical message
+ * before the JSON/codec path ever sees it.
+ *
+ * Correlation reuses the existing RPC `id`. `seq` is zero-based; `total` and
+ * `totalBytes` are repeated on every frame so the receiver can validate the
+ * stream is complete (no missing/duplicate `seq`, exact frame count, exact
+ * reassembled byte length) before decoding.
+ *
+ * @see docs/transport-framing.md
+ */
+export interface ChunkFrame {
+  /**
+   * Frame-envelope discriminator.
+   * - `'chunk'`: a normal data-carrying frame.
+   * - `'error'`: a framing-layer error (e.g. the sender could not continue the
+   *   stream); carries no further data frames for this `id`.
+   */
+  __tywrap_frame__: 'chunk' | 'error';
+
+  /** Framing protocol identifier (must equal {@link FRAME_PROTOCOL_ID}). */
+  frameProtocol: string;
+
+  /** Which logical stream this frame belongs to. */
+  stream: 'request' | 'response';
+
+  /** RPC correlation id, shared with the logical {@link ProtocolMessage.id}. */
+  id: number;
+
+  /** Zero-based sequence index of this frame within its stream. */
+  seq: number;
+
+  /** Total number of frames in this stream (repeated on every frame). */
+  total: number;
+
+  /**
+   * Total byte length of the complete reassembled logical message (repeated on
+   * every frame). Used to validate the reassembled payload exactly.
+   */
+  totalBytes: number;
+
+  /** Per-frame payload encoding (see {@link ChunkFrameEncoding}). */
+  encoding: ChunkFrameEncoding;
+
+  /** This frame's slice of the logical message, encoded per {@link encoding}. */
+  data: string;
+}
+
 // =============================================================================
 // TRANSPORT CAPABILITIES
 // =============================================================================
@@ -118,9 +200,11 @@ export interface ProtocolResponse {
  * authoritative for transport-level flags; the meta report is authoritative for
  * library availability.
  *
- * Honest for TODAY's behavior: `supportsChunking` and `supportsStreaming` are
- * `false` on every backend — both are planned for 0.8.0 and no backend implements
- * them yet. See docs/transport-capabilities.md for the full matrix.
+ * `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.
  */
 export interface TransportCapabilities {
   /** Which backend this transport drives. */
@@ -142,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;
 
@@ -157,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;
 }
@@ -228,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.
@@ -320,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 {
@@ -474,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
@@ -486,45 +502,15 @@ export interface PythonRuntime {
     module: string,
     functionName: string,
     args: unknown[],
-    kwargs?: Record<string, unknown>
-  ): Promise<T>;
-
-  instantiate<T = unknown>(
-    module: string,
-    className: string,
-    args: unknown[],
-    kwargs?: Record<string, unknown>
+    kwargs?: Record<string, unknown>,
+    validate?: (result: T) => void
   ): 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];