tywrap 0.8.0 → 0.10.0

package/runtime/tywrap_bridge_core.py

@@ -43,12 +43,12 @@ derived from TYWRAP_CODEC_FALLBACK=json so that "Node in json-fallback mode" and
 import base64
 import datetime as dt
 import decimal
-import functools
 import importlib
 import importlib.util
-import inspect
 import json
 import math
+import re
+import sys
 import traceback
 import uuid
 from pathlib import Path, PurePath
@@ -58,16 +58,16 @@ from pathlib import Path, PurePath
 PROTOCOL = 'tywrap/1'
 PROTOCOL_VERSION = 1
 CODEC_VERSION = 1
+MAX_SERIALIZE_DEPTH = 900
+MAX_SERIALIZE_NODES = 1_000_000
+JS_SAFE_INTEGER_MAX = 2**53 - 1
+_SERIALIZE_PATH_IDENTIFIER = re.compile(r'^[A-Za-z_$][\w$]*$', re.ASCII)
 
 
 class ProtocolError(Exception):
     """Raised for malformed requests (bad protocol/id/method/params)."""
 
 
-class InstanceHandleError(ValueError):
-    """Raised when an instance handle is unknown or no longer valid."""
-
-
 class ImportNotAllowedError(PermissionError):
     """Raised when a requested module import is not on the active allowlist."""
 
@@ -96,8 +96,8 @@ class AttributeNotAllowedError(PermissionError):
 # IMPORT / ATTRIBUTE ALLOWLIST (trust boundary enforcement)
 # =============================================================================
 #
-# The bridge dispatches call/instantiate/call_method by importing the requested
-# module and getattr-ing the requested function/class/method. That is an
+# The bridge dispatches call requests by importing the requested module and
+# getattr-ing the requested function/class method. That is an
 # arbitrary import+getattr+call surface, so two complementary guards live here.
 # Both are PURE (no env reads) so the rules behave identically under the
 # subprocess server and the in-WASM Pyodide server; the subprocess server derives
@@ -204,22 +204,6 @@ def resolve_allowed_attr_path(root, dotted_name, *, allow_private_attrs):
     return obj
 
 
-def is_accessor_attr(obj, attr_name):
-    """
-    True when attr_name resolves to a @property or functools.cached_property on
-    obj's type — i.e. it is read by attribute access, not called.
-
-    Inspects type(obj)'s MRO via getattr_static (which never triggers the
-    descriptor protocol), NOT the instance dict. That matters for
-    cached_property: after the first read it stores its value in the instance
-    __dict__, so an instance-level static lookup would return the cached value
-    rather than the descriptor and misclassify it as a method on the next read.
-    Reading from the type keeps the classification stable across repeated reads.
-    """
-    descriptor = inspect.getattr_static(type(obj), attr_name, None)
-    return isinstance(descriptor, (property, functools.cached_property))
-
-
 class CodecError(Exception):
     """Raised when value encoding fails (e.g. NaN/Infinity not allowed)."""
 
@@ -269,22 +253,24 @@ def _deserialize_bytes_envelope(value):
     return _NO_DESERIALIZE
 
 
-def deserialize(value):
+def deserialize(value, *, has_envelope_markers=True):
     """
     Recursively deserialize request values into Python-native types.
 
     Why: requests are JSON-only; we need a small set of explicit decoders
     (currently bytes) to restore Python semantics at the boundary.
     """
+    if not has_envelope_markers:
+        return value
     decoded = _deserialize_bytes_envelope(value)
     if decoded is not _NO_DESERIALIZE:
         return decoded
 
     if isinstance(value, list):
-        return [deserialize(item) for item in value]
+        return [deserialize(item, has_envelope_markers=True) for item in value]
     if isinstance(value, dict):
         # Preserve dict shape while decoding nested values.
-        return {k: deserialize(v) for k, v in value.items()}
+        return {k: deserialize(v, has_envelope_markers=True) for k, v in value.items()}
     return value
 
 
@@ -314,33 +300,33 @@ def module_available(module_name):
 
 
 def is_numpy_array(obj):
-    try:
-        import numpy as np  # noqa: F401
-    except Exception:
+    """Return whether obj is an ndarray without importing NumPy."""
+    np = sys.modules.get('numpy')
+    if np is None:
         return False
     return isinstance(obj, np.ndarray)
 
 
 def is_pandas_dataframe(obj):
-    try:
-        import pandas as pd  # noqa: F401
-    except Exception:
+    """Return whether obj is a DataFrame without importing pandas."""
+    pd = sys.modules.get('pandas')
+    if pd is None:
         return False
     return isinstance(obj, pd.DataFrame)
 
 
 def is_pandas_series(obj):
-    try:
-        import pandas as pd  # noqa: F401
-    except Exception:
+    """Return whether obj is a Series without importing pandas."""
+    pd = sys.modules.get('pandas')
+    if pd is None:
         return False
     return isinstance(obj, pd.Series)
 
 
 def is_scipy_sparse(obj):
