Merge pull request #297 from bbopen/refactor/0.9-transport-collapse

refactor(runtime)!: collapse the subprocess transport stack — single-attempt requests, merged pool, always-on framing

Author: bbopen

docs/public/llms-full.txt

@@ -16,24 +16,6 @@ These affect the Python bridge or decoded runtime behavior.
 | `TYWRAP_ALLOWED_MODULES`     | Python bridge | unset   | Comma- and/or whitespace-separated import allowlist; blank is unset, while a non-empty value permits only named modules plus bridge-required stdlib modules. See [SECURITY.md](https://github.com/bbopen/tywrap/blob/main/SECURITY.md). |
 | `TYWRAP_ALLOW_PRIVATE_ATTRS` | Python bridge | off     | Set to `1`, `true`, or `yes` to allow underscore-prefixed attribute access; otherwise it is blocked                                                                                                                                     |
 
-## Chunked transport (`tywrap-frame/1`)
-
-These negotiate the large-payload chunked transport. They are set **by the Node
-subprocess transport on the Python bridge it spawns** when `enableChunking` is
-requested — you do not normally set them by hand. Chunking is
-**subprocess-only** (it is the only backend with a real frame ceiling, the JSONL
-line-length limit); HTTP and Pyodide are single-frame and ignore these. If the
-bridge does not see all three agree, it stays single-frame and an oversize
-payload fails loud — there is no silent single-frame fallback. See
-[Transport framing](../transport-framing.md) and the
-[capability matrix](../transport-capabilities.md).
-
-| Variable                           | Scope         | Default | Purpose                                                                                         |
-| ---------------------------------- | ------------- | ------- | ----------------------------------------------------------------------------------------------- |
-| `TYWRAP_TRANSPORT_CHUNKING`        | Python bridge | unset   | Set to `1`/`true`/`yes` to enable `tywrap-frame/1` chunked framing on the bridge                |
-| `TYWRAP_TRANSPORT_FRAME_PROTOCOL`  | Python bridge | unset   | The framing protocol the JS side advertises; must equal `tywrap-frame/1` for chunking to enable |
-| `TYWRAP_TRANSPORT_MAX_FRAME_BYTES` | Python bridge | unset   | Per-frame UTF-8 byte ceiling for each frame's data slice (the JS side's JSONL `maxLineLength`)  |
-
 ## Logging
 
 These control the structured logger in the JavaScript runtime.

docs/reference/env-vars.md

@@ -2,19 +2,20 @@
 
 Every tywrap transport exposes a static, transport-level capability descriptor
 via `Transport.capabilities()`. The same descriptor is surfaced by
-`RpcClient.capabilities()` (it delegates to the held transport). It tells callers
-what the wire channel can carry and how it frames messages **without** a network
-round-trip.
+`RpcClient.capabilities()` (it delegates to the held transport). It tells
+callers what the wire channel can carry and how it frames messages **without** a
+network round-trip.
 
 This descriptor is deliberately separate from the bridge `meta` report
 (`BridgeInfo`, fetched via `RpcClient.getBridgeInfo()`):
 
 - The **transport descriptor** is authoritative for transport-level flags — what
-  bytes the channel moves and how it frames them. It does not depend on lifecycle
-  state, so it is safe to read before `init()` and after `dispose()`.
-- The **`BridgeInfo` meta report** is authoritative for the *Python environment* —
-  which optional libraries (`arrowAvailable`, `scipyAvailable`, `torchAvailable`,
-  `sklearnAvailable`) happen to be importable in the running interpreter.
+  bytes the channel moves and how it frames them. It does not depend on
+  lifecycle state, so it is safe to read before `init()` and after `dispose()`.
+- The **`BridgeInfo` meta report** is authoritative for the _Python environment_
+  — which optional libraries (`arrowAvailable`, `scipyAvailable`,
+  `torchAvailable`, `sklearnAvailable`) happen to be importable in the running
+  interpreter.
 
 When you need both questions answered — "can this transport carry Arrow **and**
 does this Python have pyarrow?" — consult both: the transport descriptor for the
