@polyengine/wasi 0.1.0-pre.g633468a

package/esm/http.js

@@ -0,0 +1,663 @@
+// `wasi:http@0.3` — the OUTBOUND half (`types` + `client`), served over
+// `fetch`. À la carte (`@polyengine/wasi/http`): fetch is universal across
+// the JS runtimes, but this fragment grants NETWORK EGRESS — unscoped,
+// with no allowlist or address check (docs/security.md) — and the
+// default `wasi()` merge carries only ambient, side-effect-benign
+// capabilities (mod.ts "COMPOSITION") — portability is not the
+// criterion, capability is.
+//
+// Interfaces served (WIT: wasi:http 0.3.1, released with the WASI 0.3
+// consolidation — WebAssembly/WASI v0.3.1, proposals/http/wit; vendored
+// copy for the fixture guest under examples/guests/http-fetch/wit):
+//
+//   wasi:http/types@0.3  — resources fields, request, request-options,
+//                          response (constructors and all accessors)
+//   wasi:http/client@0.3 — send: async func(request) -> result<response, error-code>
+//
+// `handler` (the middleware-chain interface, same shape as `client`) is
+// deliberately NOT registered: serving a middleware's upstream from fetch
+// would silently flatten a chain into the network. An embedder that means
+// exactly that can register this fragment's `send` under its own handler
+// key.
+//
+// VERSION KEYS: 0.3.x releases fold onto the `@0.3` compatibility track
+// (contracts/embedder-api.md §"Version canonicalization"), so the
+// default registration serves every released 0.3.x with one provider —
+// the same flagship track-key pattern as the rest of this package. The
+// pre-consolidation rc SNAPSHOTS (`0.3.0-rc-*`) are prereleases, which
+// resolve exact-only: a guest pinned to one names it via
+// `http({ version: "0.3.0-rc-..." })`, which re-keys the fragment at
+// that exact id instead.
+//
+// Body/trailers plumbing is the same stream+future choreography the TCP
+// provider proved: constructors return `[resource, transmission-future]`
+// (the future is a Promise — amendment A12 lowers it as the future
+// source), `consume-body` returns `[stream<u8>, trailers-future]`, and
+// guest-abandoned streams are retired by the runtime's A13 machinery
+// (`ReadableStream` sources are cancel()ed, which aborts the underlying
+// fetch body).
+//
+// Recorded divergences (fetch exposes no lower transport):
+//
+//   * Redirects are NOT followed (`redirect: "manual"`, matching
+//     wasmtime's plain-transport behavior); in BROWSERS a manual redirect
+//     is an opaque response (the platform hides the 3xx), a
+//     browser-only divergence.
+//   * Request trailers cannot be transmitted (fetch has no trailer
+//     channel): a trailers future resolving `some(trailers)` fails the
+//     transmission with `internal-error` rather than silently dropping
+//     data; resolving to an ERROR aborts the request, per the WIT.
+//     Response trailers always resolve `none` (fetch cannot read them).
+//   * Request bodies are BUFFERED before transmission (streaming request
+//     bodies via `duplex: "half"` are not universal); the transmission
+//     future settles only after the fetch, so the guest still observes
+//     truthful completion. Response bodies stream through unbuffered.
+//   * `set-connect-timeout` answers `not-supported` (fetch exposes no
+//     connect phase); first-byte and between-bytes timeouts are REAL,
+//     enforced with timers around the response-body reads.
+//   * Platform-managed headers (host, content-length, and the rest of
+//     fetch's forbidden list) are silently owned by the platform, not by
+//     the `fields` the guest set.
+//
+// Error model: `client.send` and the fallible fields/options methods
+// throw branded `ComponentException`s whose payloads use the WIT case
+// names VERBATIM (`DNS-timeout`, `TLS-protocol-error`, `internal-error` —
+// A10: case names are data, kebab-case as written, including capitals).
+// Fetch failures are TypeErrors with prose; a small sniff table maps the
+// recognizable ones and everything else is `internal-error(message)`.
+import { ComponentException } from "@polyengine/runtime/embedder";
+/** The compatibility track the fragment registers on by default. */
+export const HTTP_TRACK = "0.3";
+const OK = { kind: "ok" };
+function httpError(payload, detail) {
+    return new ComponentException(payload, `wasi:http: ${detail}`);
+}
+function headerError(kind, detail) {
+    return new ComponentException({ kind }, `wasi:http/types: ${detail}`);
+}
+/** Map a fetch failure onto `error-code` (sniff table + honest catch-all). */
+export function mapFetchError(e) {
+    // Deno/undici wrap the transport detail in the `cause` chain; sniff the
+    // whole chain, report the top-level message.
+    let message = e instanceof Error ? e.message : String(e);
+    const parts = [];
+    for (let at = e; at instanceof Error; at = at.cause)
+        parts.push(at.message);
+    const m = parts.join(" | ").toLowerCase();
+    message = parts[0] ?? message;
+    if (m.includes("refused"))
+        return { kind: "connection-refused" };
+    if (m.includes("dns error") || m.includes("name not resolved") || m.includes("getaddrinfo")) {
+        return { kind: "DNS-error", value: { rcode: undefined, infoCode: undefined } };
+    }
+    if (m.includes("timed out") || m.includes("timeout"))
+        return { kind: "connection-timeout" };
+    if (m.includes("tls") || m.includes("certificate") || m.includes("ssl")) {
+        return { kind: "TLS-protocol-error" };
+    }
+    if (m.includes("reset"))
+        return { kind: "connection-terminated" };
+    return { kind: "internal-error", value: message };
+}
+/** Collect a body source to bytes (the buffered-request divergence). */
+async function collectBody(source) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of source) {
+        const bytes = chunk instanceof Uint8Array ? chunk : Uint8Array.from(chunk);
+        chunks.push(bytes);
+        total += bytes.length;
+    }
+    const out = new Uint8Array(total);
+    let at = 0;
+    for (const c of chunks) {
+        out.set(c, at);
+        at += c.length;
+    }
+    return out;
+}
+// --- field syntax ---------------------------------------------------------------
+/** RFC 9110 token (field-name). */
+const FIELD_NAME = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+function validFieldValue(v) {
+    // No NUL / CR / LF — the transport-splitting bytes.
+    return !v.some((b) => b === 0x00 || b === 0x0a || b === 0x0d);
+}
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+/**
+ * `wasi:http` provider fragment (exact version keys — see the module
+ * header). The resource classes are built per fragment so the `onCall`
+ * observer is scoped to it.
+ */
+export function http(options = {}) {
+    const onCall = options.onCall ?? (() => { });
+    const v = options.version ?? HTTP_TRACK;
+    // --- fields -----------------------------------------------------------------
+    class Fields {
+        /** Entries in original casing and insertion order. */
+        entries = [];
+        mutable = true;
+        constructor() {
+            onCall("fields.constructor");
+        }
+        static fromList(entries) {
+            onCall("fields.from-list");
+            const f = internalFields([], true);
+            for (const [name, value] of entries) {
+                if (!FIELD_NAME.test(name)) {
+                    throw headerError("invalid-syntax", `from-list: invalid field name ${JSON.stringify(name)}`);
+                }
+                if (!validFieldValue(value)) {
+                    throw headerError("invalid-syntax", `from-list: invalid value for ${JSON.stringify(name)}`);
+                }
+                f.entries.push([name, value.slice()]);
+            }
+            return f;
+        }
+        get(name) {
+            onCall("fields.get");
+            const n = name.toLowerCase();
+            return this.entries.filter(([k]) => k.toLowerCase() === n).map(([, v]) => v.slice());
+        }
+        has(name) {
+            onCall("fields.has");
+            const n = name.toLowerCase();
+            return this.entries.some(([k]) => k.toLowerCase() === n);
+        }
+        set(name, value) {
+            onCall("fields.set");
+            requireMutableFields(this, "fields.set");
+            if (!FIELD_NAME.test(name)) {
+                throw headerError("invalid-syntax", `set: invalid field name ${JSON.stringify(name)}`);
+            }
+            for (const one of value) {
+                if (!validFieldValue(one)) {
+                    throw headerError("invalid-syntax", `set: invalid value for ${JSON.stringify(name)}`);
+                }
+            }
+            const n = name.toLowerCase();
+            this.entries = this.entries.filter(([k]) => k.toLowerCase() !== n);
+            for (const one of value)
+                this.entries.push([name, one.slice()]);
+        }
+        delete(name) {
+            onCall("fields.delete");
+            requireMutableFields(this, "fields.delete");
+            const n = name.toLowerCase();
+            this.entries = this.entries.filter(([k]) => k.toLowerCase() !== n);
+        }
+        getAndDelete(name) {
+            onCall("fields.get-and-delete");
+            requireMutableFields(this, "fields.get-and-delete");
+            const n = name.toLowerCase();
+            const out = this.entries.filter(([k]) => k.toLowerCase() === n).map(([, v]) => v);
+            this.entries = this.entries.filter(([k]) => k.toLowerCase() !== n);
+            return out;
+        }
+        append(name, value) {
+            onCall("fields.append");
+            requireMutableFields(this, "fields.append");
+            if (!FIELD_NAME.test(name)) {
+                throw headerError("invalid-syntax", `append: invalid field name ${JSON.stringify(name)}`);
+            }
+            if (!validFieldValue(value)) {
+                throw headerError("invalid-syntax", `append: invalid value for ${JSON.stringify(name)}`);
+            }
+            this.entries.push([name, value.slice()]);
+        }
+        copyAll() {
+            onCall("fields.copy-all");
+            return this.entries.map(([k, v]) => [k, v.slice()]);
+        }
+        clone() {
+            onCall("fields.clone");
+            return internalFields(this.entries.map(([k, v]) => [k, v.slice()]), true);
+        }
+        [Symbol.dispose]() {
+            // Plain data; nothing to release.
+        }
+    }
+    /** Mutability guard usable on Object.create-minted views (no #-brand). */
+    function requireMutableFields(f, what) {
+        if (!f.mutable) {
+            throw headerError("immutable", `${what}: these fields are immutable`);
+        }
+    }
+    /** Mint a Fields without the WIT constructor's onCall. */
+    function internalFields(entries, mutable) {
+        const f = Object.create(Fields.prototype);
+        f.entries = entries;
+        f.mutable = mutable;
+        return f;
+    }
+    function fieldsFromFetchHeaders(h) {
+        const entries = [];
+        h.forEach((value, name) => entries.push([name, encoder.encode(value)]));
+        return internalFields(entries, false);
+    }
+    // --- request-options ----------------------------------------------------------
+    class RequestOptions {
+        connectTimeout;
+        firstByteTimeout;
+        betweenBytesTimeout;
+        mutable = true;
+        constructor() {
+            onCall("request-options.constructor");
+        }
+        getConnectTimeout() {
+            onCall("request-options.get-connect-timeout");
+            return this.connectTimeout;
+        }
+        setConnectTimeout(_duration) {
+            onCall("request-options.set-connect-timeout");
+            requireMutableOptions(this, "set-connect-timeout");
+            // fetch exposes no connect phase: storing the value would imply
+            // enforcement that cannot happen — the honest answer is refusal.
+            throw new ComponentException({ kind: "not-supported" }, "wasi:http/types: set-connect-timeout: fetch exposes no connect phase");
+        }
+        getFirstByteTimeout() {
+            onCall("request-options.get-first-byte-timeout");
+            return this.firstByteTimeout;
+        }
+        setFirstByteTimeout(duration) {
+            onCall("request-options.set-first-byte-timeout");
+            requireMutableOptions(this, "set-first-byte-timeout");
+            this.firstByteTimeout = duration;
+        }
+        getBetweenBytesTimeout() {
+            onCall("request-options.get-between-bytes-timeout");
+            return this.betweenBytesTimeout;
+        }
+        setBetweenBytesTimeout(duration) {
+            onCall("request-options.set-between-bytes-timeout");
+            requireMutableOptions(this, "set-between-bytes-timeout");
+            this.betweenBytesTimeout = duration;
+        }
+        clone() {
+            onCall("request-options.clone");
+            const c = Object.create(RequestOptions.prototype);
+            c.connectTimeout = this.connectTimeout;
+            c.firstByteTimeout = this.firstByteTimeout;
+            c.betweenBytesTimeout = this.betweenBytesTimeout;
+            c.mutable = true;
+            return c;
+        }
+        [Symbol.dispose]() {
+            // Plain data.
+        }
+    }
+    /** Mutability guard usable on clone-minted options (no #-brand). */
+    function requireMutableOptions(o, what) {
+        if (!o.mutable) {
+            throw new ComponentException({ kind: "immutable" }, `wasi:http/types: ${what}: this request-options is immutable`);
+        }
+    }
+    // --- request --------------------------------------------------------------------
+    class Request {
+        method = { kind: "get" };
+        pathWithQuery;
+        scheme;
+        authority;
+        headers;
+        contents;
+        trailers;
+        options;
+        /** Settles the transmission future returned by `new`. */
+        settleTransmission;
+        consumed = false;
+        sent = false;
+        constructor() { }
+        // The WIT static is literally named `new` — legal as a JS static.
+        static "new"(headers, contents, trailers, options) {
+            onCall("request.new");
+            const r = new Request();
+            r.headers = headers;
+            headers.mutable = false; // ownership transferred; views are immutable
+            r.contents = contents;
+            r.trailers = trailers;
+            r.options = options;
+            if (options !== undefined)
+                options.mutable = false;
+            const transmission = new Promise((resolve) => {
+                r.settleTransmission = resolve;
+            });
+            return [r, transmission];
+        }
+        getMethod() {
+            onCall("request.get-method");
+            return this.method;
+        }
+        setMethod(method) {
+            onCall("request.set-method");
+            if (method.kind === "other" && !FIELD_NAME.test(method.value)) {
+                throw new ComponentException(null, "wasi:http/types: set-method: invalid method token");
+            }
+            this.method = method;
+        }
+        getPathWithQuery() {
+            onCall("request.get-path-with-query");
+            return this.pathWithQuery;
+        }
+        setPathWithQuery(pathWithQuery) {
+            onCall("request.set-path-with-query");
+            if (pathWithQuery !== undefined && /[ \t\r\n#]/.test(pathWithQuery)) {
+                throw new ComponentException(null, "wasi:http/types: set-path-with-query: invalid path");
+            }
+            this.pathWithQuery = pathWithQuery;
+        }
+        getScheme() {
+            onCall("request.get-scheme");
+            return this.scheme;
+        }
+        setScheme(scheme) {
+            onCall("request.set-scheme");
+            if (scheme?.kind === "other" && !/^[A-Za-z][A-Za-z0-9+.-]*$/.test(scheme.value)) {
+                throw new ComponentException(null, "wasi:http/types: set-scheme: invalid scheme");
+            }
+            this.scheme = scheme;
+        }
+        getAuthority() {
+            onCall("request.get-authority");
+            return this.authority;
+        }
+        setAuthority(authority) {
+            onCall("request.set-authority");
+            if (authority !== undefined && /[ \t\r\n/#?@]/.test(authority.replace(/@/, ""))) {
+                throw new ComponentException(null, "wasi:http/types: set-authority: invalid authority");
+            }
+            this.authority = authority;
+        }
+        getOptions() {
+            onCall("request.get-options");
+            return this.options;
+        }
+        getHeaders() {
+            onCall("request.get-headers");
+            return internalFields(this.headers.entries.map(([k, v]) => [k, v.slice()]), false);
+        }
+        static consumeBody(request, res) {
+            onCall("request.consume-body");
+            return consumeStoredBody(request, res);
+        }
+        [Symbol.dispose]() {
+            // A request dropped without transmission: the transmission future
+            // must still settle (a pending future the guest awaits would
+            // otherwise hang forever).
+            if (!this.sent && !this.consumed) {
+                this.settleTransmission({
+                    kind: "err",
+                    value: { kind: "internal-error", value: "request dropped without being sent" },
+                });
+            }
+        }
+    }
+    // --- response -------------------------------------------------------------------
+    class Response {
+        statusCode = 200;
+        headers;
+        /** Guest-constructed responses carry sources; fetch responses carry the body. */
+        contents;
+        trailers;
+        fetchBody = null;
+        settleTransmission;
+        /** Timeouts inherited from the request's options (fetch responses). */
+        firstByteTimeout;
+        betweenBytesTimeout;
+        consumed = false;
+        constructor() { }
+        // The WIT static is literally named `new` — legal as a JS static.
+        static "new"(headers, contents, trailers) {
+            onCall("response.new");
+            const r = new Response();
+            r.headers = headers;
+            headers.mutable = false;
+            r.contents = contents;
+            r.trailers = trailers;
+            const transmission = new Promise((resolve) => {
+                r.settleTransmission = resolve;
+            });
+            return [r, transmission];
+        }
+        /** A response wrapping a live fetch result (internal). */
+        static fromFetch(resp, options) {
+            const r = new Response();
+            r.statusCode = resp.status;
+            r.headers = fieldsFromFetchHeaders(resp.headers);
+            r.fetchBody = resp.body;
+            r.firstByteTimeout = options?.firstByteTimeout;
+            r.betweenBytesTimeout = options?.betweenBytesTimeout;
+            return r;
+        }
+        getStatusCode() {
+            onCall("response.get-status-code");
+            return this.statusCode;
+        }
+        setStatusCode(statusCode) {
+            onCall("response.set-status-code");
+            if (!Number.isInteger(statusCode) || statusCode < 100 || statusCode > 999) {
+                throw new ComponentException(null, "wasi:http/types: set-status-code: invalid status code");
+            }
+            this.statusCode = statusCode;
+        }
+        getHeaders() {
+            onCall("response.get-headers");
+            return internalFields(this.headers.entries.map(([k, v]) => [k, v.slice()]), false);
+        }
+        static consumeBody(response, res) {
+            onCall("response.consume-body");
+            if (response.fetchBody !== null || (response.contents === undefined && response.trailers === undefined)) {
+                return consumeFetchBody(response, res);
+            }
+            return consumeStoredBody(response, res);
+        }
+        [Symbol.dispose]() {
+            if (this.fetchBody !== null && !this.consumed) {
+                this.fetchBody.cancel().catch(() => {
+                    // The connection is being discarded; failures have no audience.
+                });
+            }
+            if (this.settleTransmission !== undefined && !this.consumed) {
+                this.settleTransmission({
+                    kind: "err",
+                    value: { kind: "internal-error", value: "response dropped without being sent" },
+                });
+            }
+        }
+    }
+    // --- body consumption (shared) ---------------------------------------------------
+    /** Consume a guest-constructed body: pass the stored sources through. */
+    function consumeStoredBody(holder, res) {
+        if (holder.consumed) {
+            return [
+                [],
+                Promise.resolve({
+                    kind: "err",
+                    value: { kind: "internal-error", value: "body already consumed" },
+                }),
+            ];
+        }
+        holder.consumed = true;
+        const contents = holder.contents;
+        const trailers = holder.trailers ??
+            Promise.resolve({ kind: "ok", value: undefined });
+        // The consumer reports its outcome through `res`; that is what settles
+        // the producer-side transmission future.
+        const settle = holder.settleTransmission;
+        if (settle !== undefined) {
+            Promise.resolve(res).then((r) => settle(r), () => settle({ kind: "err", value: { kind: "internal-error", value: "consumer failed" } }));
+        }
+        const source = (async function* () {
+            if (contents === undefined)
+                return;
+            for await (const chunk of contents) {
+                yield chunk instanceof Uint8Array ? chunk : Uint8Array.from(chunk);
+            }
+        })();
+        return [source, Promise.resolve(trailers).then((t) => t)];
+    }
+    /** Consume a fetch response body, with the real byte timeouts. */
+    function consumeFetchBody(response, _res) {
+        if (response.consumed) {
+            return [
+                [],
+                Promise.resolve({
+                    kind: "err",
+                    value: { kind: "internal-error", value: "body already consumed" },
+                }),
+            ];
+        }
+        response.consumed = true;
+        const body = response.fetchBody;
+        let settle;
+        const done = new Promise((resolve) => (settle = resolve));
+        const firstByteMs = toMs(response.firstByteTimeout);
+        const betweenBytesMs = toMs(response.betweenBytesTimeout);
+        const source = (async function* () {
+            if (body === null) {
+                settle({ kind: "ok", value: undefined }); // no trailers over fetch
+                return;
+            }
+            const reader = body.getReader();
+            let first = true;
+            try {
+                for (;;) {
+                    const timeoutMs = first ? firstByteMs : betweenBytesMs;
+                    let r;
+                    try {
+                        r = await readWithTimeout(reader, timeoutMs);
+                    }
+                    catch (e) {
+                        settle({
+                            kind: "err",
+                            value: e === TIMED_OUT
+                                ? { kind: first ? "HTTP-response-timeout" : "connection-read-timeout" }
+                                : mapFetchError(e),
+                        });
+                        return;
+                    }
+                    first = false;
+                    if (r.done) {
+                        settle({ kind: "ok", value: undefined }); // clean end; no trailers over fetch
+                        return;
+                    }
+                    if (r.value.length > 0)
+                        yield r.value;
+                }
+            }
+            finally {
+                settle({ kind: "ok", value: undefined }); // reader dropped: canceller observes
+                reader.cancel().catch(() => {
+                    // Discarding the rest of the body; failures have no audience.
+                });
+                reader.releaseLock();
+            }
+        })();
+        return [source, done];
+    }
+    const TIMED_OUT = Symbol("timed out");
+    function toMs(ns) {
+        return ns === undefined ? undefined : Number(ns / 1000000n);
+    }
+    function readWithTimeout(reader, timeoutMs) {
+        const read = reader.read();
+        if (timeoutMs === undefined)
+            return read;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => reject(TIMED_OUT), timeoutMs);
+            read.then((r) => {
+                clearTimeout(timer);
+                resolve(r);
+            }, (e) => {
+                clearTimeout(timer);
+                reject(e);
+            });
+        });
+    }
+    // --- client.send over fetch --------------------------------------------------------
+    async function send(request) {
+        onCall("client.send");
+        if (request.sent || request.consumed) {
+            throw httpError({ kind: "internal-error", value: "request already sent or consumed" }, "client.send: request already sent or consumed");
+        }
+        request.sent = true;
+        // URL assembly. Scheme defaults to HTTPS ("the implementation may
+        // choose an appropriate default"); HTTP(S) requires an authority.
+        const scheme = request.scheme === undefined
+            ? "https"
+            : request.scheme.kind === "other"
+                ? request.scheme.value.toLowerCase()
+                : request.scheme.kind.toLowerCase();
+        if (scheme !== "http" && scheme !== "https") {
+            throw httpError({ kind: "internal-error", value: `fetch cannot carry scheme '${scheme}'` }, `client.send: unsupported scheme '${scheme}'`);
+        }
+        if (request.authority === undefined) {
+            throw httpError({ kind: "HTTP-request-URI-invalid" }, "client.send: no authority");
+        }
+        const path = request.pathWithQuery ?? "";
+        const url = `${scheme}://${request.authority}${path.startsWith("/") || path === "" ? path : "/" + path}`;
+        const method = request.method.kind === "other"
+            ? request.method.value.toUpperCase()
+            : request.method.kind.toUpperCase();
+        const headers = new Headers();
+        for (const [name, value] of request.headers.entries) {
+            try {
+                headers.append(name, decoder.decode(value));
+            }
+            catch (e) {
+                throw httpError({ kind: "internal-error", value: `header '${name}' refused by the platform` }, `client.send: ${e}`);
+            }
+        }
+        // Buffered request body (module header divergence), then the trailers
+        // future decides whether the request may be transmitted at all.
+        let body;
+        if (request.contents !== undefined) {
+            body = await collectBody(request.contents);
+        }
+        const trailersResult = await request.trailers;
+        if (trailersResult.kind === "err") {
+            // Per the WIT: a trailers error closes the underlying connection —
+            // here, the request is never transmitted.
+            const err = { kind: "err", value: trailersResult.value };
+            request.settleTransmission(err);
+            throw httpError(trailersResult.value, "client.send: request trailers resolved to an error");
+        }
+        if (trailersResult.value !== undefined) {
+            const err = {
+                kind: "internal-error",
+                value: "fetch cannot transmit request trailers",
+            };
+            request.settleTransmission({ kind: "err", value: err });
+            throw httpError(err, "client.send: request trailers are not transmissible over fetch");
+        }
+        let resp;
+        try {
+            resp = await fetch(url, {
+                method,
+                headers,
+                body: body === undefined || body.length === 0 ? undefined : body,
+                redirect: "manual",
+                cache: "no-store",
+                credentials: "omit",
+            });
+        }
+        catch (e) {
+            const code = mapFetchError(e);
+            request.settleTransmission({ kind: "err", value: code });
+            throw httpError(code, `client.send: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        request.settleTransmission(OK);
+        return Response.fromFetch(resp, request.options);
+    }
+    return {
+        imports: {
+            [`wasi:http/types@${v}`]: { Fields, Request, RequestOptions, Response },
+            [`wasi:http/client@${v}`]: { send },
+        },
+        Fields: Fields,
+        Request: Request,
+        RequestOptions: RequestOptions,
+        Response: Response,
+        send: send,
+    };
+}

package/esm/internal/cli_shared.js

@@ -0,0 +1,26 @@
+// INTERNAL shared vocabulary of the `wasi:cli` impls (cli.ts capture,
+// cli_stdio.ts host-stdio) — not a package export; the public home of
+// these names is `@polyengine/wasi/cli`. Extracting them here is what keeps
+// the two IMPLS independent of each other: an impl imports the
+// vocabulary, never its sibling.
+import { defineBrand, WASI_EXIT } from "@polyengine/protocol";
+/** Raised by `exit()` when `throwOnExit` is set (contract: "option to throw a named ExitError"). */
+export class ExitError extends Error {
+    ok;
+    code;
+    constructor(ok, code) {
+        super(`wasi:cli/exit#exit(${ok ? "success" : "failure"}${code === undefined ? "" : `, code ${code}`})`);
+        this.ok = ok;
+        this.code = code;
+        this.name = "ExitError";
+    }
+}
+// A9 brand: an exit unwind propagates out through the embedder and any host
+// frames in between, so it must be recognizable across runtime copies
+// (contracts/embedder-api.md §"Module identity", issue #83).
+defineBrand(ExitError.prototype, WASI_EXIT);
+/** `terminal-input`/`terminal-output` are opaque resources; never produced (no terminal). */
+export class TerminalInput {
+}
+export class TerminalOutput {
+}