wasi-shims: client TCP for the à la carte wasi:sockets fragment; embedder A12 (future-typed import results)

[lannbot]

The decision

@deltic/wasi-shims/sockets grows the client TCP surface — the shape the wosh listener bridges through (listener-core/src/tcp.rs: create → connect → send(stream<u8>) → receive()) and the smoke-c0 leg-4 composed-websocket shopping list names. Same à la carte stance as the UDP fragment (#122): subpath export, never in wasiShims(), absent from the release bundle. Over stable Deno.connect (TCP needs no unstable flag, only --allow-net).

The runtime half: amendment A12

The TCP WIT exposes a dispatch gap: send: func(data: stream<u8>) -> future<result<_, error-code>> is a sync WIT func whose returned future settles only after post-return guest action (the guest writes data after send returns). The import wrapper adopted any thenable return as the call's async completion — for this shape that's a livelock (park until a future that needs the guest to run), and it also silently mis-lowered returned Future handles (they're PromiseLike). The contract's producer table already promised "for future<T>, a Promise<T> or Future<T>" at lowering; dispatch preempted it.

A12 (contracts/embedder-api.md §"Streams and futures"): an import whose WIT result type is future<T> treats a thenable return as the future source — the import completes immediately; the future settles on the producer's schedule; rejections stay producer failures (site-named, host-failure channel), never a guest-visible err. Pinned by a new fixture guest (examples/guests/future-import) driving the three shapes: bare future<u32> return, the tcp-send shape with the post-return stream write (the livelock probe), and the tcp-receive tuple<stream<u8>, future<u32>> (which already worked via the recursive value adapter — now pinned).

TCP semantics (yardstick: wasmtime-wasi p3 + TcpSocketOperationalSemantics-0.3.0, client half)

• send/receive never throw — no WIT result of their own; every failure rides the future as a result value ({ kind: \"err\", value: error-code }).
• receive returns [async generator, promise] — generator deliberately, not ReadableStream: the runtime pump runs an abandoned generator's finally (releasing the conn), where a ReadableStream source is only unlocked, never cancelled.
• Shared ownership per the WIT: the OS socket closes when the handle AND both pumps have retired — streams remain functional after the guest drops the tcp-socket.
• The receive stream ends cleanly on both FIN and abnormal close (never fake data); the future distinguishes (ok/err). Reader drop settles ok (canceller-is-observer, the A8 logic).
• bind/listen/socket options stay loudly absent: Deno.connect can't bind a local address; the accept path (stream<tcp-socket>) waits for a consumer that links it (iroh direct path: p3 wasi:sockets UDP providers #4).
• Peer traps while consuming send's stream are producer failures, not socket errors.

Not in scope

The composed E2E — a real guest linking wasi:sockets/types@0.3 TCP through this provider — lands with the wosh consumer smoke; the runtime lowering shapes are pinned by the fixture, the provider semantics by 16 loopback unit tests against a real Deno.listen server.

Gates

Full just gates pass on this tree: build, test-rust, test-protocol, test-runtime (481, +4), test-wasi-shims (88, +17), test-ct-runner, test-bundle, publish-check, examples, test-translate, conformance, sched-seeds, test-ports, test-webrtc, shells (sm/jsc/node/bun), browsers (chromium+firefox), websocket-conformance (55/55), smoke-tls, smoke-c0.

Also rides along: ports deno.lock workspace-link refresh (protocol 0.2.0, pre-existing drift from the A10 publish).

Refs #4.