@@ -35,47 +36,34 @@ interface TransportCapabilities {
 
 ## Matrix
 
-| Backend (transport)            | `backend`     | `supportsArrow` | `supportsBinary` | `supportsChunking`         | `supportsStreaming` | `maxFrameBytes`                  |
-| ------------------------------ | ------------- | --------------- | ---------------- | -------------------------- | ------------------- | -------------------------------- |
-| `SubprocessTransport` (Node)   | `subprocess`  | `true`          | `true`           | `true` when configured\*   | `false`             | JSONL line limit (default 100 MB) |
-| `HttpTransport`                | `http`        | `true`          | `true`           | `false`                    | `false`             | `Number.POSITIVE_INFINITY`       |
-| `PyodideTransport` (WASM)      | `pyodide`     | `false`         | `true`           | `false`                    | `false`             | `Number.POSITIVE_INFINITY`       |
-
-\* `SubprocessTransport.supportsChunking` reports the **configured** capability:
-`true` when the transport was created with `enableChunking: true` (the default for
-`NodeBridge`), `false` otherwise. Like `supportsArrow`, it is a static,
-lifecycle-independent property of the transport — it does **not** make a round
-trip and does **not** change across `init()`/`dispose()`. Whether the *connected*
-bridge actually advertised the `tywrap-frame/1` block is the negotiated fact,
-surfaced separately on `BridgeInfo.transport.supportsChunking` (from the `meta`
-probe). "Will chunking actually happen for an oversize payload" needs **both**
-`true`; against an old/incapable bridge the oversize payload fails loud — never a
-silent single-frame fallback. Chunking is subprocess-only — it is the only backend
-with a real frame ceiling (the JSONL line-length limit). See
+| Backend (transport)          | `backend`    | `supportsArrow` | `supportsBinary` | `supportsChunking`         | `supportsStreaming` | `maxFrameBytes`                    |
+| ---------------------------- | ------------ | --------------- | ---------------- | -------------------------- | ------------------- | ---------------------------------- |
+| `SubprocessTransport` (Node) | `subprocess` | `true`          | `true`           | `true` (always-on framing) | `false`             | Per-frame ceiling (default 100 MB) |
+| `HttpTransport`              | `http`       | `true`          | `true`           | `false`                    | `false`             | `Number.POSITIVE_INFINITY`         |
+| `PyodideTransport` (WASM)    | `pyodide`    | `false`         | `true`           | `false`                    | `false`             | `Number.POSITIVE_INFINITY`         |
+
+`SubprocessTransport.supportsChunking` is always `true`. The npm package ships
+the JS and Python framing peers together, so no runtime negotiation is needed.
+Chunking is subprocess-only; HTTP and Pyodide have no JSONL line ceiling. See
 [Transport framing](./transport-framing.md).
 
 `PooledTransport` (the multi-process Node path) reports the capabilities of the
 worker transport it distributes across — in practice `SubprocessTransport`. Its
 `capabilities()` is a **static** descriptor read from an un-initialized probe
-worker built by the same factory, so it reports the configured
-`supportsChunking` the workers carry (e.g. `true` when the pool's workers are
-created with `enableChunking: true`). The pool builds no live worker to answer a
-capability query. Each leased worker negotiates `tywrap-frame/1` independently
-inside its own `init()` — that per-worker negotiated fact lives on each worker's
-`BridgeInfo.transport.supportsChunking`, and a chunked request or response routed
-through a pool lease reassembles correctly.
+worker built by the same factory. Each leased worker always uses
+`tywrap-frame/1`, and chunked traffic through a lease reassembles correctly.
 
 ## Notes per flag
 
 ### `supportsArrow`
 
-Whether the transport can carry Arrow-encoded payloads (binary IPC frames) on the
-wire.
+Whether the transport can carry Arrow-encoded payloads (binary IPC frames) on
+the wire.
 
-- **subprocess / http**: `true`. The channel can move Arrow bytes. Whether Arrow is
-  actually *used* for a given response still depends on the Python side
-  (`BridgeInfo.arrowAvailable`) and the `TYWRAP_CODEC_FALLBACK` setting — those are
-  runtime/codec concerns, not transport-level ones.
+- **subprocess / http**: `true`. The channel can move Arrow bytes. Whether Arrow
+  is actually _used_ for a given response still depends on the Python side
+  (`BridgeInfo.arrowAvailable`) and the `TYWRAP_CODEC_FALLBACK` setting — those
+  are runtime/codec concerns, not transport-level ones.
 - **pyodide**: `false`. pyarrow is unavailable in WASM, so the Pyodide bootstrap
   forces JSON markers (`force_json_markers=True`) and reports
   `arrowAvailable: false`. The channel is JSON-only.
@@ -87,33 +75,29 @@ Whether the transport can carry arbitrary binary data (e.g. Python `bytes`).
 
 ### `supportsChunking` and `supportsStreaming`
 
-`supportsChunking` is implemented for the **subprocess** backend as of **0.8.0**:
-it splits one logical message across multiple `tywrap-frame/1` frames so a payload
-can exceed the JSONL line ceiling. The capability reports the **configured** path
-(`enableChunking`, `true` by default on `NodeBridge`) and is static (see the table
-note above); the per-bridge negotiated fact lives on
-`BridgeInfo.transport.supportsChunking`. HTTP and Pyodide stay `false` — they have
-no line ceiling and buffer the whole payload in one frame. See
-[Transport framing](./transport-framing.md) for the wire format and negotiation
-handshake.
+`supportsChunking` is implemented for the **subprocess** backend as of
+**0.8.0**: it splits one logical message across multiple `tywrap-frame/1` frames
+so a payload can exceed the JSONL line ceiling. The capability is statically
+`true` for subprocess. HTTP and Pyodide stay `false`. See
+[Transport framing](./transport-framing.md) for the wire format.
 
-`supportsStreaming` (incremental results for a single request) is `false` on every
-backend; it is not implemented in 0.8.0.
+`supportsStreaming` (incremental results for a single request) is `false` on
+every backend; it is not implemented in 0.8.0.
 
 ### `maxFrameBytes`
 
 Maximum size, in bytes, of a single wire frame the transport itself will accept.
-`Number.POSITIVE_INFINITY` means the transport imposes no frame ceiling of its own
-(a higher layer — e.g. the codec's payload limit, default 10 MB — may still cap
-the size).
+`Number.POSITIVE_INFINITY` means the transport imposes no frame ceiling of its
+own (a higher layer — e.g. the codec's payload limit, default 10 MB — may still
+cap the size).
 
 - **subprocess**: the JSONL line-length limit (`maxLineLength`, default
-  `100 * 1024 * 1024` = 100 MB). A response line larger than this raises a protocol
-  error.
-- **http**: `Number.POSITIVE_INFINITY`. The whole response body is read in one shot;
-  the transport imposes no frame limit.
-- **pyodide**: `Number.POSITIVE_INFINITY`. Calls are in-memory string passing with no
-  framing.
+  `100 * 1024 * 1024` = 100 MB). A response line larger than this raises a
+  protocol error.
+- **http**: `Number.POSITIVE_INFINITY`. The whole response body is read in one
+  shot; the transport imposes no frame limit.
+- **pyodide**: `Number.POSITIVE_INFINITY`. Calls are in-memory string passing
+  with no framing.
 
 ## Example