-    try:
-        import scipy.sparse as sp  # noqa: F401
-    except Exception:
+    """Return whether obj is sparse without importing SciPy."""
+    sp = sys.modules.get('scipy.sparse')
+    if sp is None:
         return False
     try:
         return sp.issparse(obj)
@@ -349,9 +335,9 @@ def is_scipy_sparse(obj):
 
 
 def is_torch_tensor(obj):
-    try:
-        import torch  # noqa: F401
-    except Exception:
+    """Return whether obj is a Tensor without importing PyTorch."""
+    torch = sys.modules.get('torch')
+    if torch is None:
         return False
     try:
         return torch.is_tensor(obj)
@@ -360,11 +346,11 @@ def is_torch_tensor(obj):
 
 
 def is_sklearn_estimator(obj):
-    try:
-        from sklearn.base import BaseEstimator  # noqa: F401
-    except Exception:
+    """Return whether obj is an estimator without importing scikit-learn."""
+    sklearn_base = sys.modules.get('sklearn.base')
+    if sklearn_base is None:
         return False
-    return isinstance(obj, BaseEstimator)
+    return isinstance(obj, sklearn_base.BaseEstimator)
 
 
 # =============================================================================
@@ -395,7 +381,7 @@ def serialize_ndarray(obj, *, force_json_markers):
         ) from exc
     try:
         original_shape = list(obj.shape) if hasattr(obj, 'shape') else None
-        flat = obj.flatten() if hasattr(obj, 'ndim') and obj.ndim > 1 else obj
+        flat = obj.flatten() if hasattr(obj, 'ndim') and obj.ndim != 1 else obj
         arr = pa.array(flat)
         table = pa.Table.from_arrays([arr], names=['value'])
         sink = pa.BufferOutputStream()
@@ -416,7 +402,80 @@ def serialize_ndarray(obj, *, force_json_markers):
 
 
 def serialize_ndarray_json(obj):
-    """JSON fallback for ndarray (larger payloads, potential dtype loss)."""
+    """JSON fallback for ndarray values that JavaScript can represent safely."""
+    dtype = obj.dtype
+    dtype_label = str(dtype)
+
+    if not dtype.isnative:
+        raise RuntimeError(
+            f'JSON ndarray encoding does not support big-endian dtype={dtype_label}; '
+            "convert to native byte order with a.byteswap().view(a.dtype.newbyteorder('='))"
+        )
+
+    if dtype.kind in ('i', 'u'):
+        # JSON numbers become JavaScript Number values. Scan only on this explicit
+        # fallback path and reject before tolist() can silently round an integer.
+        if obj.size and (
+            (obj < -JS_SAFE_INTEGER_MAX).any() or (obj > JS_SAFE_INTEGER_MAX).any()
+        ):
+            raise RuntimeError(
+                f'JSON ndarray encoding cannot safely represent dtype={dtype_label} values '
+                'outside the JavaScript safe integer range; use Arrow encoding or '
+                "cast/encode explicitly (e.g. .astype('float64') or str)"
+            )
+    elif dtype.kind == 'M':
+        raise RuntimeError(
+            f'JSON ndarray encoding does not support dtype={dtype_label}; use Arrow encoding '
+            "or convert explicitly (e.g. .astype('datetime64[ms]').astype(str) or int with "
+            'declared unit)'
+        )
+    elif dtype.kind == 'm':
+        raise RuntimeError(
+            f'JSON ndarray encoding does not support dtype={dtype_label}; use Arrow encoding '
+            "or convert explicitly (e.g. .astype('timedelta64[ms]').astype(str) or int with "
+            'declared unit)'
+        )
+    elif dtype.kind == 'V':
+        if dtype.fields is not None:
+            raise RuntimeError(
+                f'JSON ndarray encoding does not support structured dtype={dtype_label}; '
+                'encode each named field explicitly (e.g. as a plain JSON object)'
+            )
+        raise RuntimeError(
+            f'JSON ndarray encoding does not support void dtype={dtype_label}; convert the '
+            "raw bytes explicitly (e.g. .view('uint8'))"
+        )
+    elif dtype.kind == 'O':
+        raise RuntimeError(
+            f'JSON ndarray encoding does not support object dtype={dtype_label}; cast to a '
+            'concrete numeric dtype or encode elements explicitly as plain JSON'
+        )
+    elif dtype.kind == 'S':
+        raise RuntimeError(
+            f'JSON ndarray encoding does not support byte-string dtype={dtype_label}; '
+            'decode elements and return a plain JSON list explicitly'
+        )
+    elif dtype.kind == 'U':
+        raise RuntimeError(
+            f'JSON ndarray encoding does not support unicode dtype={dtype_label}; convert '
+            'explicitly to plain JSON strings with .tolist()'
+        )
+    elif dtype.kind == 'c':
+        raise RuntimeError(
+            f'JSON ndarray encoding does not support complex dtype={dtype_label}; encode '
+            '.real and .imag arrays explicitly'
+        )
+    elif dtype.kind == 'f' and dtype.itemsize > 8:
+        raise RuntimeError(
+            f'JSON ndarray encoding does not support float dtype={dtype_label} wider than '
+            "64 bits; cast explicitly (e.g. .astype('float64')) or use Arrow encoding"
+        )
+    elif dtype.kind not in ('b', 'f'):
+        raise RuntimeError(
+            f'JSON ndarray encoding does not support dtype={dtype_label}; cast to bool, '
+            'integer, or float dtype, or encode values explicitly as plain JSON'
+        )
+
     try:
         data = obj.tolist()
     except Exception as exc:
