tywrap 0.5.1 → 0.6.1

package/src/runtime/pyodide-bootstrap-core.generated.ts

@@ -9,4 +9,4 @@
  * Regenerate with: node scripts/generate-pyodide-bootstrap.mjs
  */
 
-export const PYODIDE_BRIDGE_CORE_SOURCE: string = "\"\"\"\nShared tywrap bridge core: protocol dispatch + value (de)serialization.\n\nThis module is the SINGLE source of truth for the \"tywrap/1\" server-side\nprotocol. It is imported by:\n\n  - runtime/python_bridge.py  (the Node/Bun/Deno subprocess server and the HTTP\n    server), which owns I/O concerns: the stdin/stdout JSONL loop, env-var size\n    guards, the real OS pid, bridge='python-subprocess', and the final SafeCodec\n    encode wrapper.\n\n  - the in-WASM Pyodide server (src/runtime/pyodide-io.ts). Pyodide cannot read\n    this file from disk, so it is shipped as a build-time-generated TypeScript\n    string constant (src/runtime/pyodide-bootstrap-core.generated.ts) produced by\n    scripts/generate-pyodide-bootstrap.mjs and exec'd into a module registered in\n    sys.modules. A conformance drift guard (test/runtime_conformance.test.ts)\n    asserts the generated constant stays byte-identical to this file.\n\nCROSS-LANGUAGE CONTRACT (Python <-> the TypeScript decoder in src/utils/codec.ts\nand the request encoder in src/runtime/safe-codec.ts):\n\n  * Every value-type \"marker\" envelope carries {'__tywrap__': <type>,\n    'codecVersion': 1, 'encoding': ...}. The 6 markers are: ndarray, dataframe,\n    series, scipy.sparse, torch.tensor, sklearn.estimator.\n  * bytes round-trip both ways via base64 envelopes (see _deserialize_bytes_*\n    and the bytes branch of default_encoder).\n  * NaN/Infinity are rejected (the JS client cannot parse the non-standard tokens\n    that allow_nan=True would emit).\n\nPURITY: This module depends only on the standard library plus LAZY optional\nimports (numpy/pandas/scipy/torch/sklearn/pyarrow are each imported inside the\nfunction that needs them). It performs no stdin/stdout I/O and reads no env vars,\nso it runs unchanged under CPython-in-WASM (Pyodide).\n\nforce_json_markers: a *parameter* threaded through every serializer (including\nthe nested torch.tensor -> ndarray call). When True, ndarray/dataframe/series are\nforced down their JSON path regardless of pyarrow availability. Pyodide passes\nTrue (Arrow is unavailable in WASM); the subprocess server passes the boolean\nderived from TYWRAP_CODEC_FALLBACK=json so that \"Node in json-fallback mode\" and\n\"Pyodide\" produce byte-identical marker envelopes.\n\"\"\"\n\nimport base64\nimport datetime as dt\nimport decimal\nimport importlib\nimport importlib.util\nimport json\nimport math\nimport traceback\nimport uuid\nfrom pathlib import Path, PurePath\n\n# Protocol constants. These MUST match src/runtime/protocol.ts (PROTOCOL_ID,\n# TYWRAP_PROTOCOL_VERSION) and the codec version baked into marker envelopes.\nPROTOCOL = 'tywrap/1'\nPROTOCOL_VERSION = 1\nCODEC_VERSION = 1\n\n\nclass ProtocolError(Exception):\n    \"\"\"Raised for malformed requests (bad protocol/id/method/params).\"\"\"\n\n\nclass InstanceHandleError(ValueError):\n    \"\"\"Raised when an instance handle is unknown or no longer valid.\"\"\"\n\n\nclass CodecError(Exception):\n    \"\"\"Raised when value encoding fails (e.g. NaN/Infinity not allowed).\"\"\"\n\n\n# =============================================================================\n# REQUEST-SIDE DESERIALIZATION (bytes envelopes -> Python bytes)\n# =============================================================================\n\n_NO_DESERIALIZE = object()\n_ERR_BYTES_MISSING_B64 = 'Invalid bytes envelope: missing b64'\n_ERR_BYTES_MISSING_DATA = 'Invalid bytes envelope: missing data'\n_ERR_BYTES_INVALID_BASE64 = 'Invalid bytes envelope: invalid base64'\n\n\ndef _deserialize_bytes_envelope(value):\n    \"\"\"\n    Decode base64-encoded bytes envelopes from JS into Python bytes.\n\n    Supported shapes:\n    - { \"__tywrap_bytes__\": true, \"b64\": \"...\" }  (JS SafeCodec.encodeRequest)\n    - { \"__type__\": \"bytes\", \"encoding\": \"base64\", \"data\": \"...\" }  (legacy/compat)\n\n    Why: TS SafeCodec encodes Uint8Array/ArrayBuffer as base64 objects, but\n    Python handlers expect real bytes/bytearray to preserve behavior (e.g., len()).\n    \"\"\"\n    if not isinstance(value, dict):\n        return _NO_DESERIALIZE\n\n    if value.get('__tywrap_bytes__') is True:\n        b64 = value.get('b64')\n        if not isinstance(b64, str):\n            raise ProtocolError(_ERR_BYTES_MISSING_B64)\n        try:\n            return base64.b64decode(b64, validate=True)\n        except Exception as exc:\n            raise ProtocolError(_ERR_BYTES_INVALID_BASE64) from exc\n\n    if value.get('__type__') == 'bytes' and value.get('encoding') == 'base64':\n        data = value.get('data')\n        if not isinstance(data, str):\n            raise ProtocolError(_ERR_BYTES_MISSING_DATA)\n        try:\n            return base64.b64decode(data, validate=True)\n        except Exception as exc:\n            raise ProtocolError(_ERR_BYTES_INVALID_BASE64) from exc\n\n    return _NO_DESERIALIZE\n\n\ndef deserialize(value):\n    \"\"\"\n    Recursively deserialize request values into Python-native types.\n\n    Why: requests are JSON-only; we need a small set of explicit decoders\n    (currently bytes) to restore Python semantics at the boundary.\n    \"\"\"\n    decoded = _deserialize_bytes_envelope(value)\n    if decoded is not _NO_DESERIALIZE:\n        return decoded\n\n    if isinstance(value, list):\n        return [deserialize(item) for item in value]\n    if isinstance(value, dict):\n        # Preserve dict shape while decoding nested values.\n        return {k: deserialize(v) for k, v in value.items()}\n    return value\n\n\n# =============================================================================\n# CAPABILITY DETECTION (lazy, best-effort)\n# =============================================================================\n\ndef arrow_available():\n    \"\"\"Return True when pyarrow can be imported.\"\"\"\n    try:\n        import pyarrow  # noqa: F401\n    except (ImportError, OSError):\n        return False\n    return True\n\n\ndef module_available(module_name):\n    \"\"\"\n    Lightweight feature detection for optional codec dependencies via find_spec.\n\n    Why: exposes availability in bridge metadata without importing heavy modules.\n    \"\"\"\n    try:\n        return importlib.util.find_spec(module_name) is not None\n    except (ImportError, AttributeError, TypeError, ValueError):\n        return False\n\n\ndef is_numpy_array(obj):\n    try:\n        import numpy as np  # noqa: F401\n    except Exception:\n        return False\n    return isinstance(obj, np.ndarray)\n\n\ndef is_pandas_dataframe(obj):\n    try:\n        import pandas as pd  # noqa: F401\n    except Exception:\n        return False\n    return isinstance(obj, pd.DataFrame)\n\n\ndef is_pandas_series(obj):\n    try:\n        import pandas as pd  # noqa: F401\n    except Exception:\n        return False\n    return isinstance(obj, pd.Series)\n\n\ndef is_scipy_sparse(obj):\n    try:\n        import scipy.sparse as sp  # noqa: F401\n    except Exception:\n        return False\n    try:\n        return sp.issparse(obj)\n    except Exception:\n        return False\n\n\ndef is_torch_tensor(obj):\n    try:\n        import torch  # noqa: F401\n    except Exception:\n        return False\n    try:\n        return torch.is_tensor(obj)\n    except Exception:\n        return False\n\n\ndef is_sklearn_estimator(obj):\n    try:\n        from sklearn.base import BaseEstimator  # noqa: F401\n    except Exception:\n        return False\n    return isinstance(obj, BaseEstimator)\n\n\n# =============================================================================\n# MARKER SERIALIZERS (6 __tywrap__ value types)\n# =============================================================================\n#\n# Each serializer accepts force_json_markers. When True, the Arrow path is never\n# taken (used by Pyodide and by the subprocess server in TYWRAP_CODEC_FALLBACK=json\n# mode). The JSON fallback envelopes are byte-identical across both callers, which\n# is what the conformance suite asserts.\n\ndef serialize_ndarray(obj, *, force_json_markers):\n    \"\"\"\n    Encode a NumPy ndarray. Arrow IPC (compact, lossless) by default; JSON when\n    force_json_markers is set or pyarrow is unavailable in fallback mode.\n\n    Note: pa.array() only handles 1D arrays; multi-dimensional arrays are\n    flattened with shape metadata for JS-side reconstruction. See\n    https://github.com/apache/arrow-js/issues/115\n    \"\"\"\n    if force_json_markers:\n        return serialize_ndarray_json(obj)\n    try:\n        import pyarrow as pa  # type: ignore\n    except Exception as exc:\n        raise RuntimeError(\n            'Arrow encoding unavailable for ndarray; install pyarrow or set TYWRAP_CODEC_FALLBACK=json to enable JSON fallback'\n        ) from exc\n    try:\n        original_shape = list(obj.shape) if hasattr(obj, 'shape') else None\n        flat = obj.flatten() if hasattr(obj, 'ndim') and obj.ndim > 1 else obj\n        arr = pa.array(flat)\n        table = pa.Table.from_arrays([arr], names=['value'])\n        sink = pa.BufferOutputStream()\n        with pa.ipc.new_stream(sink, table.schema) as writer:\n            writer.write_table(table)\n        buf = sink.getvalue()\n        b64 = base64.b64encode(buf.to_pybytes()).decode('ascii')\n        return {\n            '__tywrap__': 'ndarray',\n            'codecVersion': CODEC_VERSION,\n            'encoding': 'arrow',\n            'b64': b64,\n            'shape': original_shape,\n            'dtype': str(obj.dtype) if hasattr(obj, 'dtype') else None,\n        }\n    except Exception as exc:\n        raise RuntimeError('Arrow encoding failed for ndarray') from exc\n\n\ndef serialize_ndarray_json(obj):\n    \"\"\"JSON fallback for ndarray (larger payloads, potential dtype loss).\"\"\"\n    try:\n        data = obj.tolist()\n    except Exception as exc:\n        raise RuntimeError('JSON fallback failed for ndarray') from exc\n    return {\n        '__tywrap__': 'ndarray',\n        'codecVersion': CODEC_VERSION,\n        'encoding': 'json',\n        'data': data,\n        'shape': getattr(obj, 'shape', None),\n    }\n\n\ndef serialize_dataframe(obj, *, force_json_markers):\n    \"\"\"\n    Encode a pandas DataFrame. Feather/Arrow-IPC (uncompressed, so apache-arrow\n    in JS can read it) by default; JSON when force_json_markers is set.\n    \"\"\"\n    if force_json_markers:\n        return serialize_dataframe_json(obj)\n    try:\n        import pyarrow as pa  # type: ignore\n        import pyarrow.feather as feather  # type: ignore\n    except Exception as exc:\n        raise RuntimeError(\n            'Arrow encoding unavailable for pandas.DataFrame; install pyarrow or set TYWRAP_CODEC_FALLBACK=json to enable JSON fallback'\n        ) from exc\n    try:\n        table = pa.Table.from_pandas(obj)  # type: ignore\n        sink = pa.BufferOutputStream()\n        feather.write_feather(table, sink, compression='uncompressed')\n        buf = sink.getvalue()\n        b64 = base64.b64encode(buf.to_pybytes()).decode('ascii')\n        return {\n            '__tywrap__': 'dataframe',\n            'codecVersion': CODEC_VERSION,\n            'encoding': 'arrow',\n            'b64': b64,\n        }\n    except Exception as exc:\n        raise RuntimeError('Arrow encoding failed for pandas.DataFrame') from exc\n\n\ndef serialize_dataframe_json(obj):\n    \"\"\"JSON fallback for DataFrame: records orientation.\"\"\"\n    try:\n        data = obj.to_dict(orient='records')\n    except Exception as exc:\n        raise RuntimeError('JSON fallback failed for pandas.DataFrame') from exc\n    return {\n        '__tywrap__': 'dataframe',\n        'codecVersion': CODEC_VERSION,\n        'encoding': 'json',\n        'data': data,\n    }\n\n\ndef serialize_series(obj, *, force_json_markers):\n    \"\"\"\n    Encode a pandas Series as a single-column Arrow Table stream (the JS decoder\n    contract is \"table-like\"); JSON when force_json_markers is set.\n    \"\"\"\n    if force_json_markers:\n        return serialize_series_json(obj)\n    try:\n        import pyarrow as pa  # type: ignore\n    except Exception as exc:\n        raise RuntimeError(\n            'Arrow encoding unavailable for pandas.Series; install pyarrow or set TYWRAP_CODEC_FALLBACK=json to enable JSON fallback'\n        ) from exc\n    try:\n        arr = pa.Array.from_pandas(obj)  # type: ignore\n        table = pa.Table.from_arrays([arr], names=['value'])\n        sink = pa.BufferOutputStream()\n        with pa.ipc.new_stream(sink, table.schema) as writer:\n            writer.write_table(table)\n        buf = sink.getvalue()\n        b64 = base64.b64encode(buf.to_pybytes()).decode('ascii')\n        return {\n            '__tywrap__': 'series',\n            'codecVersion': CODEC_VERSION,\n            'encoding': 'arrow',\n            'b64': b64,\n            'name': getattr(obj, 'name', None),\n        }\n    except Exception as exc:\n        raise RuntimeError('Arrow encoding failed for pandas.Series') from exc\n\n\ndef serialize_series_json(obj):\n    \"\"\"JSON fallback for Series (potentially lossy dtype/NA representation).\"\"\"\n    try:\n        data = obj.to_list()  # type: ignore\n    except Exception:\n        try:\n            data = obj.to_dict()  # type: ignore\n        except Exception as exc:\n            raise RuntimeError('JSON fallback failed for pandas.Series') from exc\n    return {\n        '__tywrap__': 'series',\n        'codecVersion': CODEC_VERSION,\n        'encoding': 'json',\n        'data': data,\n        'name': getattr(obj, 'name', None),\n    }\n\n\ndef serialize_sparse_matrix(obj):\n    \"\"\"\n    Serialize scipy sparse matrices into structured JSON envelopes (json-only;\n    there is no Arrow path). Preserves sparsity; rejects unsupported formats and\n    complex dtypes explicitly.\n    \"\"\"\n    try:\n        fmt = obj.getformat()\n    except Exception as exc:\n        raise RuntimeError('Failed to inspect scipy sparse matrix format') from exc\n\n    if fmt not in ('csr', 'csc', 'coo'):\n        raise RuntimeError(f'Unsupported scipy sparse format: {fmt}')\n\n    dtype = None\n    try:\n        dtype = str(obj.dtype)\n    except Exception:\n        dtype = None\n    if getattr(obj.dtype, 'kind', None) == 'c':\n        raise RuntimeError('Complex sparse matrices are not supported by JSON codec')\n\n    if fmt in ('csr', 'csc'):\n        data = obj.data.tolist()\n        indices = obj.indices.tolist()\n        indptr = obj.indptr.tolist()\n        return {\n            '__tywrap__': 'scipy.sparse',\n            'codecVersion': CODEC_VERSION,\n            'encoding': 'json',\n            'format': fmt,\n            'shape': list(obj.shape),\n            'data': data,\n            'indices': indices,\n            'indptr': indptr,\n            'dtype': dtype,\n        }\n\n    # coo\n    data = obj.data.tolist()\n    row = obj.row.tolist()\n    col = obj.col.tolist()\n    return {\n        '__tywrap__': 'scipy.sparse',\n        'codecVersion': CODEC_VERSION,\n        'encoding': 'json',\n        'format': fmt,\n        'shape': list(obj.shape),\n        'data': data,\n        'row': row,\n        'col': col,\n        'dtype': dtype,\n    }\n\n\ndef serialize_torch_tensor(obj, *, force_json_markers, torch_allow_copy=False):\n    \"\"\"\n    Serialize torch.Tensor values via the nested ndarray envelope. CPU-only by\n    default; device/copy behavior is explicit. force_json_markers is threaded\n    into the nested ndarray serialization so Pyodide gets a JSON ndarray value.\n    \"\"\"\n    tensor = obj.detach()\n    if getattr(tensor, 'device', None) is not None and tensor.device.type != 'cpu':\n        if not torch_allow_copy:\n            raise RuntimeError(\n                'Torch tensor is on a non-CPU device; set TYWRAP_TORCH_ALLOW_COPY=1 to allow CPU transfer'\n            )\n        tensor = tensor.to('cpu')\n    if hasattr(tensor, 'is_contiguous') and not tensor.is_contiguous():\n        if not torch_allow_copy:\n            raise RuntimeError(\n                'Torch tensor is not contiguous; set TYWRAP_TORCH_ALLOW_COPY=1 to allow contiguous copy'\n            )\n        tensor = tensor.contiguous()\n    try:\n        arr = tensor.numpy()\n    except Exception as exc:\n        raise RuntimeError('Failed to convert torch.Tensor to numpy') from exc\n\n    return {\n        '__tywrap__': 'torch.tensor',\n        'codecVersion': CODEC_VERSION,\n        'encoding': 'ndarray',\n        'value': serialize_ndarray(arr, force_json_markers=force_json_markers),\n        'shape': list(tensor.shape),\n        'dtype': str(tensor.dtype),\n        'device': str(tensor.device),\n    }\n\n\ndef serialize_sklearn_estimator(obj):\n    \"\"\"Serialize sklearn estimators as metadata only (json-only); no pickling.\"\"\"\n    try:\n        import sklearn  # noqa: F401\n    except Exception as exc:\n        raise RuntimeError('scikit-learn is not available') from exc\n\n    params = obj.get_params(deep=False)\n    try:\n        json.dumps(params)\n    except Exception as exc:\n        raise RuntimeError(\n            'scikit-learn estimator params are not JSON-serializable; avoid returning estimators or sanitize params'\n        ) from exc\n\n    return {\n        '__tywrap__': 'sklearn.estimator',\n        'codecVersion': CODEC_VERSION,\n        'encoding': 'json',\n        'className': obj.__class__.__name__,\n        'module': obj.__class__.__module__,\n        'version': getattr(sklearn, '__version__', None),\n        'params': params,\n    }\n\n\n_NO_PYDANTIC = object()\n\n\ndef serialize_pydantic(obj):\n    \"\"\"\n    Serialize Pydantic v2 models via model_dump(by_alias=True, mode='json')\n    without importing Pydantic. Returns _NO_PYDANTIC when obj is not a model.\n    \"\"\"\n    model_dump = getattr(obj, 'model_dump', None)\n    if not callable(model_dump):\n        return _NO_PYDANTIC\n    try:\n        try:\n            return model_dump(by_alias=True, mode='json')\n        except TypeError:\n            # Older Pydantic versions may not support `mode=...`.\n            return model_dump(by_alias=True)\n    except Exception as exc:\n        raise RuntimeError(f'model_dump failed: {exc}') from exc\n\n\ndef serialize_stdlib(obj):\n    \"\"\"Coerce common stdlib scalar types to JSON-safe forms; None otherwise.\"\"\"\n    if isinstance(obj, dt.datetime):\n        return obj.isoformat()\n    if isinstance(obj, dt.date):\n        return obj.isoformat()\n    if isinstance(obj, dt.time):\n        return obj.isoformat()\n    if isinstance(obj, dt.timedelta):\n        return obj.total_seconds()\n    if isinstance(obj, decimal.Decimal):\n        return str(obj)\n    if isinstance(obj, uuid.UUID):\n        return str(obj)\n    if isinstance(obj, (Path, PurePath)):\n        return str(obj)\n    return None\n\n\ndef serialize(obj, *, force_json_markers, torch_allow_copy=False):\n    \"\"\"\n    Top-level result serializer. Dispatch order is significant: numpy ndarray ->\n    dataframe -> series -> scipy.sparse -> torch -> sklearn -> Pydantic -> stdlib\n    -> passthrough. The remaining SafeCodec value behaviors (numpy/pandas scalars,\n    bytes, sets, complex rejection, NaN/Infinity) are applied later during JSON\n    encoding by default_encoder.\n    \"\"\"\n    if is_numpy_array(obj):\n        return serialize_ndarray(obj, force_json_markers=force_json_markers)\n    if is_pandas_dataframe(obj):\n        return serialize_dataframe(obj, force_json_markers=force_json_markers)\n    if is_pandas_series(obj):\n        return serialize_series(obj, force_json_markers=force_json_markers)\n    if is_scipy_sparse(obj):\n        return serialize_sparse_matrix(obj)\n    if is_torch_tensor(obj):\n        return serialize_torch_tensor(\n            obj, force_json_markers=force_json_markers, torch_allow_copy=torch_allow_copy\n        )\n    if is_sklearn_estimator(obj):\n        return serialize_sklearn_estimator(obj)\n    pydantic_value = serialize_pydantic(obj)\n    if pydantic_value is not _NO_PYDANTIC:\n        return pydantic_value\n    stdlib_value = serialize_stdlib(obj)\n    if stdlib_value is not None:\n        return stdlib_value\n    return obj\n\n\n# =============================================================================\n# JSON ENCODE: SafeCodec-equivalent value handling (NaN reject, scalars, bytes)\n# =============================================================================\n#\n# This mirrors SafeCodec._default_encoder (runtime/safe_codec.py) for the VALUE\n# behaviors that are part of the wire contract. The subprocess server still uses\n# the real SafeCodec for its final encode (it also enforces size limits); this\n# core encoder exists so the Pyodide server gets identical value handling without\n# depending on safe_codec.py. The conformance suite asserts these behaviors match.\n\ndef _is_nan_or_inf(value):\n    if not isinstance(value, (int, float)):\n        return False\n    try:\n        return math.isnan(value) or math.isinf(value)\n    except (TypeError, ValueError):\n        return False\n\n\ndef _is_numpy_scalar(obj):\n    try:\n        import numpy as np\n    except ImportError:\n        return False\n    return isinstance(obj, (np.generic, np.ndarray)) and obj.ndim == 0\n\n\ndef _is_pandas_scalar(obj):\n    try:\n        import pandas as pd\n    except ImportError:\n        return False\n    return isinstance(obj, (pd.Timestamp, pd.Timedelta, type(pd.NaT)))\n\n\ndef make_default_encoder(*, allow_nan):\n    \"\"\"\n    Build a json.dumps default= encoder matching SafeCodec's value handling.\n\n    Raises CodecError for NaN/Infinity extracted from numpy scalars (json.dumps\n    itself rejects top-level/nested NaN/Infinity floats when allow_nan=False).\n    \"\"\"\n\n    def default_encoder(obj):\n        # numpy/pandas scalars first (need .item() extraction).\n        if _is_numpy_scalar(obj):\n            extracted = obj.item()\n            if not allow_nan and _is_nan_or_inf(extracted):\n                raise CodecError('Cannot serialize NaN - NaN/Infinity not allowed in JSON')\n            return extracted\n\n        if _is_pandas_scalar(obj):\n            try:\n                import pandas as pd\n            except ImportError:\n                pass\n            else:\n                if obj is pd.NaT or (hasattr(pd, 'isna') and pd.isna(obj)):\n                    return None\n                if isinstance(obj, pd.Timestamp):\n                    return obj.isoformat()\n                if isinstance(obj, pd.Timedelta):\n                    return obj.total_seconds()\n\n        if isinstance(obj, dt.datetime):\n            return obj.isoformat()\n        if isinstance(obj, dt.date):\n            return obj.isoformat()\n        if isinstance(obj, dt.time):\n            return obj.isoformat()\n        if isinstance(obj, dt.timedelta):\n            return obj.total_seconds()\n        if isinstance(obj, decimal.Decimal):\n            return str(obj)\n        if isinstance(obj, uuid.UUID):\n            return str(obj)\n        if isinstance(obj, (Path, PurePath)):\n            return str(obj)\n\n        if isinstance(obj, (bytes, bytearray)):\n            return {\n                '__type__': 'bytes',\n                'encoding': 'base64',\n                'data': base64.b64encode(obj).decode('ascii'),\n            }\n\n        model_dump = getattr(obj, 'model_dump', None)\n        if callable(model_dump):\n            try:\n                return model_dump(by_alias=True, mode='json')\n            except TypeError:\n                return model_dump(by_alias=True)\n\n        if isinstance(obj, (set, frozenset)):\n            return list(obj)\n\n        if isinstance(obj, complex):\n            raise TypeError(f'Object of type {type(obj).__name__} is not JSON serializable')\n\n        raise TypeError(f'Object of type {type(obj).__name__} is not JSON serializable')\n\n    return default_encoder\n\n\ndef encode_value(value, *, allow_nan):\n    \"\"\"\n    JSON-encode a fully-serialized response value, applying the SafeCodec-equivalent\n    default encoder and rejecting NaN/Infinity when allow_nan is False.\n\n    Raises CodecError (wrapping the json.dumps ValueError) on NaN/Infinity, matching\n    SafeCodec's \"Cannot serialize NaN...\" wording so error parity holds.\n    \"\"\"\n    try:\n        return json.dumps(value, default=make_default_encoder(allow_nan=allow_nan), allow_nan=allow_nan)\n    except ValueError as exc:\n        error_msg = str(exc).lower()\n        # json.dumps(allow_nan=False) rejects NaN/Infinity with a ValueError whose\n        # wording is Python-version dependent: 3.12+ appends the offending value\n        # (\"...not JSON compliant: nan\"), but 3.10/3.11 emit only the canonical\n        # \"Out of range float values are not JSON compliant\". Match that phrase too\n        # so the typed error message is stable across versions.\n        if (\n            'nan' in error_msg\n            or 'infinity' in error_msg\n            or 'inf' in error_msg\n            or 'out of range float' in error_msg\n        ):\n            raise CodecError('Cannot serialize NaN - NaN/Infinity not allowed in JSON') from exc\n        raise CodecError(f'JSON encoding failed: {exc}') from exc\n    except TypeError as exc:\n        raise CodecError(f'JSON encoding failed: {exc}') from exc\n\n\n# =============================================================================\n# REQUEST VALIDATION + HANDLERS + DISPATCH\n# =============================================================================\n\ndef require_protocol(msg):\n    if not isinstance(msg, dict):\n        raise ProtocolError('Invalid request payload')\n    proto = msg.get('protocol')\n    if proto != PROTOCOL:\n        raise ProtocolError(f'Invalid protocol: {proto}')\n    mid = msg.get('id')\n    if not isinstance(mid, int):\n        raise ProtocolError(f'Invalid request id: {mid}')\n    return mid\n\n\ndef require_str(params, key):\n    value = params.get(key)\n    if not isinstance(value, str) or not value:\n        raise ProtocolError(f'Missing {key}')\n    return value\n\n\ndef coerce_list(value, key):\n    if value is None:\n        return []\n    if not isinstance(value, list):\n        raise ProtocolError(f'Invalid {key}')\n    return value\n\n\ndef coerce_dict(value, key):\n    if value is None:\n        return {}\n    if not isinstance(value, dict):\n        raise ProtocolError(f'Invalid {key}')\n    return value\n\n\ndef handle_call(params, *, force_json_markers, torch_allow_copy):\n    module_name = require_str(params, 'module')\n    function_name = require_str(params, 'functionName')\n    args = deserialize(coerce_list(params.get('args'), 'args'))\n    kwargs = deserialize(coerce_dict(params.get('kwargs'), 'kwargs'))\n    mod = importlib.import_module(module_name)\n    func = getattr(mod, function_name)\n    res = func(*args, **kwargs)\n    return serialize(res, force_json_markers=force_json_markers, torch_allow_copy=torch_allow_copy)\n\n\ndef handle_instantiate(params, instances):\n    module_name = require_str(params, 'module')\n    class_name = require_str(params, 'className')\n    args = deserialize(coerce_list(params.get('args'), 'args'))\n    kwargs = deserialize(coerce_dict(params.get('kwargs'), 'kwargs'))\n    mod = importlib.import_module(module_name)\n    cls = getattr(mod, class_name)\n    obj = cls(*args, **kwargs)\n    handle_id = str(id(obj))\n    instances[handle_id] = obj\n    return handle_id\n\n\ndef handle_call_method(params, instances, *, force_json_markers, torch_allow_copy):\n    handle_id = require_str(params, 'handle')\n    method_name = require_str(params, 'methodName')\n    args = deserialize(coerce_list(params.get('args'), 'args'))\n    kwargs = deserialize(coerce_dict(params.get('kwargs'), 'kwargs'))\n    if handle_id not in instances:\n        raise InstanceHandleError(f'Unknown instance handle: {handle_id}')\n    obj = instances[handle_id]\n    func = getattr(obj, method_name)\n    res = func(*args, **kwargs)\n    return serialize(res, force_json_markers=force_json_markers, torch_allow_copy=torch_allow_copy)\n\n\ndef handle_dispose_instance(params, instances):\n    handle_id = require_str(params, 'handle')\n    if handle_id not in instances:\n        return False\n    del instances[handle_id]\n    return True\n\n\ndef build_meta(instances, *, bridge, pid, python_version, codec_fallback, arrow_available_override=None):\n    \"\"\"\n    Build the bridge metadata payload.\n\n    Field order here is part of the wire contract (the JS validator and the\n    documented BridgeInfo shape). Callers supply the backend-specific identity:\n    the subprocess server passes bridge='python-subprocess' and a real pid; the\n    Pyodide server passes bridge='pyodide' and pid=None.\n\n    arrow_available_override: when not None, report this value for arrowAvailable\n    instead of probing pyarrow. The Pyodide server forces markers to JSON\n    unconditionally, so it advertises arrowAvailable=False regardless of whether\n    pyarrow happens to be importable in the WASM environment.\n    \"\"\"\n    arrow = arrow_available() if arrow_available_override is None else arrow_available_override\n    return {\n        'protocol': PROTOCOL,\n        'protocolVersion': PROTOCOL_VERSION,\n        'bridge': bridge,\n        'pythonVersion': python_version,\n        'pid': pid,\n        'codecFallback': codec_fallback,\n        'arrowAvailable': arrow,\n        'scipyAvailable': module_available('scipy'),\n        'torchAvailable': module_available('torch'),\n        'sklearnAvailable': module_available('sklearn'),\n        'instances': len(instances),\n    }\n\n\ndef dispatch_request(\n    msg,\n    instances,\n    *,\n    bridge,\n    pid,\n    force_json_markers,\n    allow_nan=False,\n    python_version=None,\n    torch_allow_copy=False,\n    arrow_available_override=None,\n):\n    \"\"\"\n    Validate and route a request, returning the fully-serialized response dict\n    ({'id', 'protocol', 'result'}). Raises ProtocolError for malformed requests\n    and propagates handler exceptions to the caller, which is responsible for\n    building the error envelope (so it controls traceback inclusion).\n\n    allow_nan is accepted for signature symmetry; NaN rejection happens during\n    the final encode_value() call, which the caller performs.\n    \"\"\"\n    mid = require_protocol(msg)\n    method = msg.get('method')\n    if not isinstance(method, str):\n        raise ProtocolError('Missing method')\n    params = coerce_dict(msg.get('params'), 'params')\n    if method == 'call':\n        result = handle_call(\n            params, force_json_markers=force_json_markers, torch_allow_copy=torch_allow_copy\n        )\n    elif method == 'instantiate':\n        result = handle_instantiate(params, instances)\n    elif method == 'call_method':\n        result = handle_call_method(\n            params, instances, force_json_markers=force_json_markers, torch_allow_copy=torch_allow_copy\n        )\n    elif method == 'dispose_instance':\n        result = handle_dispose_instance(params, instances)\n    elif method == 'meta':\n        if python_version is None:\n            import sys\n            python_version = sys.version.split()[0]\n        codec_fallback = 'json' if force_json_markers else 'none'\n        result = build_meta(\n            instances,\n            bridge=bridge,\n            pid=pid,\n            python_version=python_version,\n            codec_fallback=codec_fallback,\n            arrow_available_override=arrow_available_override,\n        )\n    else:\n        raise ProtocolError(f'Unknown method: {method}')\n    return {'id': mid, 'protocol': PROTOCOL, 'result': result}\n\n\ndef build_error_payload(mid, exc, *, include_traceback):\n    \"\"\"\n    Build a protocol error response. Protocol/validation errors omit traceback;\n    handler errors include it. Field order matches the reference server.\n    \"\"\"\n    error = {'type': type(exc).__name__, 'message': str(exc)}\n    if include_traceback:\n        error['traceback'] = traceback.format_exc()\n    return {\n        'id': mid if mid is not None else -1,\n        'protocol': PROTOCOL,\n        'error': error,\n    }\n";
+export const PYODIDE_BRIDGE_CORE_SOURCE: string = "\"\"\"\nShared tywrap bridge core: protocol dispatch + value (de)serialization.\n\nThis module is the SINGLE source of truth for the \"tywrap/1\" server-side\nprotocol. It is imported by:\n\n  - runtime/python_bridge.py  (the Node/Bun/Deno subprocess server and the HTTP\n    server), which owns I/O concerns: the stdin/stdout JSONL loop, env-var size\n    guards, the real OS pid, bridge='python-subprocess', and the final BridgeCodec\n    encode wrapper.\n\n  - the in-WASM Pyodide server (src/runtime/pyodide-transport.ts). Pyodide cannot read\n    this file from disk, so it is shipped as a build-time-generated TypeScript\n    string constant (src/runtime/pyodide-bootstrap-core.generated.ts) produced by\n    scripts/generate-pyodide-bootstrap.mjs and exec'd into a module registered in\n    sys.modules. A conformance drift guard (test/runtime_conformance.test.ts)\n    asserts the generated constant stays byte-identical to this file.\n\nCROSS-LANGUAGE CONTRACT (Python <-> the TypeScript decoder in src/utils/codec.ts\nand the request encoder in src/runtime/bridge-codec.ts):\n\n  * Every value-type \"marker\" envelope carries {'__tywrap__': <type>,\n    'codecVersion': 1, 'encoding': ...}. The 6 markers are: ndarray, dataframe,\n    series, scipy.sparse, torch.tensor, sklearn.estimator.\n  * bytes round-trip both ways via base64 envelopes (see _deserialize_bytes_*\n    and the bytes branch of default_encoder).\n  * NaN/Infinity are rejected (the JS client cannot parse the non-standard tokens\n    that allow_nan=True would emit).\n\nPURITY: This module depends only on the standard library plus LAZY optional\nimports (numpy/pandas/scipy/torch/sklearn/pyarrow are each imported inside the\nfunction that needs them). It performs no stdin/stdout I/O and reads no env vars,\nso it runs unchanged under CPython-in-WASM (Pyodide).\n\nforce_json_markers: a *parameter* threaded through every serializer (including\nthe nested torch.tensor -> ndarray call). When True, ndarray/dataframe/series are\nforced down their JSON path regardless of pyarrow availability. Pyodide passes\nTrue (Arrow is unavailable in WASM); the subprocess server passes the boolean\nderived from TYWRAP_CODEC_FALLBACK=json so that \"Node in json-fallback mode\" and\n\"Pyodide\" produce byte-identical marker envelopes.\n\"\"\"\n\nimport base64\nimport datetime as dt\nimport decimal\nimport importlib\nimport importlib.util\nimport json\nimport math\nimport traceback\nimport uuid\nfrom pathlib import Path, PurePath\n\n# Protocol constants. These MUST match src/runtime/protocol.ts (PROTOCOL_ID,\n# TYWRAP_PROTOCOL_VERSION) and the codec version baked into marker envelopes.\nPROTOCOL = 'tywrap/1'\nPROTOCOL_VERSION = 1\nCODEC_VERSION = 1\n\n\nclass ProtocolError(Exception):\n    \"\"\"Raised for malformed requests (bad protocol/id/method/params).\"\"\"\n\n\nclass InstanceHandleError(ValueError):\n    \"\"\"Raised when an instance handle is unknown or no longer valid.\"\"\"\n\n\nclass ImportNotAllowedError(PermissionError):\n    \"\"\"Raised when a requested module import is not on the active allowlist.\"\"\"\n\n    def __init__(self, module_name):\n        super().__init__(\n            f'Import of module {module_name!r} is not permitted by the tywrap bridge '\n            'allowlist; add it to TYWRAP_ALLOWED_MODULES (subprocess) or the '\n            'allowed_modules parameter to enable it'\n        )\n\n\nclass AttributeNotAllowedError(PermissionError):\n    \"\"\"Raised when access to a private/dunder attribute is denied by policy.\"\"\"\n\n    def __init__(self, attr_name):\n        super().__init__(\n            f'Access to attribute {attr_name!r} is not permitted by the tywrap bridge: '\n            'underscore-prefixed (private/dunder) attributes are blocked to prevent '\n            'sandbox-escape via attributes like __globals__/__subclasses__/__builtins__; '\n            'set TYWRAP_ALLOW_PRIVATE_ATTRS=1 (subprocess) or pass allow_private_attrs=True '\n            'to override'\n        )\n\n\n# =============================================================================\n# IMPORT / ATTRIBUTE ALLOWLIST (trust boundary enforcement)\n# =============================================================================\n#\n# The bridge dispatches call/instantiate/call_method by importing the requested\n# module and getattr-ing the requested function/class/method. That is an\n# arbitrary import+getattr+call surface, so two complementary guards live here.\n# Both are PURE (no env reads) so the rules behave identically under the\n# subprocess server and the in-WASM Pyodide server; the subprocess server derives\n# the parameters from env vars (TYWRAP_ALLOWED_MODULES / TYWRAP_ALLOW_PRIVATE_ATTRS)\n# and threads them in, exactly like force_json_markers / torch_allow_copy.\n#\n# 1. MODULE ALLOWLIST (opt-in, default = allow all):\n#    allowed_modules=None means \"no restriction\" so existing configurations keep\n#    working unchanged. When a caller supplies a set, only those modules (plus the\n#    stdlib the bridge itself needs to serialize results, see _BRIDGE_REQUIRED_MODULES)\n#    may be imported; submodules of an allowed module are permitted (e.g. allowing\n#    'scipy' also allows 'scipy.sparse'). A non-allowlisted import fails LOUDLY with\n#    ImportNotAllowedError rather than silently importing.\n#\n# 2. PRIVATE-ATTRIBUTE BLOCK (default ON):\n#    getattr of any name starting with '_' (single-underscore private OR dunder) is\n#    rejected. This blocks the classic escape chain (obj.__class__.__subclasses__()\n#    /__globals__/__builtins__/__import__) without depending on the module allowlist.\n#    tywrap-generated wrappers never reference underscore-prefixed names (the IR\n#    analyzer skips them), so this does not regress generated code. Set\n#    allow_private_attrs=True to restore unrestricted getattr for trusted callers.\n\n# Stdlib modules the bridge's own serialization/handlers may need to import even\n# when a caller-supplied allowlist is active. Optional codec deps (numpy, pandas,\n# scipy, torch, sklearn, pyarrow) are intentionally NOT here: if a caller restricts\n# modules, they must opt those in explicitly. These names cover only what the\n# bridge core itself imports.\n_BRIDGE_REQUIRED_MODULES = frozenset(\n    {\n        'base64',\n        'datetime',\n        'decimal',\n        'importlib',\n        'json',\n        'math',\n        'sys',\n        'traceback',\n        'uuid',\n        'pathlib',\n    }\n)\n\n\ndef _top_level_package(module_name):\n    \"\"\"Return the top-level package of a dotted module name ('a.b.c' -> 'a').\"\"\"\n    return module_name.split('.', 1)[0]\n\n\ndef _is_module_allowed(module_name, allowed_modules):\n    \"\"\"\n    Return True when module_name may be imported under the active policy.\n\n    allowed_modules=None disables enforcement (allow all). Otherwise a module is\n    allowed when it (or its top-level package) is explicitly listed, or it is one\n    of the stdlib modules the bridge itself requires.\n    \"\"\"\n    if allowed_modules is None:\n        return True\n    if module_name in allowed_modules or module_name in _BRIDGE_REQUIRED_MODULES:\n        return True\n    top = _top_level_package(module_name)\n    return top in allowed_modules or top in _BRIDGE_REQUIRED_MODULES\n\n\ndef import_allowed_module(module_name, allowed_modules):\n    \"\"\"\n    Import module_name only if permitted by the allowlist, else raise loudly.\n\n    This is the single chokepoint every handler routes module imports through.\n    \"\"\"\n    if not _is_module_allowed(module_name, allowed_modules):\n        raise ImportNotAllowedError(module_name)\n    return importlib.import_module(module_name)\n\n\ndef get_allowed_attr(obj, attr_name, *, allow_private_attrs):\n    \"\"\"\n    getattr(obj, attr_name) with the private/dunder block applied.\n\n    Rejects any underscore-prefixed name unless allow_private_attrs is True. This\n    is the single chokepoint every handler routes attribute access through.\n    \"\"\"\n    if not allow_private_attrs and attr_name.startswith('_'):\n        raise AttributeNotAllowedError(attr_name)\n    return getattr(obj, attr_name)\n\n\nclass CodecError(Exception):\n    \"\"\"Raised when value encoding fails (e.g. NaN/Infinity not allowed).\"\"\"\n\n\n# =============================================================================\n# REQUEST-SIDE DESERIALIZATION (bytes envelopes -> Python bytes)\n# =============================================================================\n\n_NO_DESERIALIZE = object()\n_ERR_BYTES_MISSING_B64 = 'Invalid bytes envelope: missing b64'\n_ERR_BYTES_MISSING_DATA = 'Invalid bytes envelope: missing data'\n_ERR_BYTES_INVALID_BASE64 = 'Invalid bytes envelope: invalid base64'\n\n\ndef _deserialize_bytes_envelope(value):\n    \"\"\"\n    Decode base64-encoded bytes envelopes from JS into Python bytes.\n\n    Supported shapes:\n    - { \"__tywrap_bytes__\": true, \"b64\": \"...\" }  (JS BridgeCodec.encodeRequest)\n    - { \"__type__\": \"bytes\", \"encoding\": \"base64\", \"data\": \"...\" }  (legacy/compat)\n\n    Why: TS BridgeCodec encodes Uint8Array/ArrayBuffer as base64 objects, but\n    Python handlers expect real bytes/bytearray to preserve behavior (e.g., len()).\n    \"\"\"\n    if not isinstance(value, dict):\n        return _NO_DESERIALIZE\n\n    if value.get('__tywrap_bytes__') is True:\n        b64 = value.get('b64')\n        if not isinstance(b64, str):\n            raise ProtocolError(_ERR_BYTES_MISSING_B64)\n        try:\n            return base64.b64decode(b64, validate=True)\n        except Exception as exc:\n            raise ProtocolError(_ERR_BYTES_INVALID_BASE64) from exc\n\n    if value.get('__type__') == 'bytes' and value.get('encoding') == 'base64':\n        data = value.get('data')\n        if not isinstance(data, str):\n            raise ProtocolError(_ERR_BYTES_MISSING_DATA)\n        try:\n            return base64.b64decode(data, validate=True)\n        except Exception as exc:\n            raise ProtocolError(_ERR_BYTES_INVALID_BASE64) from exc\n\n    return _NO_DESERIALIZE\n\n\ndef deserialize(value):\n    \"\"\"\n    Recursively deserialize request values into Python-native types.\n\n    Why: requests are JSON-only; we need a small set of explicit decoders\n    (currently bytes) to restore Python semantics at the boundary.\n    \"\"\"\n    decoded = _deserialize_bytes_envelope(value)\n    if decoded is not _NO_DESERIALIZE:\n        return decoded\n\n    if isinstance(value, list):\n        return [deserialize(item) for item in value]\n    if isinstance(value, dict):\n        # Preserve dict shape while decoding nested values.\n        return {k: deserialize(v) for k, v in value.items()}\n    return value\n\n\n# =============================================================================\n# CAPABILITY DETECTION (lazy, best-effort)\n# =============================================================================\n\ndef arrow_available():\n    \"\"\"Return True when pyarrow can be imported.\"\"\"\n    try:\n        import pyarrow  # noqa: F401\n    except (ImportError, OSError):\n        return False\n    return True\n\n\ndef module_available(module_name):\n    \"\"\"\n    Lightweight feature detection for optional codec dependencies via find_spec.\n\n    Why: exposes availability in bridge metadata without importing heavy modules.\n    \"\"\"\n    try:\n        return importlib.util.find_spec(module_name) is not None\n    except (ImportError, AttributeError, TypeError, ValueError):\n        return False\n\n\ndef is_numpy_array(obj):\n    try:\n        import numpy as np  # noqa: F401\n    except Exception:\n        return False\n    return isinstance(obj, np.ndarray)\n\n\ndef is_pandas_dataframe(obj):\n    try:\n        import pandas as pd  # noqa: F401\n    except Exception:\n        return False\n    return isinstance(obj, pd.DataFrame)\n\n\ndef is_pandas_series(obj):\n    try:\n        import pandas as pd  # noqa: F401\n    except Exception:\n        return False\n    return isinstance(obj, pd.Series)\n\n\ndef is_scipy_sparse(obj):\n    try:\n        import scipy.sparse as sp  # noqa: F401\n    except Exception:\n        return False\n    try:\n        return sp.issparse(obj)\n    except Exception:\n        return False\n\n\ndef is_torch_tensor(obj):\n    try:\n        import torch  # noqa: F401\n    except Exception:\n        return False\n    try:\n        return torch.is_tensor(obj)\n    except Exception:\n        return False\n\n\ndef is_sklearn_estimator(obj):\n    try:\n        from sklearn.base import BaseEstimator  # noqa: F401\n    except Exception:\n        return False\n    return isinstance(obj, BaseEstimator)\n\n\n# =============================================================================\n# MARKER SERIALIZERS (6 __tywrap__ value types)\n# =============================================================================\n#\n# Each serializer accepts force_json_markers. When True, the Arrow path is never\n# taken (used by Pyodide and by the subprocess server in TYWRAP_CODEC_FALLBACK=json\n# mode). The JSON fallback envelopes are byte-identical across both callers, which\n# is what the conformance suite asserts.\n\ndef serialize_ndarray(obj, *, force_json_markers):\n    \"\"\"\n    Encode a NumPy ndarray. Arrow IPC (compact, lossless) by default; JSON when\n    force_json_markers is set or pyarrow is unavailable in fallback mode.\n\n    Note: pa.array() only handles 1D arrays; multi-dimensional arrays are\n    flattened with shape metadata for JS-side reconstruction. See\n    https://github.com/apache/arrow-js/issues/115\n    \"\"\"\n    if force_json_markers:\n        return serialize_ndarray_json(obj)\n    try:\n        import pyarrow as pa  # type: ignore\n    except Exception as exc:\n        raise RuntimeError(\n            'Arrow encoding unavailable for ndarray; install pyarrow or set TYWRAP_CODEC_FALLBACK=json to enable JSON fallback'\n        ) from exc\n    try:\n        original_shape = list(obj.shape) if hasattr(obj, 'shape') else None\n        flat = obj.flatten() if hasattr(obj, 'ndim') and obj.ndim > 1 else obj\n        arr = pa.array(flat)\n        table = pa.Table.from_arrays([arr], names=['value'])\n        sink = pa.BufferOutputStream()\n        with pa.ipc.new_stream(sink, table.schema) as writer:\n            writer.write_table(table)\n        buf = sink.getvalue()\n        b64 = base64.b64encode(buf.to_pybytes()).decode('ascii')\n        return {\n            '__tywrap__': 'ndarray',\n            'codecVersion': CODEC_VERSION,\n            'encoding': 'arrow',\n            'b64': b64,\n            'shape': original_shape,\n            'dtype': str(obj.dtype) if hasattr(obj, 'dtype') else None,\n        }\n    except Exception as exc:\n        raise RuntimeError('Arrow encoding failed for ndarray') from exc\n\n\ndef serialize_ndarray_json(obj):\n    \"\"\"JSON fallback for ndarray (larger payloads, potential dtype loss).\"\"\"\n    try:\n        data = obj.tolist()\n    except Exception as exc:\n        raise RuntimeError('JSON fallback failed for ndarray') from exc\n    return {\n        '__tywrap__': 'ndarray',\n        'codecVersion': CODEC_VERSION,\n        'encoding': 'json',\n        'data': data,\n        'shape': getattr(obj, 'shape', None),\n    }\n\n\ndef serialize_dataframe(obj, *, force_json_markers):\n    \"\"\"\n    Encode a pandas DataFrame. Feather/Arrow-IPC (uncompressed, so apache-arrow\n    in JS can read it) by default; JSON when force_json_markers is set.\n    \"\"\"\n    if force_json_markers:\n        return serialize_dataframe_json(obj)\n    try:\n        import pyarrow as pa  # type: ignore\n        import pyarrow.feather as feather  # type: ignore\n    except Exception as exc:\n        raise RuntimeError(\n            'Arrow encoding unavailable for pandas.DataFrame; install pyarrow or set TYWRAP_CODEC_FALLBACK=json to enable JSON fallback'\n        ) from exc\n    try:\n        table = pa.Table.from_pandas(obj)  # type: ignore\n        sink = pa.BufferOutputStream()\n        feather.write_feather(table, sink, compression='uncompressed')\n        buf = sink.getvalue()\n        b64 = base64.b64encode(buf.to_pybytes()).decode('ascii')\n        return {\n            '__tywrap__': 'dataframe',\n            'codecVersion': CODEC_VERSION,\n            'encoding': 'arrow',\n            'b64': b64,\n        }\n    except Exception as exc:\n        raise RuntimeError('Arrow encoding failed for pandas.DataFrame') from exc\n\n\ndef serialize_dataframe_json(obj):\n    \"\"\"JSON fallback for DataFrame: records orientation.\"\"\"\n    try:\n        data = obj.to_dict(orient='records')\n    except Exception as exc:\n        raise RuntimeError('JSON fallback failed for pandas.DataFrame') from exc\n    return {\n        '__tywrap__': 'dataframe',\n        'codecVersion': CODEC_VERSION,\n        'encoding': 'json',\n        'data': data,\n    }\n\n\ndef serialize_series(obj, *, force_json_markers):\n    \"\"\"\n    Encode a pandas Series as a single-column Arrow Table stream (the JS decoder\n    contract is \"table-like\"); JSON when force_json_markers is set.\n    \"\"\"\n    if force_json_markers:\n        return serialize_series_json(obj)\n    try:\n        import pyarrow as pa  # type: ignore\n    except Exception as exc:\n        raise RuntimeError(\n            'Arrow encoding unavailable for pandas.Series; install pyarrow or set TYWRAP_CODEC_FALLBACK=json to enable JSON fallback'\n        ) from exc\n    try:\n        arr = pa.Array.from_pandas(obj)  # type: ignore\n        table = pa.Table.from_arrays([arr], names=['value'])\n        sink = pa.BufferOutputStream()\n        with pa.ipc.new_stream(sink, table.schema) as writer:\n            writer.write_table(table)\n        buf = sink.getvalue()\n        b64 = base64.b64encode(buf.to_pybytes()).decode('ascii')\n        return {\n            '__tywrap__': 'series',\n            'codecVersion': CODEC_VERSION,\n            'encoding': 'arrow',\n            'b64': b64,\n            'name': getattr(obj, 'name', None),\n        }\n    except Exception as exc:\n        raise RuntimeError('Arrow encoding failed for pandas.Series') from exc\n\n\ndef serialize_series_json(obj):\n    \"\"\"JSON fallback for Series (potentially lossy dtype/NA representation).\"\"\"\n    try:\n        data = obj.to_list()  # type: ignore\n    except Exception:\n        try:\n            data = obj.to_dict()  # type: ignore\n        except Exception as exc:\n            raise RuntimeError('JSON fallback failed for pandas.Series') from exc\n    return {\n        '__tywrap__': 'series',\n        'codecVersion': CODEC_VERSION,\n        'encoding': 'json',\n        'data': data,\n        'name': getattr(obj, 'name', None),\n    }\n\n\ndef serialize_sparse_matrix(obj):\n    \"\"\"\n    Serialize scipy sparse matrices into structured JSON envelopes (json-only;\n    there is no Arrow path). Preserves sparsity; rejects unsupported formats and\n    complex dtypes explicitly.\n    \"\"\"\n    try:\n        fmt = obj.getformat()\n    except Exception as exc:\n        raise RuntimeError('Failed to inspect scipy sparse matrix format') from exc\n\n    if fmt not in ('csr', 'csc', 'coo'):\n        raise RuntimeError(f'Unsupported scipy sparse format: {fmt}')\n\n    dtype = None\n    try:\n        dtype = str(obj.dtype)\n    except Exception:\n        dtype = None\n    if getattr(obj.dtype, 'kind', None) == 'c':\n        raise RuntimeError('Complex sparse matrices are not supported by JSON codec')\n\n    if fmt in ('csr', 'csc'):\n        data = obj.data.tolist()\n        indices = obj.indices.tolist()\n        indptr = obj.indptr.tolist()\n        return {\n            '__tywrap__': 'scipy.sparse',\n            'codecVersion': CODEC_VERSION,\n            'encoding': 'json',\n            'format': fmt,\n            'shape': list(obj.shape),\n            'data': data,\n            'indices': indices,\n            'indptr': indptr,\n            'dtype': dtype,\n        }\n\n    # coo\n    data = obj.data.tolist()\n    row = obj.row.tolist()\n    col = obj.col.tolist()\n    return {\n        '__tywrap__': 'scipy.sparse',\n        'codecVersion': CODEC_VERSION,\n        'encoding': 'json',\n        'format': fmt,\n        'shape': list(obj.shape),\n        'data': data,\n        'row': row,\n        'col': col,\n        'dtype': dtype,\n    }\n\n\ndef serialize_torch_tensor(obj, *, force_json_markers, torch_allow_copy=False):\n    \"\"\"\n    Serialize torch.Tensor values via the nested ndarray envelope. CPU-only by\n    default; device/copy behavior is explicit. force_json_markers is threaded\n    into the nested ndarray serialization so Pyodide gets a JSON ndarray value.\n    \"\"\"\n    tensor = obj.detach()\n    if getattr(tensor, 'device', None) is not None and tensor.device.type != 'cpu':\n        if not torch_allow_copy:\n            raise RuntimeError(\n                'Torch tensor is on a non-CPU device; set TYWRAP_TORCH_ALLOW_COPY=1 to allow CPU transfer'\n            )\n        tensor = tensor.to('cpu')\n    if hasattr(tensor, 'is_contiguous') and not tensor.is_contiguous():\n        if not torch_allow_copy:\n            raise RuntimeError(\n                'Torch tensor is not contiguous; set TYWRAP_TORCH_ALLOW_COPY=1 to allow contiguous copy'\n            )\n        tensor = tensor.contiguous()\n    try:\n        arr = tensor.numpy()\n    except Exception as exc:\n        raise RuntimeError('Failed to convert torch.Tensor to numpy') from exc\n\n    return {\n        '__tywrap__': 'torch.tensor',\n        'codecVersion': CODEC_VERSION,\n        'encoding': 'ndarray',\n        'value': serialize_ndarray(arr, force_json_markers=force_json_markers),\n        'shape': list(tensor.shape),\n        'dtype': str(tensor.dtype),\n        'device': str(tensor.device),\n    }\n\n\ndef serialize_sklearn_estimator(obj):\n    \"\"\"Serialize sklearn estimators as metadata only (json-only); no pickling.\"\"\"\n    try:\n        import sklearn  # noqa: F401\n    except Exception as exc:\n        raise RuntimeError('scikit-learn is not available') from exc\n\n    params = obj.get_params(deep=False)\n    try:\n        json.dumps(params)\n    except Exception as exc:\n        raise RuntimeError(\n            'scikit-learn estimator params are not JSON-serializable; avoid returning estimators or sanitize params'\n        ) from exc\n\n    return {\n        '__tywrap__': 'sklearn.estimator',\n        'codecVersion': CODEC_VERSION,\n        'encoding': 'json',\n        'className': obj.__class__.__name__,\n        'module': obj.__class__.__module__,\n        'version': getattr(sklearn, '__version__', None),\n        'params': params,\n    }\n\n\n_NO_PYDANTIC = object()\n\n\ndef serialize_pydantic(obj):\n    \"\"\"\n    Serialize Pydantic v2 models via model_dump(by_alias=True, mode='json')\n    without importing Pydantic. Returns _NO_PYDANTIC when obj is not a model.\n    \"\"\"\n    model_dump = getattr(obj, 'model_dump', None)\n    if not callable(model_dump):\n        return _NO_PYDANTIC\n    try:\n        try:\n            return model_dump(by_alias=True, mode='json')\n        except TypeError:\n            # Older Pydantic versions may not support `mode=...`.\n            return model_dump(by_alias=True)\n    except Exception as exc:\n        raise RuntimeError(f'model_dump failed: {exc}') from exc\n\n\ndef serialize_stdlib(obj):\n    \"\"\"Coerce common stdlib scalar types to JSON-safe forms; None otherwise.\"\"\"\n    if isinstance(obj, dt.datetime):\n        return obj.isoformat()\n    if isinstance(obj, dt.date):\n        return obj.isoformat()\n    if isinstance(obj, dt.time):\n        return obj.isoformat()\n    if isinstance(obj, dt.timedelta):\n        return obj.total_seconds()\n    if isinstance(obj, decimal.Decimal):\n        return str(obj)\n    if isinstance(obj, uuid.UUID):\n        return str(obj)\n    if isinstance(obj, (Path, PurePath)):\n        return str(obj)\n    return None\n\n\ndef serialize(obj, *, force_json_markers, torch_allow_copy=False):\n    \"\"\"\n    Top-level result serializer. Dispatch order is significant: numpy ndarray ->\n    dataframe -> series -> scipy.sparse -> torch -> sklearn -> Pydantic -> stdlib\n    -> passthrough. The remaining BridgeCodec value behaviors (numpy/pandas scalars,\n    bytes, sets, complex rejection, NaN/Infinity) are applied later during JSON\n    encoding by default_encoder.\n    \"\"\"\n    if is_numpy_array(obj):\n        return serialize_ndarray(obj, force_json_markers=force_json_markers)\n    if is_pandas_dataframe(obj):\n        return serialize_dataframe(obj, force_json_markers=force_json_markers)\n    if is_pandas_series(obj):\n        return serialize_series(obj, force_json_markers=force_json_markers)\n    if is_scipy_sparse(obj):\n        return serialize_sparse_matrix(obj)\n    if is_torch_tensor(obj):\n        return serialize_torch_tensor(\n            obj, force_json_markers=force_json_markers, torch_allow_copy=torch_allow_copy\n        )\n    if is_sklearn_estimator(obj):\n        return serialize_sklearn_estimator(obj)\n    pydantic_value = serialize_pydantic(obj)\n    if pydantic_value is not _NO_PYDANTIC:\n        return pydantic_value\n    stdlib_value = serialize_stdlib(obj)\n    if stdlib_value is not None:\n        return stdlib_value\n    return obj\n\n\n# =============================================================================\n# JSON ENCODE: BridgeCodec-equivalent value handling (NaN reject, scalars, bytes)\n# =============================================================================\n#\n# This mirrors BridgeCodec._default_encoder (runtime/safe_codec.py) for the VALUE\n# behaviors that are part of the wire contract. The subprocess server still uses\n# the real BridgeCodec for its final encode (it also enforces size limits); this\n# core encoder exists so the Pyodide server gets identical value handling without\n# depending on safe_codec.py. The conformance suite asserts these behaviors match.\n\ndef _is_nan_or_inf(value):\n    if not isinstance(value, (int, float)):\n        return False\n    try:\n        return math.isnan(value) or math.isinf(value)\n    except (TypeError, ValueError):\n        return False\n\n\ndef _is_numpy_scalar(obj):\n    try:\n        import numpy as np\n    except ImportError:\n        return False\n    return isinstance(obj, (np.generic, np.ndarray)) and obj.ndim == 0\n\n\ndef _is_pandas_scalar(obj):\n    try:\n        import pandas as pd\n    except ImportError:\n        return False\n    return isinstance(obj, (pd.Timestamp, pd.Timedelta, type(pd.NaT)))\n\n\ndef make_default_encoder(*, allow_nan):\n    \"\"\"\n    Build a json.dumps default= encoder matching BridgeCodec's value handling.\n\n    Raises CodecError for NaN/Infinity extracted from numpy scalars (json.dumps\n    itself rejects top-level/nested NaN/Infinity floats when allow_nan=False).\n    \"\"\"\n\n    def default_encoder(obj):\n        # numpy/pandas scalars first (need .item() extraction).\n        if _is_numpy_scalar(obj):\n            extracted = obj.item()\n            if not allow_nan and _is_nan_or_inf(extracted):\n                raise CodecError('Cannot serialize NaN - NaN/Infinity not allowed in JSON')\n            return extracted\n\n        if _is_pandas_scalar(obj):\n            try:\n                import pandas as pd\n            except ImportError:\n                pass\n            else:\n                if obj is pd.NaT or (hasattr(pd, 'isna') and pd.isna(obj)):\n                    return None\n                if isinstance(obj, pd.Timestamp):\n                    return obj.isoformat()\n                if isinstance(obj, pd.Timedelta):\n                    return obj.total_seconds()\n\n        if isinstance(obj, dt.datetime):\n            return obj.isoformat()\n        if isinstance(obj, dt.date):\n            return obj.isoformat()\n        if isinstance(obj, dt.time):\n            return obj.isoformat()\n        if isinstance(obj, dt.timedelta):\n            return obj.total_seconds()\n        if isinstance(obj, decimal.Decimal):\n            return str(obj)\n        if isinstance(obj, uuid.UUID):\n            return str(obj)\n        if isinstance(obj, (Path, PurePath)):\n            return str(obj)\n\n        if isinstance(obj, (bytes, bytearray)):\n            return {\n                '__type__': 'bytes',\n                'encoding': 'base64',\n                'data': base64.b64encode(obj).decode('ascii'),\n            }\n\n        model_dump = getattr(obj, 'model_dump', None)\n        if callable(model_dump):\n            try:\n                return model_dump(by_alias=True, mode='json')\n            except TypeError:\n                return model_dump(by_alias=True)\n\n        if isinstance(obj, (set, frozenset)):\n            return list(obj)\n\n        if isinstance(obj, complex):\n            raise TypeError(f'Object of type {type(obj).__name__} is not JSON serializable')\n\n        raise TypeError(f'Object of type {type(obj).__name__} is not JSON serializable')\n\n    return default_encoder\n\n\ndef encode_value(value, *, allow_nan):\n    \"\"\"\n    JSON-encode a fully-serialized response value, applying the BridgeCodec-equivalent\n    default encoder and rejecting NaN/Infinity when allow_nan is False.\n\n    Raises CodecError (wrapping the json.dumps ValueError) on NaN/Infinity, matching\n    BridgeCodec's \"Cannot serialize NaN...\" wording so error parity holds.\n    \"\"\"\n    try:\n        return json.dumps(value, default=make_default_encoder(allow_nan=allow_nan), allow_nan=allow_nan)\n    except ValueError as exc:\n        error_msg = str(exc).lower()\n        # json.dumps(allow_nan=False) rejects NaN/Infinity with a ValueError whose\n        # wording is Python-version dependent: 3.12+ appends the offending value\n        # (\"...not JSON compliant: nan\"), but 3.10/3.11 emit only the canonical\n        # \"Out of range float values are not JSON compliant\". Match that phrase too\n        # so the typed error message is stable across versions.\n        if (\n            'nan' in error_msg\n            or 'infinity' in error_msg\n            or 'inf' in error_msg\n            or 'out of range float' in error_msg\n        ):\n            raise CodecError('Cannot serialize NaN - NaN/Infinity not allowed in JSON') from exc\n        raise CodecError(f'JSON encoding failed: {exc}') from exc\n    except TypeError as exc:\n        raise CodecError(f'JSON encoding failed: {exc}') from exc\n\n\n# =============================================================================\n# REQUEST VALIDATION + HANDLERS + DISPATCH\n# =============================================================================\n\ndef require_protocol(msg):\n    if not isinstance(msg, dict):\n        raise ProtocolError('Invalid request payload')\n    proto = msg.get('protocol')\n    if proto != PROTOCOL:\n        raise ProtocolError(f'Invalid protocol: {proto}')\n    mid = msg.get('id')\n    if not isinstance(mid, int):\n        raise ProtocolError(f'Invalid request id: {mid}')\n    return mid\n\n\ndef require_str(params, key):\n    value = params.get(key)\n    if not isinstance(value, str) or not value:\n        raise ProtocolError(f'Missing {key}')\n    return value\n\n\ndef coerce_list(value, key):\n    if value is None:\n        return []\n    if not isinstance(value, list):\n        raise ProtocolError(f'Invalid {key}')\n    return value\n\n\ndef coerce_dict(value, key):\n    if value is None:\n        return {}\n    if not isinstance(value, dict):\n        raise ProtocolError(f'Invalid {key}')\n    return value\n\n\ndef handle_call(params, *, force_json_markers, torch_allow_copy, allowed_modules, allow_private_attrs):\n    module_name = require_str(params, 'module')\n    function_name = require_str(params, 'functionName')\n    args = deserialize(coerce_list(params.get('args'), 'args'))\n    kwargs = deserialize(coerce_dict(params.get('kwargs'), 'kwargs'))\n    mod = import_allowed_module(module_name, allowed_modules)\n    func = get_allowed_attr(mod, function_name, allow_private_attrs=allow_private_attrs)\n    res = func(*args, **kwargs)\n    return serialize(res, force_json_markers=force_json_markers, torch_allow_copy=torch_allow_copy)\n\n\ndef handle_instantiate(params, instances, *, allowed_modules, allow_private_attrs):\n    module_name = require_str(params, 'module')\n    class_name = require_str(params, 'className')\n    args = deserialize(coerce_list(params.get('args'), 'args'))\n    kwargs = deserialize(coerce_dict(params.get('kwargs'), 'kwargs'))\n    mod = import_allowed_module(module_name, allowed_modules)\n    cls = get_allowed_attr(mod, class_name, allow_private_attrs=allow_private_attrs)\n    obj = cls(*args, **kwargs)\n    handle_id = str(id(obj))\n    instances[handle_id] = obj\n    return handle_id\n\n\ndef handle_call_method(params, instances, *, force_json_markers, torch_allow_copy, allow_private_attrs):\n    handle_id = require_str(params, 'handle')\n    method_name = require_str(params, 'methodName')\n    args = deserialize(coerce_list(params.get('args'), 'args'))\n    kwargs = deserialize(coerce_dict(params.get('kwargs'), 'kwargs'))\n    if handle_id not in instances:\n        raise InstanceHandleError(f'Unknown instance handle: {handle_id}')\n    obj = instances[handle_id]\n    func = get_allowed_attr(obj, method_name, allow_private_attrs=allow_private_attrs)\n    res = func(*args, **kwargs)\n    return serialize(res, force_json_markers=force_json_markers, torch_allow_copy=torch_allow_copy)\n\n\ndef handle_dispose_instance(params, instances):\n    handle_id = require_str(params, 'handle')\n    if handle_id not in instances:\n        return False\n    del instances[handle_id]\n    return True\n\n\ndef build_meta(instances, *, bridge, pid, python_version, codec_fallback, arrow_available_override=None):\n    \"\"\"\n    Build the bridge metadata payload.\n\n    Field order here is part of the wire contract (the JS validator and the\n    documented BridgeInfo shape). Callers supply the backend-specific identity:\n    the subprocess server passes bridge='python-subprocess' and a real pid; the\n    Pyodide server passes bridge='pyodide' and pid=None.\n\n    arrow_available_override: when not None, report this value for arrowAvailable\n    instead of probing pyarrow. The Pyodide server forces markers to JSON\n    unconditionally, so it advertises arrowAvailable=False regardless of whether\n    pyarrow happens to be importable in the WASM environment.\n    \"\"\"\n    arrow = arrow_available() if arrow_available_override is None else arrow_available_override\n    return {\n        'protocol': PROTOCOL,\n        'protocolVersion': PROTOCOL_VERSION,\n        'bridge': bridge,\n        'pythonVersion': python_version,\n        'pid': pid,\n        'codecFallback': codec_fallback,\n        'arrowAvailable': arrow,\n        'scipyAvailable': module_available('scipy'),\n        'torchAvailable': module_available('torch'),\n        'sklearnAvailable': module_available('sklearn'),\n        'instances': len(instances),\n    }\n\n\ndef dispatch_request(\n    msg,\n    instances,\n    *,\n    bridge,\n    pid,\n    force_json_markers,\n    allow_nan=False,\n    python_version=None,\n    torch_allow_copy=False,\n    arrow_available_override=None,\n    allowed_modules=None,\n    allow_private_attrs=False,\n):\n    \"\"\"\n    Validate and route a request, returning the fully-serialized response dict\n    ({'id', 'protocol', 'result'}). Raises ProtocolError for malformed requests\n    and propagates handler exceptions to the caller, which is responsible for\n    building the error envelope (so it controls traceback inclusion).\n\n    allow_nan is accepted for signature symmetry; NaN rejection happens during\n    the final encode_value() call, which the caller performs.\n\n    allowed_modules: None (default) disables the import allowlist so existing\n    behavior is preserved. Supplying a set restricts call/instantiate imports to\n    those modules (plus the stdlib the bridge itself needs) and raises\n    ImportNotAllowedError otherwise. allow_private_attrs=False (default) blocks\n    getattr of underscore-prefixed names; True restores unrestricted access. See\n    the IMPORT / ATTRIBUTE ALLOWLIST section above for the full trust model.\n    \"\"\"\n    mid = require_protocol(msg)\n    method = msg.get('method')\n    if not isinstance(method, str):\n        raise ProtocolError('Missing method')\n    params = coerce_dict(msg.get('params'), 'params')\n    if method == 'call':\n        result = handle_call(\n            params,\n            force_json_markers=force_json_markers,\n            torch_allow_copy=torch_allow_copy,\n            allowed_modules=allowed_modules,\n            allow_private_attrs=allow_private_attrs,\n        )\n    elif method == 'instantiate':\n        result = handle_instantiate(\n            params, instances, allowed_modules=allowed_modules, allow_private_attrs=allow_private_attrs\n        )\n    elif method == 'call_method':\n        result = handle_call_method(\n            params,\n            instances,\n            force_json_markers=force_json_markers,\n            torch_allow_copy=torch_allow_copy,\n            allow_private_attrs=allow_private_attrs,\n        )\n    elif method == 'dispose_instance':\n        result = handle_dispose_instance(params, instances)\n    elif method == 'meta':\n        if python_version is None:\n            import sys\n            python_version = sys.version.split()[0]\n        codec_fallback = 'json' if force_json_markers else 'none'\n        result = build_meta(\n            instances,\n            bridge=bridge,\n            pid=pid,\n            python_version=python_version,\n            codec_fallback=codec_fallback,\n            arrow_available_override=arrow_available_override,\n        )\n    else:\n        raise ProtocolError(f'Unknown method: {method}')\n    return {'id': mid, 'protocol': PROTOCOL, 'result': result}\n\n\ndef build_error_payload(mid, exc, *, include_traceback):\n    \"\"\"\n    Build a protocol error response. Protocol/validation errors omit traceback;\n    handler errors include it. Field order matches the reference server.\n    \"\"\"\n    error = {'type': type(exc).__name__, 'message': str(exc)}\n    if include_traceback:\n        error['traceback'] = traceback.format_exc()\n    return {\n        'id': mid if mid is not None else -1,\n        'protocol': PROTOCOL,\n        'error': error,\n    }\n";

