Merge pull request #123 from lann/wasi-sockets-tcp

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

Author: lannbot

contracts/embedder-api.md

@@ -47,7 +47,11 @@ host-import settlements are serviced by a settlement pump while no export
 call is in flight, so background tasks parked on host-call wakeups (clocks,
 fetches) progress without embedder traffic — embedder-never-acts operations
 still hang (never trap) and failures still surface on the next driving
-call.**
+call; amendment A12 (2026-08-12) makes result-position future sources
+normative for imports: 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) — see
+§"Streams and futures".**
 This document supersedes `descriptor-ir.md`'s interim
 "host value mapping" table as the destination for host-facing value shapes.
 The runtime's *raw* boundary (`instance.exports`, `HostImports`) keeps the
@@ -469,6 +473,26 @@ class DroppedError extends Error { … }    // awaiting a dropped future rejects
   deadlock-masking activity-lifetime footgun — R-fix review note 2), and
   cross-store reuse is a runtime-asserted error, not silent misbehavior
   (note 3).
+- **An import whose WIT result type is `future<T>` returns the future
+  source** (amendment A12, 2026-08-12). A thenable returned by the host
+  method — a `Promise<T>` or a `Future<T>` handle — is lowered as the
+  future itself: the import call completes immediately, and the future
+  settles on the producer's schedule. It is **not** adopted as the call's
+  async completion (the pre-A12 dispatch behavior, under which a sync-typed
+  import returning a Promise was a JSPI park request — and under which a
+  `Future` handle, being `PromiseLike`, was silently awaited and
+  re-lowered). The natural spelling of the `wasi:sockets@0.3` TCP `send`
+  shape — `send: func(data: stream<u8>) -> future<result<_, error-code>>`
+  as an `async` JS method whose promise resolves when transmission
+  completes — depends on this: the future settles only after post-return
+  guest action (the guest writes `data` after `send` returns), so adopting
+  the thenable is a livelock, not a semantics choice. A **rejected**
+  future-source promise stays a producer failure on the host-failure
+  channel (site-named, surfacing on the consuming call — same as every
+  producer), never a guest-visible err value: a fallible payload rides
+  *inside* the future (`future<result<…>>`), resolved as a result value.
+  Executable spec: `examples/guests/future-import` +
+  `runtime/tests/embedder/future_result_test.ts`.
 - **Stream values survive round trips** (amendment A5). A `stream`/`future`
   is an identity: lifting one that the host already handled — a
   host-created stream a guest passed back (result or import position), or

docs/architecture.md

@@ -88,8 +88,9 @@ contracts throughout the repo. Related documents:
   they are the ecosystem's most important interfaces and the conventions must
   serve them well — and a minimal WASI shim *package* (`wasi-shims/`, a
   separate deliverable; consumer-driven scope: p2 cli/io/clocks/random
-  baseline + p3 clocks, plus an à la carte p3 `wasi:sockets` UDP fragment
-  (`@deltic/wasi-shims/sockets`, adopted from polymorph-iroh's Deno host —
+  baseline + p3 clocks, plus an à la carte p3 `wasi:sockets` fragment
+  (`@deltic/wasi-shims/sockets` — UDP adopted from polymorph-iroh's Deno
+  host, client TCP for the wosh consumer;
   [#4](https://github.com/lann/deltic/issues/4)) that Deno-native hosts
   opt into and the default `wasiShims()` never carries).
 - **Componentizing JS/TS.** Guests are components built by external toolchains

examples/README.md

@@ -37,6 +37,7 @@ WASI imports** — so componentization needs no wasip1 adapter.
 | `backpressure-probe.component.wasm` | [`guests/backpressure-probe/wit/world.wit`](guests/backpressure-probe/wit/world.wit) | `toggle-around-yield: async func(x: u32) -> u32` (asserts backpressure, yields, clears backpressure) | ~40 KB |
 | `stream-echo.component.wasm` | [`guests/stream-echo/wit/world.wit`](guests/stream-echo/wit/world.wit) | `echo-doubled: async func(input: stream<u32>) -> stream<u32>` — consumes AND produces a stream in one export | ~60 KB |
 | `future-user.component.wasm` | [`guests/future-user/wit/world.wit`](guests/future-user/wit/world.wit) | `double-future: async func(f: future<u32>) -> u32` (awaits an imported future); `make-future: async func(x: u32) -> future<u32>` (resolves an exported one) | ~64 KB |
+| `future-import.component.wasm` | [`guests/future-import/wit/world.wit`](guests/future-import/wit/world.wit) | Host imports with future-bearing results (amendment A12; the `wasi:sockets@0.3` TCP shapes reduced to `u32`): `next-value: func() -> future<u32>`, `send-sink: func(stream<u8>) -> future<u32>`, `recv-pair: func() -> tuple<stream<u8>, future<u32>>`, driven by `run-next`/`run-send`/`run-recv` exports (`run-send` writes the stream only after the sync import returns — the livelock probe) | ~64 KB |
 | `test-suite.component.wasm` | [`guests/test-suite/wit/tests.wit`](guests/test-suite/wit/tests.wit) (vendored verbatim from polymorph-test's `polymorph:test@0.1.0`, TRACK C2-D) | Implements the `suite` world: imports `test-context`, exports `tests` (`all: async func() -> list<test-case>`). Six deterministic cases exercising pass/fail/skip, multi-message diagnostics, and a measurable-time case for budget plumbing — the ct-runner's (`../../ct-runner/`) fixture. | ~61 KB |
 
 

examples/build.sh

@@ -20,13 +20,13 @@ TARGET=wasm32-unknown-unknown
 BUILD_DIR=guests/build
 export CARGO_TARGET_DIR="$PWD/guests/target"
 
-GUESTS="hello values resources async-probe yield-only context-user backpressure-probe stream-echo stream-pass future-user test-suite"
+GUESTS="hello values resources async-probe yield-only context-user backpressure-probe stream-echo stream-pass future-user future-import test-suite"
 
 # wasm-tools validation features per guest (component-model always on;
 # CM 0.3 async guests additionally need the cm-async feature).
 features_for() {
   case "$1" in
-    async-probe|yield-only|context-user|backpressure-probe|stream-echo|stream-pass|future-user|test-suite)
+    async-probe|yield-only|context-user|backpressure-probe|stream-echo|stream-pass|future-user|future-import|test-suite)
       echo "component-model,cm-async" ;;
     *) echo "component-model" ;;
   esac