@@ -427,6 +486,7 @@ def serialize_ndarray_json(obj):
         'encoding': 'json',
         'data': data,
         'shape': getattr(obj, 'shape', None),
+        'dtype': dtype.name,
     }
 
 
@@ -461,11 +521,42 @@ def serialize_dataframe(obj, *, force_json_markers):
 
 
 def serialize_dataframe_json(obj):
-    """JSON fallback for DataFrame: records orientation."""
+    """JSON fallback for DataFrame values that JavaScript can represent safely."""
+    import pandas as pd  # type: ignore
+
+    _validate_pandas_json_index(obj.index, pd, 'DataFrame')
+    json_columns = [_json_object_key(column) for column in obj.columns]
+    supported_json_columns = [column for column in json_columns if column is not None]
+    if not obj.columns.is_unique or len(set(supported_json_columns)) != len(
+        supported_json_columns
+    ):
+        raise RuntimeError(
+            'JSON pandas.DataFrame encoding requires column labels to remain unique after '
+            'JSON object-key coercion; rename columns or make them distinct before applying '
+            '.columns.astype(str)'
+        )
+    for column, dtype in obj.dtypes.items():
+        if isinstance(dtype, pd.CategoricalDtype):
+            raise RuntimeError(
+                f'JSON pandas.DataFrame encoding does not support categorical dtype in '
+                f'column {column!r}; use Arrow encoding or convert explicitly '
+                "(e.g. .astype(str))"
+            )
     try:
-        data = obj.to_dict(orient='records')
+        data = (
+            [{} for _ in range(len(obj.index))]
+            if len(obj.columns) == 0
+            else obj.to_dict(orient='records')
+        )
     except Exception as exc:
         raise RuntimeError('JSON fallback failed for pandas.DataFrame') from exc
