tywrap 0.6.1 → 0.8.0

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
 // =============================================================================
@@ -102,6 +124,142 @@ 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
+// =============================================================================
+
+/**
+ * Static, transport-level capability descriptor.
+ *
+ * Each backend exposes one of these via {@link Transport.capabilities} so callers
+ * can reason about what the wire channel can carry WITHOUT round-tripping to
+ * Python. These flags describe the transport itself (what bytes it can move and
+ * how it frames them) — they are deliberately separate from the bridge's runtime
+ * `meta` report ({@link BridgeInfo}), which describes the *Python environment*
+ * (which optional libraries happen to be importable). The transport descriptor is
+ * 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.
+ * 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. */
+  readonly backend: 'subprocess' | 'http' | 'pyodide';
+
+  /**
+   * Whether the transport can carry Arrow-encoded payloads (binary IPC frames)
+   * on the wire. Pyodide is JSON-only (pyarrow is unavailable in WASM), so it is
+   * `false` there; subprocess and HTTP can move Arrow bytes.
+   */
+  readonly supportsArrow: boolean;
+
+  /**
+   * Whether the transport can carry arbitrary binary data (e.g. Python `bytes`).
+   * All current backends carry binary via base64 envelopes, so this is `true`
+   * everywhere.
+   */
+  readonly supportsBinary: boolean;
+
+  /**
+   * 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`.
+   */
+  readonly supportsChunking: boolean;
+
+  /**
+   * Whether the transport can stream incremental results for a single request.
+   * Not implemented on any backend yet (planned for 0.8.0) — always `false`.
+   */
+  readonly supportsStreaming: boolean;
+
+  /**
+   * 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.
+   */
+  readonly maxFrameBytes: number;
+}
+
 // =============================================================================
 // TRANSPORT INTERFACE
 // =============================================================================
@@ -177,6 +335,16 @@ export interface Transport extends Disposable {
    * Returns `false` in all other states.
    */
   readonly isReady: boolean;
+
+  /**
+   * Static, transport-level capability descriptor.
+   *
+   * Returns what this transport can carry and how it frames messages, with
+   * honest values for the transport's current behavior (see
+   * {@link TransportCapabilities}). It does NOT depend on lifecycle state — it is
+   * safe to call before `init()` and after `dispose()`.
+   */
+  capabilities(): TransportCapabilities;
 }
 
 // =============================================================================
@@ -228,6 +396,7 @@ export function isTransport(value: unknown): value is Transport {
     typeof (value as Transport).init === 'function' &&
     typeof (value as Transport).send === 'function' &&
     typeof (value as Transport).dispose === 'function' &&
+    typeof (value as Transport).capabilities === 'function' &&
     'isReady' in value
   );
 }

package/src/types/index.ts

@@ -13,6 +13,16 @@ export interface PythonModule {
   exports: string[];
 }
 
+/**
+ * How a callable is bound on its owning class.
+ *
+ * Mirrors `IRFunction.method_kind` from the Python IR (tywrap_ir 0.3.0):
+ * `'instance'` (default, keeps `self`), `'class'` (keeps `cls`), or
+ * `'static'` (no implicit first parameter). Module-level functions retain the
+ * `'instance'` default; it is only meaningful for class members.
+ */
+export type PythonMethodKind = 'instance' | 'class' | 'static';
+
 export interface PythonFunction {
   name: string;
   signature: FunctionSignature;
@@ -23,6 +33,28 @@ export interface PythonFunction {
   typeParameters?: PythonGenericParameter[];
   returnType: PythonType;
   parameters: Parameter[];
+  /**
+   * Binding of this callable on its owning class. Defaults to `'instance'`.
+   * @see PythonMethodKind
+   */
+  methodKind?: PythonMethodKind;
+}
+
+/**
+ * A `@property` or `functools.cached_property` exposed on a class.
+ *
+ * Mirrors `IRAccessor` from the Python IR (tywrap_ir 0.3.0). Distinct from
+ * {@link PythonClass.properties} (which model TypedDict/NamedTuple/dataclass
+ * data shapes): accessors are computed attributes backed by a getter.
+ */
+export interface PythonAccessor {
+  name: string;
+  type: PythonType;
+  docstring?: string;
+  /** True when there is no setter. `undefined` when undeterminable. */
+  readOnly?: boolean;
+  /** True for `functools.cached_property`. */
+  isCached: boolean;
 }
 
 export interface PythonClass {
@@ -30,6 +62,11 @@ export interface PythonClass {
   bases: string[];
   methods: PythonFunction[];
   properties: Property[];
+  /**
+   * `@property` / `functools.cached_property` accessors, emitted as TS getters.
+   * @see PythonAccessor
+   */
+  accessors?: PythonAccessor[];
   docstring?: string;
   decorators: string[];
   kind?: 'class' | 'protocol' | 'typed_dict' | 'namedtuple' | 'dataclass' | 'pydantic';
@@ -376,6 +413,25 @@ 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;
@@ -389,6 +445,12 @@ 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