package/src/runtime/{pyodide-io.ts → pyodide-transport.ts}

@@ -1,5 +1,5 @@
 /**
- * PyodideIO Transport - In-memory Pyodide communication for browser environments.
+ * PyodideTransport - In-memory Pyodide communication for browser environments.
  *
  * This transport implements the Transport interface for direct in-memory
  * communication with Pyodide (Python compiled to WebAssembly). It is designed
@@ -29,9 +29,9 @@ import {
 // =============================================================================
 
 /**
- * Options for configuring the PyodideIO transport.
+ * Options for configuring the PyodideTransport.
  */
-export interface PyodideIOOptions {
+export interface PyodideTransportOptions {
   /** URL for Pyodide CDN. Default: official CDN */
   indexURL?: string;
   /** Python packages to load during initialization */
@@ -176,7 +176,7 @@ def __tywrap_dispatch(message_json):
  *
  * @example
  * ```typescript
- * const transport = new PyodideIO({ packages: ['numpy'] });
+ * const transport = new PyodideTransport({ packages: ['numpy'] });
  * await transport.init();
  *
  * const response = await transport.send(
@@ -192,17 +192,17 @@ def __tywrap_dispatch(message_json):
  * await transport.dispose();
  * ```
  */
-export class PyodideIO extends DisposableBase implements Transport {
+export class PyodideTransport extends DisposableBase implements Transport {
   private readonly indexURL: string;
   private readonly packages: readonly string[];
   private py?: PyodideInstance;
 
   /**
-   * Create a new PyodideIO transport.
+   * Create a new PyodideTransport.
    *
    * @param options - Configuration options
    */
-  constructor(options: PyodideIOOptions = {}) {
+  constructor(options: PyodideTransportOptions = {}) {
     super();
     this.indexURL = options.indexURL ?? DEFAULT_INDEX_URL;
     this.packages = Object.freeze([...(options.packages ?? [])]);

package/src/runtime/pyodide.ts

@@ -2,7 +2,7 @@
  * Pyodide runtime bridge.
  *
  * PyodideBridge is a thin facade: it extends DisposableBase (lifecycle) and
- * implements PythonRuntime by HOLDING an RpcClient over a PyodideIO transport
+ * implements PythonRuntime by HOLDING an RpcClient over a PyodideTransport
  * for in-memory Python execution in browser environments via WebAssembly.
  *
  * @see https://github.com/bbopen/tywrap/issues/149
@@ -12,8 +12,8 @@ import type { PythonRuntime, BridgeInfo } from '../types/index.js';
 
 import { DisposableBase } from './bounded-context.js';
 import { RpcClient, type GetBridgeInfoOptions } from './rpc-client.js';
-import { PyodideIO } from './pyodide-io.js';
-import type { CodecOptions } from './safe-codec.js';
+import { PyodideTransport } from './pyodide-transport.js';
+import type { CodecOptions } from './bridge-codec.js';
 
 // =============================================================================
 // OPTIONS
@@ -51,7 +51,7 @@ export interface PyodideBridgeOptions {
  * - Zero network overhead (in-memory execution)
  * - Automatic Pyodide loading from CDN or module
  * - Python package loading support
- * - Full SafeCodec validation (NaN/Infinity rejection, key validation)
+ * - Full BridgeCodec validation (NaN/Infinity rejection, key validation)
  * - Proper proxy cleanup to prevent memory leaks
  *
  * @example
@@ -78,7 +78,7 @@ export class PyodideBridge extends DisposableBase implements PythonRuntime {
   constructor(options: PyodideBridgeOptions = {}) {
     super();
 
-    const transport = new PyodideIO({
+    const transport = new PyodideTransport({
       indexURL: options.indexURL,
       packages: options.packages,
     });
@@ -110,7 +110,7 @@ export class PyodideBridge extends DisposableBase implements PythonRuntime {
   }
 
   // ===========================================================================
-  // RPC METHODS (delegate to the held RpcClient; never PyodideIO directly)
+  // RPC METHODS (delegate to the held RpcClient; never PyodideTransport directly)
   // ===========================================================================
 
   async call<T = unknown>(

package/src/runtime/rpc-client.ts

@@ -1,7 +1,7 @@
 /**
  * RpcClient - the single correlated-RPC client for JS<->Python communication.
  *
- * It HOLDS a Transport and a codec (SafeCodec) and is, in turn, HELD by the
+ * It HOLDS a Transport and a codec (BridgeCodec) 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
@@ -22,9 +22,13 @@ import type { BridgeInfo } from '../types/index.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';
-import { PROTOCOL_ID, type Transport, type ProtocolMessage } from './transport.js';
+import { BridgeCodec, type CodecOptions } from './bridge-codec.js';
+import {
+  PROTOCOL_ID,
+  TYWRAP_PROTOCOL_VERSION,
+  type Transport,
+  type ProtocolMessage,
+} from './transport.js';
 
 // =============================================================================
 // TYPES
@@ -180,7 +184,7 @@ function validateBridgeInfoPayload(value: unknown): BridgeInfo {
 // =============================================================================
 
 /**
- * RpcClient holds a SafeCodec + Transport and composes DisposableBase for
+ * RpcClient holds a BridgeCodec + 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.
  *
@@ -190,7 +194,7 @@ function validateBridgeInfoPayload(value: unknown): BridgeInfo {
  *   private readonly rpc: RpcClient;
  *   constructor(options: NodeBridgeOptions) {
  *     super();
- *     const transport = new ProcessIO(options);
+ *     const transport = new SubprocessTransport(options);
  *     this.rpc = new RpcClient({ transport, defaultTimeoutMs: options.timeout });
  *     this.trackResource(this.rpc);
  *   }
@@ -200,7 +204,7 @@ function validateBridgeInfoPayload(value: unknown): BridgeInfo {
  */
 export class RpcClient extends DisposableBase {
   /** Codec instance for validation and serialization */
-  readonly codec: SafeCodec;
+  readonly codec: BridgeCodec;
 
   /** Transport instance for message passing */
   readonly transport: Transport;
@@ -221,7 +225,7 @@ export class RpcClient extends DisposableBase {
    */
   constructor(options: RpcClientOptions) {
     super();
-    this.codec = new SafeCodec(options.codec);
+    this.codec = new BridgeCodec(options.codec);
     this.transport = options.transport;
     this.defaultTimeoutMs = options.defaultTimeoutMs ?? 30000;
 
@@ -277,26 +281,7 @@ export class RpcClient extends DisposableBase {
     message: Omit<ProtocolMessage, 'id' | 'protocol'>,
     options?: ExecuteOptions<T>
   ): Promise<T> {
-    const fullMessage: ProtocolMessage = {
-      ...message,
-      id: this.generateId(),
-      protocol: PROTOCOL_ID,
-    };
-
-    return this.execute(async () => {
-      // 1. Encode request (validates args)
-      const encoded = this.codec.encodeRequest(fullMessage);
-
-      // 2. Send via transport
-      const responseStr = await this.transport.send(
-        encoded,
-        options?.timeoutMs ?? this.defaultTimeoutMs,
-        options?.signal
-      );
-
-      // 3. Decode response (validates result)
-      return this.codec.decodeResponse<T>(responseStr);
-    }, options);
+    return this.sendVia(message, options, responseStr => this.codec.decodeResponse<T>(responseStr));
   }
 
   /**
@@ -317,11 +302,27 @@ export class RpcClient extends DisposableBase {
     message: Omit<ProtocolMessage, 'id' | 'protocol'>,
     options?: ExecuteOptions<T>
   ): Promise<T> {
-    const fullMessage: ProtocolMessage = {
-      ...message,
-      id: this.generateId(),
-      protocol: PROTOCOL_ID,
-    };
+    return this.sendVia(message, options, responseStr =>
+      this.codec.decodeResponseAsync<T>(responseStr)
+    );
+  }
+
+  /**
+   * Shared body for sendMessage/sendMessageAsync: stamp the frame, run the
+   * encode -> transport.send -> decode pipeline inside this.execute() (which
+   * supplies auto-init, timeout/retry/abort), where the only difference between
+   * the sync and Arrow-aware paths is the supplied `decode` step.
+   *
+   * Behavior-preserving extraction of the two twins; ordering, the
+   * `options?.timeoutMs ?? this.defaultTimeoutMs` fallback, and the
+   * `this.execute(..., options)` wrapping are unchanged.
+   */
+  private async sendVia<T>(
+    message: Omit<ProtocolMessage, 'id' | 'protocol'>,
+    options: ExecuteOptions<T> | undefined,
+    decode: (responseStr: string) => T | Promise<T>
+  ): Promise<T> {
+    const fullMessage = this.stampMessage(message);
 
     return this.execute(async () => {
       // 1. Encode request (validates args)
@@ -334,8 +335,8 @@ export class RpcClient extends DisposableBase {
         options?.signal
       );
 
-      // 3. Decode response with Arrow support
-      return this.codec.decodeResponseAsync<T>(responseStr);
+      // 3. Decode response (sync or Arrow-aware, per caller)
+      return decode(responseStr);
     }, options);
   }
 
@@ -360,11 +361,7 @@ export class RpcClient extends DisposableBase {
     message: Omit<ProtocolMessage, 'id' | 'protocol'>,
     opts?: { timeoutMs?: number; signal?: AbortSignal }
   ): Promise<T> {
-    const fullMessage: ProtocolMessage = {
-      ...message,
-      id: this.generateId(),
-      protocol: PROTOCOL_ID,
-    };
+    const fullMessage = this.stampMessage(message);
     const encoded = this.codec.encodeRequest(fullMessage);
     const responseStr = await transport.send(
       encoded,
@@ -374,6 +371,20 @@ export class RpcClient extends DisposableBase {
     return this.codec.decodeResponseAsync<T>(responseStr);
   }
 
+  /**
+   * Stamp a partial message into a full wire frame: assign the next request id
+   * and the protocol marker. The single id counter + protocol stamping live
+   * here so every send path (sendMessage/sendMessageAsync/sendOn) is correlated
+   * identically.
+   */
+  private stampMessage(message: Omit<ProtocolMessage, 'id' | 'protocol'>): ProtocolMessage {
+    return {
+      ...message,
+      id: this.generateId(),
+      protocol: PROTOCOL_ID,
+    };
+  }
+
   /**
    * Generate a unique request ID.
    *

package/src/runtime/{process-io.ts → subprocess-transport.ts}

@@ -1,5 +1,5 @@
 /**
- * ProcessIO Transport - Subprocess-based Python communication for Node.js.
+ * SubprocessTransport - Subprocess-based Python communication for Node.js.
  *
  * This transport implements the Transport interface for spawning and communicating
  * with a Python subprocess via stdio streams. It provides:
@@ -14,6 +14,7 @@
  */
 
 import { spawn, type ChildProcess } from 'child_process';
+import type { Writable } from 'stream';
 import { DisposableBase } from './bounded-context.js';
 import { BridgeDisposedError, BridgeProtocolError, BridgeTimeoutError } from './errors.js';
 import { TimedOutRequestTracker } from './timed-out-request-tracker.js';
@@ -46,9 +47,9 @@ const CONTROL_CHARS_RE = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F\u0080-\u
 // =============================================================================
 
 /**
- * Options for ProcessIO transport.
+ * Options for the SubprocessTransport.
  */
-export interface ProcessIOOptions {
+export interface SubprocessTransportOptions {
   /** Python executable path. Default: 'python3' */
   pythonPath?: string;
 
@@ -135,14 +136,14 @@ function extractMessageId(json: string): number | null {
 /**
  * Transport implementation for subprocess-based Python communication.
  *
- * ProcessIO spawns a Python child process and communicates via stdio:
+ * SubprocessTransport spawns a Python child process and communicates via stdio:
  * - Requests are written to stdin as JSON lines
  * - Responses are read from stdout as JSON lines
  * - Stderr is captured for diagnostics
  *
  * @example
  * ```typescript
- * const transport = new ProcessIO({
+ * const transport = new SubprocessTransport({
  *   bridgeScript: '/path/to/bridge.py',
  *   pythonPath: 'python3',
  * });
@@ -157,7 +158,7 @@ function extractMessageId(json: string): number | null {
  * await transport.dispose();
  * ```
  */
-export class ProcessIO extends DisposableBase implements Transport {
+export class SubprocessTransport extends DisposableBase implements Transport {
   // Configuration
   private readonly pythonPath: string;
   private readonly bridgeScript: string;
@@ -189,11 +190,11 @@ export class ProcessIO extends DisposableBase implements Transport {
   private draining = false;
 
   /**
-   * Create a new ProcessIO transport.
+   * Create a new SubprocessTransport.
    *
    * @param options - Transport configuration options
    */
-  constructor(options: ProcessIOOptions) {
+  constructor(options: SubprocessTransportOptions) {
     super();
 
     this.pythonPath = options.pythonPath ?? 'python3';
@@ -764,6 +765,67 @@ export class ProcessIO extends DisposableBase implements Transport {
     });
   }
 
+  /**
+   * Reject and clear every entry currently in the write queue.
+   * Clears each entry's timeout before rejecting so no late timer fires.
+   */
+  private rejectAllQueuedWrites(error: Error): void {
+    for (const q of this.writeQueue) {
+      this.clearQueuedWriteTimeout(q);
+      q.reject(error);
+    }
+    this.writeQueue.length = 0;
+  }
+
+  /**
+   * Process a single dequeued write entry: enforce the fallback queue timeout,
+   * then attempt the stdin write. The returned status tells {@link flushWriteQueue}
+   * how to proceed:
+   * - `'continue'`: entry settled (written or timed out); process the next entry.
+   * - `'backpressure'`: write accepted but stream is full; pause until the next drain.
+   * - `'error'`: synchronous write failure; the caller must reject the remaining queue.
+   *
+   * The entry's own timeout must already be cleared by the caller before this runs.
+   */
+  private processQueuedWrite(
+    queued: QueuedWrite,
+    stdin: Writable,
+    now: number
+  ): 'continue' | 'backpressure' | 'error' {
+    // Check for write queue timeout (fallback check, timer should have handled this)
+    if (now - queued.queuedAt > this.writeQueueTimeoutMs) {
+      queued.reject(
+        new BridgeTimeoutError(
+          `Write queue timeout: entry waited ${now - queued.queuedAt}ms (limit: ${this.writeQueueTimeoutMs}ms)`
+        )
+      );
+      return 'continue';
+    }
+
+    try {
+      const canWrite = stdin.write(queued.data);
+
+      if (canWrite) {
+        queued.resolve();
+        return 'continue';
+      }
+
+      // Backpressure - this write has been accepted by stream buffer.
+      // Pause further queued writes until the next "drain" event.
+      queued.resolve();
+      this.draining = true;
+      return 'backpressure';
+    } catch (err) {
+      // Synchronous write error (e.g., EPIPE) - reject this entry; caller rejects the rest.
+      const errorMessage = err instanceof Error ? err.message : 'unknown';
+      const error = new BridgeProtocolError(this.withStderrTail(`Write error: ${errorMessage}`));
+      queued.reject(error);
+      this.rejectAllQueuedWrites(error);
+      this.markForRestart();
+      return 'error';
+    }
+  }
+
   /**
    * Flush queued writes when backpressure clears.
    */
@@ -771,13 +833,12 @@ export class ProcessIO extends DisposableBase implements Transport {
     const now = Date.now();
 
     while (this.writeQueue.length > 0 && !this.draining) {
-      if (!this.process?.stdin || this.processExited) {
+      const stdin = this.process?.stdin;
+      if (!stdin || this.processExited) {
         // Process died - reject all queued writes
-        for (const q of this.writeQueue) {
-          this.clearQueuedWriteTimeout(q);
-          q.reject(new BridgeProtocolError(this.withStderrTail('Process stdin not available')));
-        }
-        this.writeQueue.length = 0;
+        this.rejectAllQueuedWrites(
+          new BridgeProtocolError(this.withStderrTail('Process stdin not available'))
+        );
         this.markForRestart();
         return;
       }
@@ -790,39 +851,8 @@ export class ProcessIO extends DisposableBase implements Transport {
       // Clear the timeout since we're processing this entry now
       this.clearQueuedWriteTimeout(queued);
 
-      // Check for write queue timeout (fallback check, timer should have handled this)
-      if (now - queued.queuedAt > this.writeQueueTimeoutMs) {
-        queued.reject(
-          new BridgeTimeoutError(
-            `Write queue timeout: entry waited ${now - queued.queuedAt}ms (limit: ${this.writeQueueTimeoutMs}ms)`
-          )
-        );
-        continue; // Process next entry
-      }
-
-      try {
-        const canWrite = this.process.stdin.write(queued.data);
-
-        if (canWrite) {
-          queued.resolve();
-        } else {
-          // Backpressure - this write has been accepted by stream buffer.
-          // Pause further queued writes until the next "drain" event.
-          queued.resolve();
-          this.draining = true;
-          return;
-        }
-      } catch (err) {
-        // Synchronous write error (e.g., EPIPE) - reject this and all remaining writes
-        const errorMessage = err instanceof Error ? err.message : 'unknown';
-        const error = new BridgeProtocolError(this.withStderrTail(`Write error: ${errorMessage}`));
-        queued.reject(error);
-        for (const q of this.writeQueue) {
-          this.clearQueuedWriteTimeout(q);
-          q.reject(error);
-        }
-        this.writeQueue.length = 0;
-        this.markForRestart();
+      const status = this.processQueuedWrite(queued, stdin, now);
+      if (status === 'backpressure' || status === 'error') {
         return;
       }
     }