+    for row_number, row in enumerate(data):
+        for column, value in row.items():
+            row[column] = _normalize_pandas_json_scalar(
+                value,
+                f'DataFrame cell at row {row_number}, column {column!r}',
+                pd,
+            )
     return {
         '__tywrap__': 'dataframe',
         'codecVersion': CODEC_VERSION,
@@ -507,14 +598,23 @@ def serialize_series(obj, *, force_json_markers):
 
 
 def serialize_series_json(obj):
-    """JSON fallback for Series (potentially lossy dtype/NA representation)."""
+    """JSON fallback for Series values that JavaScript can represent safely."""
+    import pandas as pd  # type: ignore
+
+    _validate_pandas_json_index(obj.index, pd, 'Series')
+    if isinstance(obj.dtype, pd.CategoricalDtype):
+        raise RuntimeError(
+            'JSON pandas.Series encoding does not support categorical dtype; use Arrow '
+            "encoding or convert explicitly (e.g. .astype(str))"
+        )
     try:
         data = obj.to_list()  # type: ignore
-    except Exception:
-        try:
-            data = obj.to_dict()  # type: ignore
-        except Exception as exc:
-            raise RuntimeError('JSON fallback failed for pandas.Series') from exc
+    except Exception as exc:
+        raise RuntimeError('JSON fallback failed for pandas.Series') from exc
+    data = [
+        _normalize_pandas_json_scalar(value, f'Series value at position {position}', pd)
+        for position, value in enumerate(data)
+    ]
     return {
         '__tywrap__': 'series',
         'codecVersion': CODEC_VERSION,
@@ -524,6 +624,70 @@ def serialize_series_json(obj):
     }
 
 
+def _validate_pandas_json_index(index, pd, container_name):
+    """Reject index metadata that records/list-oriented JSON would discard."""
+    if isinstance(index, pd.MultiIndex):
+        raise RuntimeError(
+            f'JSON pandas.{container_name} encoding does not support MultiIndex; use Arrow '
+            'encoding or flatten the index explicitly with .reset_index()'
+        )
+    if not (
+        isinstance(index, pd.RangeIndex)
+        and index.start == 0
+        and index.step == 1
+        and index.stop == len(index)
+        and index.name is None
+    ):
+        raise RuntimeError(
+            f'JSON pandas.{container_name} encoding requires an unnamed RangeIndex starting '
+            'at 0 with step 1; use Arrow encoding or normalize explicitly with '
+            '.reset_index(drop=True)'
+        )
+
+
+def _json_object_key(value):
+    """Return json.dumps' object-key spelling, or None for unsupported keys."""
+    try:
+        encoded = json.dumps({value: None})
+    except (TypeError, ValueError):
+        return None
+    return next(iter(json.loads(encoded)))
+
+
+def _normalize_pandas_json_scalar(value, location, pd):
+    """Normalize pandas nulls and reject values outside the plain JSON domain."""
+    np = sys.modules.get('numpy')
+    if np is not None and isinstance(value, np.generic):
+        value = value.item()
+    if value is None or value is pd.NA or value is pd.NaT:
+        return None
+    if type(value) is bool:
+        return value
+    if type(value) is int:
+        if value < -JS_SAFE_INTEGER_MAX or value > JS_SAFE_INTEGER_MAX:
+            raise RuntimeError(
+                f'JSON pandas encoding cannot safely represent {location} integer values '
+                'outside the JavaScript safe integer range; use Arrow encoding or '
+                "cast/encode explicitly (e.g. .astype('float64') or str)"
+            )
+        return value
+    if type(value) is float:
+        if not math.isfinite(value):
+            raise RuntimeError(
+                f'JSON pandas encoding cannot represent non-finite {location} float values '
+                '(NaN or Infinity); use .fillna(...) for intentional missing values or '
+                'Arrow encoding'
+            )
+        return value
+    if type(value) is str:
+        return value
+    raise RuntimeError(
+        f'JSON pandas encoding does not support {location} value of type '
+        f'{type(value).__name__}; use Arrow encoding or convert explicitly '
+        '(e.g. .astype(str))'
+    )
+
+
 def serialize_sparse_matrix(obj):
     """
     Serialize scipy sparse matrices into structured JSON envelopes (json-only;
@@ -594,12 +758,14 @@ def serialize_torch_tensor(obj, *, force_json_markers, torch_allow_copy=False):
     Rejection order is significant: the categorical rejections (sparse / quantized
     / meta / complex) are checked BEFORE the device/contiguous opt-in branch so
     they fail with a clear, specific message and are NOT bypassable by
-    TYWRAP_TORCH_ALLOW_COPY. The opt-in only governs the lossy-but-lossless device
-    transfer and contiguous copy, never an unrepresentable layout/dtype.
+    TYWRAP_TORCH_ALLOW_COPY. The opt-in only governs the device transfer and
+    contiguous copy, never an unrepresentable layout/dtype.
     """
     import torch  # already importable: is_torch_tensor() gated the dispatch
 
     tensor = obj.detach()
+    source_device = None
+    source_dtype = None
 
     # Sparse tensors (COO/CSR/CSC/BSR/BSC -> any non-strided layout) have no dense
     # numpy representation without a densify step, which is not the round-trip this
@@ -647,6 +813,7 @@ def serialize_torch_tensor(obj, *, force_json_markers, torch_allow_copy=False):
             raise RuntimeError(
                 'Torch tensor is on a non-CPU device; set TYWRAP_TORCH_ALLOW_COPY=1 to allow CPU transfer'
             )
+        source_device = str(tensor.device)
         tensor = tensor.to('cpu')
     if hasattr(tensor, 'is_contiguous') and not tensor.is_contiguous():
         if not torch_allow_copy:
@@ -654,12 +821,15 @@ def serialize_torch_tensor(obj, *, force_json_markers, torch_allow_copy=False):
                 'Torch tensor is not contiguous; set TYWRAP_TORCH_ALLOW_COPY=1 to allow contiguous copy'
             )
         tensor = tensor.contiguous()
+    if tensor.dtype == torch.bfloat16:
+        source_dtype = str(tensor.dtype)
+        tensor = tensor.float()
     try:
         arr = tensor.numpy()
     except Exception as exc:
         raise RuntimeError('Failed to convert torch.Tensor to numpy') from exc
 
-    return {
+    envelope = {
         '__tywrap__': 'torch.tensor',
         'codecVersion': CODEC_VERSION,
         'encoding': 'ndarray',
@@ -668,6 +838,11 @@ def serialize_torch_tensor(obj, *, force_json_markers, torch_allow_copy=False):
         'dtype': str(tensor.dtype),
         'device': str(tensor.device),
     }
+    if source_dtype is not None:
+        envelope['sourceDtype'] = source_dtype
+    if source_device is not None:
+        envelope['sourceDevice'] = source_device
+    return envelope
 
 
 def serialize_sklearn_estimator(obj):
@@ -746,46 +921,227 @@ def serialize_stdlib(obj):
     return None
 
 
-def serialize(obj, *, force_json_markers, torch_allow_copy=False):
-    """
-    Top-level result serializer. Dispatch order is significant: numpy ndarray ->
-    dataframe -> series -> scipy.sparse -> torch -> sklearn -> Pydantic -> stdlib
-    -> passthrough. The remaining BridgeCodec value behaviors (numpy/pandas scalars,
-    bytes, sets, complex rejection, NaN/Infinity) are applied later during JSON
-    encoding by default_encoder.
-    """
-    if is_numpy_array(obj):
-        return serialize_ndarray(obj, force_json_markers=force_json_markers)
-    if is_pandas_dataframe(obj):
-        return serialize_dataframe(obj, force_json_markers=force_json_markers)
-    if is_pandas_series(obj):
-        return serialize_series(obj, force_json_markers=force_json_markers)
-    if is_scipy_sparse(obj):
-        return serialize_sparse_matrix(obj)
-    if is_torch_tensor(obj):
-        return serialize_torch_tensor(
-            obj, force_json_markers=force_json_markers, torch_allow_copy=torch_allow_copy
+_NO_SCIENTIFIC = object()
+
+
+def _check_serialize_depth(depth, path):
+    if depth > MAX_SERIALIZE_DEPTH:
+        raise RuntimeError(
+            f'Scientific envelope serialization maximum depth '
+            f'{MAX_SERIALIZE_DEPTH} exceeded at {path}'
+        )
+
+
+def _check_serialize_nodes(nodes, path):
+    if nodes > MAX_SERIALIZE_NODES:
+        raise RuntimeError(
+            f'Scientific envelope serialization maximum visited nodes '
+            f'{MAX_SERIALIZE_NODES} exceeded at {path}'
         )
-    if is_sklearn_estimator(obj):
+
+
+def _serialize_scientific(obj, *, force_json_markers, torch_allow_copy, depth, path):
+    """Serialize a supported scientific value, or return _NO_SCIENTIFIC."""
+    package = type(obj).__module__.split('.', 1)[0]
+
+    if package == 'numpy' and 'numpy' in sys.modules:
+        if is_numpy_array(obj):
+            _check_serialize_depth(depth, path)
+            return serialize_ndarray(obj, force_json_markers=force_json_markers)
+    elif package == 'pandas' and 'pandas' in sys.modules:
+        if is_pandas_dataframe(obj):
+            _check_serialize_depth(depth, path)
+            return serialize_dataframe(obj, force_json_markers=force_json_markers)
+        if is_pandas_series(obj):
+            _check_serialize_depth(depth, path)
+            return serialize_series(obj, force_json_markers=force_json_markers)
+    elif package == 'scipy' and 'scipy.sparse' in sys.modules:
+        if is_scipy_sparse(obj):
+            _check_serialize_depth(depth, path)
+            return serialize_sparse_matrix(obj)
+    elif package == 'torch' and 'torch' in sys.modules:
+        if is_torch_tensor(obj):
+            _check_serialize_depth(depth, path)
+            _check_serialize_depth(depth + 1, _serialize_path(path, 'value'))
+            return serialize_torch_tensor(
+                obj, force_json_markers=force_json_markers, torch_allow_copy=torch_allow_copy
+            )
+    elif 'sklearn.base' in sys.modules and is_sklearn_estimator(obj):
+        # No package gate here, unlike the branches above: subclassing
+        # BaseEstimator is sklearn's documented extension point, so user-defined
+        # estimators live outside the 'sklearn' package and must still get the
+        # estimator serializer (and its param-naming errors).
+        _check_serialize_depth(depth, path)
         return serialize_sklearn_estimator(obj)
-    pydantic_value = serialize_pydantic(obj)
+
+    return _NO_SCIENTIFIC
+
+
+def _serialize_path(base, key):
+    """Build a decoder-compatible JSONPath-like result path."""
+    if isinstance(key, int):
+        return f'{base}[{key}]'
+    if _SERIALIZE_PATH_IDENTIFIER.fullmatch(key):
+        return f'{base}.{key}'
+    return f'{base}[{json.dumps(key, ensure_ascii=False)}]'
+
+
+def _invalid_key_path(base, key):
+    """Name a dict key that cannot be represented by JSON."""
+    return f'{base}[{key!r}]'
+
+
+def _needs_serialize_visit(value):
+    """Return whether value needs container or scientific traversal work."""
+    if type(value) in (type(None), bool, int, float, str):
+        return False
+    if type(value) in (dict, list, tuple):
+        return True
+    package = type(value).__module__.split('.', 1)[0]
+    if package in ('numpy', 'pandas', 'scipy', 'torch'):
+        return True
+    return 'sklearn.base' in sys.modules and is_sklearn_estimator(value)
+
+
+def _serialize_leaf(value):
+    """Apply non-container conversions without allocating a traversal frame."""
+    if type(value) in (type(None), bool, int, float, str):
+        return value
+    pydantic_value = serialize_pydantic(value)
     if pydantic_value is not _NO_PYDANTIC:
         return pydantic_value
-    stdlib_value = serialize_stdlib(obj)
+    stdlib_value = serialize_stdlib(value)
     if stdlib_value is not None:
         return stdlib_value
-    return obj
+    return value
+
+
+def serialize(obj, *, force_json_markers, torch_allow_copy=False):
+    """
+    Top-level result serializer.
+
+    Scientific codecs are type-first and only inspect packages that the value can
+    belong to. A value from an optional package implies that package is already in
+    sys.modules, so these checks never cold-import the scientific stack. The
+    package dispatch deliberately precedes the JSON-native fast path: e.g. a
+    package-defined subclass of dict still receives its relevant codec check.
+    Every other value is left untouched so the shared JSON encoder applies the
+    exact same default conversion at the root and at any nested depth.
+    """
+    root = [None]
+    active_ids = set()
+    stack = [('visit', obj, 0, 'result', root, 0)]
+    visited_nodes = 0
+
+    # Repeated aliases have value semantics and are intentionally serialized twice.
+    while stack:
+        frame = stack.pop()
+        action = frame[0]
+        if action == 'dict':
+            _, current, depth, path, parent, key, output, iterator = frame
+            try:
+                item_key, item = next(iterator)
+            except StopIteration:
+                active_ids.remove(id(current))
+                parent[key] = output
+                continue
+            stack.append(frame)
+            if not (isinstance(item_key, (str, int, float, bool)) or item_key is None):
+                invalid_path = _invalid_key_path(path, item_key)
+                raise TypeError(
+                    f'keys must be str, int, float, bool or None, not '
+                    f'{type(item_key).__name__} at {invalid_path}'
+                )
+            child_key = _json_object_key(item_key)
+            child_path = _serialize_path(path, child_key)
+            if _needs_serialize_visit(item):
+                stack.append(('visit', item, depth + 1, child_path, output, item_key))
+            else:
+                output[item_key] = _serialize_leaf(item)
+            continue
+        if action == 'sequence':
+            _, current, depth, path, parent, key, output, index = frame
+            if index == len(output):
+                active_ids.remove(id(current))
+                parent[key] = output if type(current) is list else tuple(output)
+                continue
+            stack.append(('sequence', current, depth, path, parent, key, output, index + 1))
+            item = current[index]
+            if _needs_serialize_visit(item):
+                stack.append(
+                    ('visit', item, depth + 1, _serialize_path(path, index), output, index)
+                )
+            else:
+                output[index] = _serialize_leaf(item)
+            continue
+
+        _, current, depth, path, parent, key = frame
+        try:
+            scientific = _serialize_scientific(
+                current,
+                force_json_markers=force_json_markers,
+                torch_allow_copy=torch_allow_copy,
+                depth=depth,
+                path=path,
+            )
+        except Exception as exc:
+            if path == 'result':
+                raise
+            raise RuntimeError(f'Scientific value serialization failed at {path}: {exc}') from exc
+        if scientific is not _NO_SCIENTIFIC:
+            # Recognized envelopes are terminal containers to the JS decoder.
+            visited_nodes += 1
+            _check_serialize_nodes(visited_nodes, path)
+            if scientific.get('__tywrap__') == 'torch.tensor':
+                nested_path = _serialize_path(path, 'value')
+                try:
+                    visited_nodes += 1
+                    _check_serialize_nodes(visited_nodes, nested_path)
+                except Exception as exc:
+                    if path == 'result':
+                        raise
+                    raise RuntimeError(
+                        f'Scientific value serialization failed at {path}: {exc}'
+                    ) from exc
+            parent[key] = scientific
+            continue
+
+        container_type = type(current)
+        if container_type in (dict, list, tuple):
+            _check_serialize_depth(depth, path)
+            visited_nodes += 1
+            _check_serialize_nodes(visited_nodes, path)
+            current_id = id(current)
+            if current_id in active_ids:
+                raise RuntimeError(f'Circular reference detected at {path}')
+            active_ids.add(current_id)
+
+            if container_type is dict:
+                output = {}
+                parent[key] = output
+                stack.append(
+                    ('dict', current, depth, path, parent, key, output, iter(current.items()))
+                )
+                continue
+
+            output = [None] * len(current)
+            if container_type is list:
+                parent[key] = output
+            stack.append(('sequence', current, depth, path, parent, key, output, 0))
+            continue
+
+        parent[key] = _serialize_leaf(current)
+
+    return root[0]
 
 
 # =============================================================================
-# JSON ENCODE: BridgeCodec-equivalent value handling (NaN reject, scalars, bytes)
+# JSON CODEC: value handling and size-limited encode/decode
 # =============================================================================
 #
-# This mirrors BridgeCodec._default_encoder (runtime/safe_codec.py) for the VALUE
-# behaviors that are part of the wire contract. The subprocess server still uses
-# the real BridgeCodec for its final encode (it also enforces size limits); this
-# core encoder exists so the Pyodide server gets identical value handling without
-# depending on safe_codec.py. The conformance suite asserts these behaviors match.
+# This is the single Python implementation used by both the subprocess bridge and
+# the embedded Pyodide core. BridgeCodec adds payload-size enforcement around the
+# shared encoder; encode_value is the unbounded form used by the in-memory bridge.
 
 def _is_nan_or_inf(value):
     if not isinstance(value, (int, float)):
@@ -841,20 +1197,9 @@ def make_default_encoder(*, allow_nan):
                 if isinstance(obj, pd.Timedelta):
                     return obj.total_seconds()
 
-        if isinstance(obj, dt.datetime):
-            return obj.isoformat()
-        if isinstance(obj, dt.date):
-            return obj.isoformat()
-        if isinstance(obj, dt.time):
-            return obj.isoformat()
-        if isinstance(obj, dt.timedelta):
-            return obj.total_seconds()
-        if isinstance(obj, decimal.Decimal):
-            return str(obj)
-        if isinstance(obj, uuid.UUID):
-            return str(obj)
-        if isinstance(obj, (Path, PurePath)):
-            return str(obj)
+        stdlib_value = serialize_stdlib(obj)
+        if stdlib_value is not None:
+            return stdlib_value
 
         if isinstance(obj, (bytes, bytearray)):
             return {
@@ -898,18 +1243,66 @@ def encode_value(value, *, allow_nan):
         # ("...not JSON compliant: nan"), but 3.10/3.11 emit only the canonical
         # "Out of range float values are not JSON compliant". Match that phrase too
         # so the typed error message is stable across versions.
+        nonfinite_token = re.search(r'(^|[^a-z])(nan|inf|infinity)([^a-z]|$)', error_msg)
         if (
-            'nan' in error_msg
-            or 'infinity' in error_msg
-            or 'inf' in error_msg
-            or 'out of range float' in error_msg
-        ):
+            not allow_nan and 'out of range float values are not json compliant' in error_msg
+        ) or nonfinite_token:
             raise CodecError('Cannot serialize NaN - NaN/Infinity not allowed in JSON') from exc
         raise CodecError(f'JSON encoding failed: {exc}') from exc
     except TypeError as exc:
         raise CodecError(f'JSON encoding failed: {exc}') from exc
 
 
+class BridgeCodec:
+    """Safe JSON codec with explicit value handling and payload-size limits."""
+
+    def __init__(self, allow_nan=False, max_payload_bytes=10 * 1024 * 1024):
+        self.allow_nan = allow_nan
+        self.max_payload_bytes = max_payload_bytes
+        self._encoder = make_default_encoder(allow_nan=allow_nan)
+
+    def encode(self, value):
+        result = encode_value(value, allow_nan=self.allow_nan)
+        if len(result.encode('utf-8')) > self.max_payload_bytes:
+            raise CodecError(f'Payload exceeds {self.max_payload_bytes} bytes')
+        return result
+
+    def decode(self, payload):
+        if len(payload.encode('utf-8')) > self.max_payload_bytes:
+            raise CodecError(f'Payload exceeds {self.max_payload_bytes} bytes')
+        try:
+            return json.loads(payload)
+        except json.JSONDecodeError as exc:
+            raise CodecError(f'JSON decoding failed: {exc}') from exc
+
+    def _default_encoder(self, obj):
+        """Compatibility hook for callers that used the codec's JSON encoder."""
+        return self._encoder(obj)
+
+
+_default_codec = None
+
+
+def get_default_codec():
+    """Return the lazily-created default BridgeCodec instance."""
+    global _default_codec
+    if _default_codec is None:
+        _default_codec = BridgeCodec()
+    return _default_codec
+
+
+def encode(value, *, allow_nan=False):
+    """Encode a value with the default codec settings."""
+    if allow_nan:
+        return BridgeCodec(allow_nan=True).encode(value)
+    return get_default_codec().encode(value)
+
+
+def decode(payload):
+    """Decode a JSON payload with the default codec settings."""
+    return get_default_codec().decode(payload)
+
+
 # =============================================================================
 # REQUEST VALIDATION + HANDLERS + DISPATCH
 # =============================================================================
@@ -949,11 +1342,19 @@ def coerce_dict(value, key):
     return value
 
 
-def handle_call(params, *, force_json_markers, torch_allow_copy, allowed_modules, allow_private_attrs):
+def handle_call(
+    params,
+    *,
+    force_json_markers,
+    torch_allow_copy,
+    allowed_modules,
+    allow_private_attrs,
+    has_envelope_markers,
+):
     module_name = require_str(params, 'module')
     function_name = require_str(params, 'functionName')
-    args = deserialize(coerce_list(params.get('args'), 'args'))
-    kwargs = deserialize(coerce_dict(params.get('kwargs'), 'kwargs'))
+    args = deserialize(coerce_list(params.get('args'), 'args'), has_envelope_markers=has_envelope_markers)
+    kwargs = deserialize(coerce_dict(params.get('kwargs'), 'kwargs'), has_envelope_markers=has_envelope_markers)
     mod = import_allowed_module(module_name, allowed_modules)
     # function_name may be dotted ('Class.method') for @classmethod/@staticmethod
     # calls, which the generated wrapper routes through call() rather than an
@@ -963,61 +1364,13 @@ def handle_call(params, *, force_json_markers, torch_allow_copy, allowed_modules
     return serialize(res, force_json_markers=force_json_markers, torch_allow_copy=torch_allow_copy)
 
 
-def handle_instantiate(params, instances, *, allowed_modules, allow_private_attrs):
-    module_name = require_str(params, 'module')
-    class_name = require_str(params, 'className')
-    args = deserialize(coerce_list(params.get('args'), 'args'))
-    kwargs = deserialize(coerce_dict(params.get('kwargs'), 'kwargs'))
-    mod = import_allowed_module(module_name, allowed_modules)
-    cls = get_allowed_attr(mod, class_name, allow_private_attrs=allow_private_attrs)
-    obj = cls(*args, **kwargs)
-    handle_id = str(id(obj))
-    instances[handle_id] = obj
-    return handle_id
-
-
-def handle_call_method(params, instances, *, force_json_markers, torch_allow_copy, allow_private_attrs):
-    handle_id = require_str(params, 'handle')
-    method_name = require_str(params, 'methodName')
-    args = deserialize(coerce_list(params.get('args'), 'args'))
-    kwargs = deserialize(coerce_dict(params.get('kwargs'), 'kwargs'))
-    if handle_id not in instances:
-        raise InstanceHandleError(f'Unknown instance handle: {handle_id}')
-    obj = instances[handle_id]
-    # A @property / functools.cached_property is read, not called: the generated
-    # `get prop()` accessor emits callMethod(handle, name, []). Classify before
-    # touching the value (so cached_property is detected on its first read) and
-    # return the attribute directly; everything else is a bound method to call.
-    if is_accessor_attr(obj, method_name):
-        # An accessor is read, never called: a generated `get prop()` always
-        # sends empty args. Reject a malformed request that supplies any so it
-        # fails loudly instead of silently dropping the arguments.
-        if args or kwargs:
-            raise ProtocolError(f'Accessor {method_name!r} does not accept arguments')
-        res = get_allowed_attr(obj, method_name, allow_private_attrs=allow_private_attrs)
-    else:
-        func = get_allowed_attr(obj, method_name, allow_private_attrs=allow_private_attrs)
-        res = func(*args, **kwargs)
-    return serialize(res, force_json_markers=force_json_markers, torch_allow_copy=torch_allow_copy)
-
-
-def handle_dispose_instance(params, instances):
-    handle_id = require_str(params, 'handle')
-    if handle_id not in instances:
-        return False
-    del instances[handle_id]
-    return True
-
-
 def build_meta(
-    instances,
     *,
     bridge,
     pid,
     python_version,
     codec_fallback,
     arrow_available_override=None,
-    transport_info=None,
 ):
     """
     Build the bridge metadata payload.
@@ -1031,13 +1384,6 @@ def build_meta(
     instead of probing pyarrow. The Pyodide server forces markers to JSON
     unconditionally, so it advertises arrowAvailable=False regardless of whether
     pyarrow happens to be importable in the WASM environment.
-
-    transport_info: optional chunked-transport negotiation block (BridgeInfo
-    .transport). Core stays oblivious to framing policy -- it only echoes what
-    the I/O layer tells it. The subprocess server passes a {'frameProtocol',
-    'supportsChunking', 'maxFrameBytes'} dict when chunking is negotiated; the
-    Pyodide server passes None (single-frame, in-memory). When None the block is
-    omitted entirely (backward compatible: old bridges never emit it).
     """
     arrow = arrow_available() if arrow_available_override is None else arrow_available_override
     meta = {
@@ -1051,16 +1397,13 @@ def build_meta(
         'scipyAvailable': module_available('scipy'),
         'torchAvailable': module_available('torch'),
         'sklearnAvailable': module_available('sklearn'),
-        'instances': len(instances),
+        'instances': 0,
     }
-    if transport_info is not None:
-        meta['transport'] = transport_info
     return meta
 
 
 def dispatch_request(
     msg,
-    instances,
     *,
     bridge,
     pid,
@@ -1071,7 +1414,7 @@ def dispatch_request(
     arrow_available_override=None,
     allowed_modules=None,
     allow_private_attrs=False,
-    transport_info=None,
+    has_envelope_markers=True,
 ):
     """
     Validate and route a request, returning the fully-serialized response dict
@@ -1083,7 +1426,7 @@ def dispatch_request(
     the final encode_value() call, which the caller performs.
 
     allowed_modules: None (default) disables the import allowlist so existing
-    behavior is preserved. Supplying a set restricts call/instantiate imports to
+    behavior is preserved. Supplying a set restricts call imports to
     those modules (plus the stdlib the bridge itself needs) and raises
     ImportNotAllowedError otherwise. allow_private_attrs=False (default) blocks
     getattr of underscore-prefixed names; True restores unrestricted access. See
@@ -1101,34 +1444,19 @@ def dispatch_request(
             torch_allow_copy=torch_allow_copy,
             allowed_modules=allowed_modules,
             allow_private_attrs=allow_private_attrs,
+            has_envelope_markers=has_envelope_markers,
         )
-    elif method == 'instantiate':
-        result = handle_instantiate(
-            params, instances, allowed_modules=allowed_modules, allow_private_attrs=allow_private_attrs
-        )
-    elif method == 'call_method':
-        result = handle_call_method(
-            params,
-            instances,
-            force_json_markers=force_json_markers,
-            torch_allow_copy=torch_allow_copy,
-            allow_private_attrs=allow_private_attrs,
-        )
-    elif method == 'dispose_instance':
-        result = handle_dispose_instance(params, instances)
     elif method == 'meta':
         if python_version is None:
             import sys
             python_version = sys.version.split()[0]
         codec_fallback = 'json' if force_json_markers else 'none'
         result = build_meta(
-            instances,
             bridge=bridge,
             pid=pid,
             python_version=python_version,
             codec_fallback=codec_fallback,
             arrow_available_override=arrow_available_override,
-            transport_info=transport_info,
         )
     else:
         raise ProtocolError(f'Unknown method: {method}')