@polyengine/wasi 0.1.0-pre.g633468a

package/esm/mod.js

@@ -0,0 +1,80 @@
+// `@polyengine/wasi` — the WASI providers for polyengine hosts, and the
+// executable check that the embedder conventions
+// (`@polyengine/runtime/embedder`) serve WASI (contracts/embedder-api.md C2
+// checklist item 7; docs/architecture.md §2 keeps implementations out of
+// the RUNTIME — this package is where they live). Scope: p2
+// baseline + p3 clocks + à la carte sockets on BOTH tracks (the
+// poll-shaped `@0.2` surface std::net links, and `@0.3` UDP + TCP
+// client/listener; one node-builtins backend serving Deno and Node;
+// `@polyengine/wasi/sockets`, issue #4, server-JS hosts only). Sockets is
+// deliberately not merged here: this root module stays host-agnostic
+// web-platform code, and `wasi()` merges only AMBIENT, side-effect-
+// benign capabilities (time, entropy, stdio capture, an empty
+// filesystem). Anything granting network egress or host storage is
+// opt-in regardless of how portable it is — sockets, the fetch-backed
+// http fragment, the host-stdio cli impl (`./cli-stdio` — real
+// stdin/stdout/terminal access; the unqualified `./cli` stays the
+// capture impl), and the real filesystem impls (`./filesystem-node` =
+// node:fs, `./filesystem-web` = OPFS; the unqualified `./filesystem`
+// stays the empty-preopens stub).
+//
+// COMPOSITION — three forms, coarsest to finest (virtualization scenarios
+// pinned by tests/version_resolution_test.ts):
+//
+// 1. Batteries: `instantiate(a, { ...wasi() })`.
+// 2. À la carte fragments: every IMPL is its own subpath export
+//    (`@polyengine/wasi/{cli,cli-stdio,clocks,filesystem,filesystem-node,`
+//    `filesystem-web,http,io,random,sockets}`) and
+//    a plain `{ imports }` record — hand-merge exactly the set you mean:
+//    `{ ...io().imports, ...clocks().imports }`. Fragment dependencies:
+//    io.ts is the package's shared vocabulary (the parking kernel and
+//    the stream classes) — cli, clocks, and the real filesystem and
+//    sockets impls all ride it; random and http stand alone. Impl
+//    machinery that is not itself a fragment lives under src/internal/
+//    (never exported). Naming convention as impls multiply: one
+//    subpath per impl; the unqualified name is the batteries impl
+//    (`./filesystem` = empty preopens), alternatives carry their backend
+//    (`./filesystem-node` = node:fs with explicit preopens,
+//    `./filesystem-web` = OPFS).
+// 3. Per-interface override: the merged record is a plain object keyed by
+//    TRACK keys (`wasi:random/random@0.2`), so later spreads replace
+//    single interfaces wholesale:
+//    `{ ...wasi(), "wasi:random/random@0.2": myStub }`.
+//    Replace the track key, don't add an exact-versioned sibling — the
+//    resolver refuses track+exact coexistence on one track as ambiguous
+//    (contracts/embedder-api.md §"Version canonicalization"). Per-guest
+//    virtualization needs no version tricks anyway: compose a different
+//    record per `instantiate` call. Some fragments also take the finer
+//    knob directly — `random({ source })` swaps the CSPRNG while keeping
+//    the WIT shapes and the no-short-reads rule.
+//
+// `wasi(options)` returns one flat imports-record fragment, keyed by
+// compatibility-**track** keys per contracts/embedder-api.md §"Version
+// canonicalization" (`@0.2`, `@0.3`) — this package is the flagship
+// track-key-registration consumer: one `@0.2` provider serves every p2
+// leaf regardless of whether the guest's binary says `0.2.6`, `0.2.9` or
+// `0.2.12` (C0 finding D-2), and one `@0.3` union provider serves both
+// divergent `monotonic-clock@0.3.0` drafts the corpus actually links
+// (C0 finding D-1).
+import { cli } from "./cli.js";
+import { clocks } from "./clocks.js";
+import { filesystem } from "./filesystem.js";
+import { io } from "./io.js";
+import { random } from "./random.js";
+export { ExitError } from "./internal/cli_shared.js";
+/**
+ * Build the merged `wasi:*` imports fragment for `instantiate`.
+ *
+ * Usage: `instantiate(artifacts, { ...wasi(), ...moreImports })`.
+ */
+export function wasi(options = {}) {
+    const c = cli(options.cli);
+    const merged = {
+        ...c.imports,
+        ...io().imports,
+        ...clocks(options.clocks).imports,
+        ...random(options.random).imports,
+        ...filesystem().imports,
+    };
+    return Object.assign(merged, { captured: c.captured });
+}

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/esm/random.js

@@ -0,0 +1,96 @@
+// `wasi:random@0.2` + `wasi:random@0.3` — random, insecure, insecure-seed
+// (contracts/embedder-api.md §"WASI examination"; 0.2 leaves confirmed
+// against `engine-go/main.wasm`'s import surface: `get-random-bytes`; 0.3
+// shapes from the WASI 0.3.1 release — same three interfaces, same
+// function names, `len` renamed `max-len` with short reads permitted; see
+// the divergence note on `GET_RANDOM_VALUES_MAX`). One impl serves both
+// tracks: chunk-to-full is conforming on each.
+/**
+ * `crypto.getRandomValues` rejects requests over 65536 bytes
+ * (QuotaExceededError), while the 0.2 WIT this fragment serves requires
+ * exactly `len` bytes back ("Return `len` cryptographically-secure random
+ * or pseudo-random bytes", random.wit @0.2.x) — no shorter-return
+ * latitude, and callers (Rust `getrandom`, the Go runtime) fill fixed-size
+ * buffers trusting the length. So: chunk the fill, never clamp it.
+ *
+ * TRACK DIVERGENCE, for a future @0.3 fragment: `wasi:random@0.3.0`
+ * renames the parameter to `max-len` and PERMITS short reads
+ * ("Implementations MAY return fewer bytes than requested"; callers must
+ * loop; ≥1 byte required for max-len > 0). Authority moved with the WASI
+ * consolidation: `WebAssembly/WASI proposals/random/wit/random.wit` — the
+ * archived wasi-random repo's 0.3 rc still shows the old exact-len text.
+ * Chunk-to-full remains conforming there too ("up to max-len" includes
+ * exactly max-len) and makes conforming callers' mandatory loops terminate
+ * in one pass, so this helper serves both tracks unchanged.
+ *
+ * Either way the fill stays synchronous, satisfying both tracks' "must not
+ * block ... including on requests for [large] numbers of bytes".
+ */
+const GET_RANDOM_VALUES_MAX = 65536;
+function cryptoBytes(len) {
+    const out = new Uint8Array(Number(len));
+    for (let i = 0; i < out.length; i += GET_RANDOM_VALUES_MAX) {
+        crypto.getRandomValues(out.subarray(i, Math.min(i + GET_RANDOM_VALUES_MAX, out.length)));
+    }
+    return out;
+}
+/** The fill, honoring a virtualized `source` and its exact-length contract. */
+function makeRandomBytes(source) {
+    if (source === undefined)
+        return cryptoBytes;
+    return (len) => {
+        const out = source(Number(len));
+        if (out.length !== Number(len)) {
+            throw new TypeError(`random source returned ${out.length} bytes, need exactly ${len} ` +
+                `(the @0.2 WIT permits no short reads)`);
+        }
+        return out;
+    };
+}
+function makeRandomU64(bytes) {
+    return () => {
+        const out = bytes(8n);
+        return new DataView(out.buffer, out.byteOffset, 8).getBigUint64(0, true);
+    };
+}
+/**
+ * A fixed default: `wasi:random/insecure-seed` is explicitly documented (WIT
+ * doc comment, io.wit deps) as allowed to be entirely deterministic — it
+ * exists to seed hash-map DoS resistance, not for cryptographic use. This
+ * shim defaults to a fixed, obviously-synthetic pair (documented here as
+ * exactly that) so runs are reproducible; pass `insecureSeed` to override.
+ */
+const DEFAULT_INSECURE_SEED = [0n, 1n];
+/** `wasi:random@0.2` + `@0.3` provider fragment (two track keys). */
+export function random(options = {}) {
+    const seed = options.insecureSeed ?? DEFAULT_INSECURE_SEED;
+    const randomBytes = makeRandomBytes(options.source);
+    const randomU64 = makeRandomU64(randomBytes);
+    const randomIface = {
+        getRandomBytes: randomBytes,
+        getRandomU64: randomU64,
+    };
+    // "insecure" only means "not required to be a CSPRNG" — it is still
+    // wired to the real CSPRNG here for simplicity; only `insecure-seed`
+    // is deliberately, documentedly predictable.
+    const insecureIface = {
+        getInsecureRandomBytes: randomBytes,
+        getInsecureRandomU64: randomU64,
+    };
+    const insecureSeedIface = {
+        insecureSeed: () => seed,
+    };
+    return {
+        imports: {
+            "wasi:random/random@0.2": randomIface,
+            "wasi:random/insecure@0.2": insecureIface,
+            "wasi:random/insecure-seed@0.2": insecureSeedIface,
+            // The @0.3 track: identical function names; `max-len` PERMITS short
+            // reads but chunk-to-full returns exactly max-len, which "up to
+            // max-len" includes (module header) — one impl, both tracks.
+            "wasi:random/random@0.3": randomIface,
+            "wasi:random/insecure@0.3": insecureIface,
+            "wasi:random/insecure-seed@0.3": insecureSeedIface,
+        },
+    };
+}

package/esm/sockets.js

@@ -0,0 +1,172 @@
+// `wasi:sockets` — grants this process's NETWORK REACH to the guest,
+// unscoped: there is no allowlist, address check, or TCP/UDP toggle, so
+// a guest can reach anything this process can, loopback and instance
+// metadata endpoints included (docs/security.md). Never rides the
+// default `wasi()` merge.
+//
+// BOTH tracks: `types@0.3` + `ip-name-lookup@0.3` (UDP
+// and TCP, client + listener; internal/sockets_03.ts) and the poll-shaped
+// `@0.2` surface (internal/sockets_02.ts). THIS module is the public
+// face: the `sockets()` fragment factory and the vocabulary re-exports.
+// One backend serves both tracks: the
+// node builtins (`node:dgram` / `node:net`), which
+// real Node provides natively, Deno serves as STABLE node-compat (no
+// `--unstable-net` needed — that flag gates only the native API's shape,
+// not the capability), and Bun reaches through its compat (findings-only;
+// JSC lacks multi-memory, so polyengine guests cannot run there regardless).
+// Backend rationale, adapters, and measured costs: internal/sockets_platform.ts.
+//
+// À la carte (issue #4): this module is a separate export
+// (`@polyengine/wasi/sockets`), never merged into `wasi()` — the
+// baseline package stays host-agnostic web-platform code, while this
+// fragment is server-JS-native by nature (browsers have no sockets;
+// wasmtime owns the native story). Consumers that want it spread it in:
+//
+//   instantiate(artifacts, { ...wasi(), ...sockets().imports })
+//
+// The UDP provider is adopted from polymorph-components/polymorph-iroh#69
+// (that host's exam drives it over loopback QUIC); divergences from the
+// adopted code are the track key (`@0.3`, per this package's conventions —
+// one provider serves every 0.3.x), the fragment-scoped `onCall` hook
+// replacing a module-global call log (a published provider must not grow a
+// string per datagram by default), and `globalThis`-based feature detection
+// (the module evaluates and answers honestly on any host). The TCP client
+// surface is what the wosh listener bridges through (its
+// `listener-core/src/tcp.rs` — issue #4's prospective consumer) and the
+// smoke-c0 leg-4 composed-websocket shopping list names.
+//
+// The implemented resource shapes (0.3.x WIT — the full 0.3.1 release
+// surface, minus the recorded not-supported options below):
+//
+//   resource udp-socket {
+//     create/bind/connect/disconnect/send/receive,
+//     get-local-address/get-remote-address/get-address-family,
+//     get+set unicast-hop-limit, get+set receive/send-buffer-size
+//   }
+//   resource tcp-socket {
+//     create/bind/connect/listen/send/receive,
+//     get-local-address/get-remote-address/get-address-family/get-is-listening,
+//     set-listen-backlog-size, get+set keep-alive-enabled,
+//     get+set keep-alive-idle-time
+//   }
+//   ip-name-lookup { resolve-addresses }  (system resolver via node:dns)
+//
+// OPTIONS HONESTY (the node option surface is narrow; nothing is
+// emulated silently):
+//
+//   * udp connect/disconnect are OS-level (node dgram connect: kernel
+//     filtering and default destination), not adapter filtering.
+//   * udp unicast-hop-limit: setter is real (dgram setTTL); the getter
+//     reports the cached value (default 64, documented) — node has no
+//     getter. Buffer sizes are real both ways once bound (SO_RCVBUF/
+//     SO_SNDBUF); before bind, gets report the cached request or fail
+//     `not-supported`.
+//   * tcp keep-alive: enabled + idle-time are real (node setKeepAlive);
+//     gets report cached values (idle default 7200 s, documented).
+//     keep-alive-interval/count, tcp hop-limit, and tcp buffer sizes
+//     have NO node:net API and fail `not-supported`.
+//   * set-listen-backlog-size: applied as listen()'s backlog hint;
+//     changing it while listening is `not-supported` (node cannot
+//     re-listen; wasmtime re-listens).
+//   * accepted sockets do NOT inherit the listener's options (wasmtime
+//     inherits; recorded divergence).
+//
+// Anything else a future guest links fails loudly with a trap naming the
+// missing method rather than riding an untested emulation.
+//
+// The behavioral yardstick is wasmtime-wasi's p3 provider (the consumers'
+// wasmtime hosts serve the same guests through it).
+//
+// UDP: the same 64 KiB datagram ceiling, the same state machine (`bind`
+// once from unbound; `receive` and `get-local-address` demand a bound
+// socket; `send` to a remote implicitly binds an unbound socket to a
+// wildcard address; an omitted `send` remote requires connected mode, and
+// an explicit remote on a connected socket is `invalid-argument`), and the same address-family validation (an
+// IPv4-mapped or deprecated IPv4-compatible IPv6 address never crosses a
+// family boundary). Recorded divergences, rooted in the platform exposing
+// no socket options:
+//
+//   * scope-id: a non-zero IPv6 `scope-id` fails `not-supported` (node
+//     hostnames cannot carry a zone; wasmtime binds it).
+//   * v6-only: wasmtime sets IPV6_V6ONLY on IPv6 sockets; node leaves the
+//     OS default, so an `::` wildcard bind on Linux is dual-stack and may
+//     receive IPv4 traffic, surfaced as IPv4-mapped sender addresses —
+//     which is also why the address codec parses the `::ffff:a.b.c.d`
+//     spelling.
+//   * unread datagrams queue in the adapter (node's receive path is
+//     push-shaped) and tail-drop past a bound — the kernel-buffer
+//     analogue; see sockets_platform.ts `MAX_QUEUED_DATAGRAMS`.
+//
+// TCP (the TcpSocketOperationalSemantics-0.3.0 state machine): `connect`
+// once from `unbound` (a failed attempt closes the socket); `listen` once
+// from `unbound` (implicit wildcard-ephemeral bind) or `bound`;
+// `send`/`receive` once each, only when `connected`, and their failures
+// NEVER throw — `send`'s error channel is its returned future (amendment
+// A12: the async method's promise IS the future source) and `receive`'s
+// is the future half of its tuple, resolved as result values. `listen`
+// returns the perpetual accept stream, whose elements are connected
+// `tcp-socket` resources (amendment A13: un-taken elements are destroyed
+// at teardown, closing their connections); per-connection accept failures
+// are skipped, listener-fatal ones end the stream. Stream teardown
+// follows the WIT's shared-ownership note: the OS socket closes only when
+// the resource handle AND every derived stream (pumps, accept stream) are
+// done, so they all remain functional after the guest drops the
+// `tcp-socket` handle. The receive stream ends (cleanly, no fake data) on
+// BOTH graceful FIN and abnormal close; the two are distinguished by the
+// future (`ok` vs `err`), exactly as the WIT documents. Guest-side
+// failures while consuming `send`'s stream (a peer trap) are NOT socket
+// errors: they propagate as producer failures on the host-failure channel.
+//
+// `listen` is SUSPENDING (embedder-api A1/A2 — the wasi:io `block`
+// kernel): node defers the OS bind one event-loop turn, so `listen` parks
+// the calling guest frame for that tick and returns fully settled — real
+// ephemeral addresses from `get-local-address`, real error codes
+// (`address-in-use`) from a failed bind. Guests that link `listen`
+// auto-select jspi mode on JSPI engines (V8: Deno, Node, Chromium);
+// client-shaped guests are untouched.
+//
+// Recorded TCP divergences:
+//
+//   * `bind` records the address; the OS bind is DEFERRED to `listen` or
+//     `connect` (node cannot bind an unconnected socket), so bind errors
+//     (`address-in-use`, `address-not-bindable`) surface at those calls —
+//     with their real codes — not at `bind`.
+//
+// When the node builtins are absent (`process.getBuiltinModule` missing —
+// a browser), `create` fails `error-code.not-supported` — the honest
+// capability answer. On Deno the providers need `--allow-net`; a denied
+// permission arrives as `Deno.errors.NotCapable` through the compat layer
+// and maps to `access-denied`.
+import { sockets02 } from "./internal/sockets_02.js";
+import { sockets03 } from "./internal/sockets_03.js";
+// The public vocabulary (types, address codec, validators, the platform
+// error mapper) lives in internal/sockets_shared.ts; THIS module is its
+// public home. The tracks live in internal/sockets_03.ts and
+// internal/sockets_02.ts and share one node-builtins backend
+// (internal/sockets_platform.ts).
+export { ipHostname, isUnspecified, isValidAddressFamily, mapPlatformError, MAX_UDP_DATAGRAM_SIZE, parseNetAddr, sameSocketAddress, wildcardAddress, } from "./internal/sockets_shared.js";
+// The 0.2 track's public pieces: the enum error vocabulary, the io-error
+// resource `network-error-code` downcasts, and the opaque network.
+export { Network, SocketIoError, } from "./internal/sockets_02.js";
+export const SOCKETS_TYPES_INTERFACE = "wasi:sockets/types@0.3";
+/**
+ * The `wasi:sockets` provider fragment, BOTH tracks (module header):
+ * `types@0.3` + `ip-name-lookup@0.3` (internal/sockets_03.ts) and the
+ * seven poll-shaped `@0.2` interfaces (internal/sockets_02.ts). Track
+ * keys — one provider serves every 0.2.x / 0.3.x the resolver folds onto
+ * its track. Resource classes are built per fragment so the `onCall`
+ * observer is scoped to it.
+ */
+export function sockets(options = {}) {
+    const onCall = options.onCall ?? (() => { });
+    const track03 = sockets03(onCall);
+    return {
+        imports: {
+            ...track03.imports,
+            ...sockets02(onCall).imports,
+        },
+        UdpSocket: track03.UdpSocket,
+        TcpSocket: track03.TcpSocket,
+        resolveAddresses: track03.resolveAddresses,
+    };
+}

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@polyengine/wasi",
+  "version": "0.1.0-pre.g633468a",
+  "description": "WASI providers for polyengine hosts: the p2 baseline and p3 clocks, one module per semver track.",
+  "homepage": "https://github.com/polymorph-components/polyengine#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/polymorph-components/polyengine.git"
+  },
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/polymorph-components/polyengine/issues"
+  },
+  "module": "./esm/mod.js",
+  "types": "./types/mod.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./types/mod.d.ts",
+        "default": "./esm/mod.js"
+      }
+    },
+    "./cli": {
+      "import": {
+        "types": "./types/cli.d.ts",
+        "default": "./esm/cli.js"
+      }
+    },
+    "./cli-stdio": {
+      "import": {
+        "types": "./types/cli_stdio.d.ts",
+        "default": "./esm/cli_stdio.js"
+      }
+    },
+    "./clocks": {
+      "import": {
+        "types": "./types/clocks.d.ts",
+        "default": "./esm/clocks.js"
+      }
+    },
+    "./filesystem": {
+      "import": {
+        "types": "./types/filesystem.d.ts",
+        "default": "./esm/filesystem.js"
+      }
+    },
+    "./filesystem-node": {
+      "import": {
+        "types": "./types/filesystem_node.d.ts",
+        "default": "./esm/filesystem_node.js"
+      }
+    },
+    "./filesystem-web": {
+      "import": {
+        "types": "./types/filesystem_web.d.ts",
+        "default": "./esm/filesystem_web.js"
+      }
+    },
+    "./http": {
+      "import": {
+        "types": "./types/http.d.ts",
+        "default": "./esm/http.js"
+      }
+    },
+    "./io": {
+      "import": {
+        "types": "./types/io.d.ts",
+        "default": "./esm/io.js"
+      }
+    },
+    "./random": {
+      "import": {
+        "types": "./types/random.d.ts",
+        "default": "./esm/random.js"
+      }
+    },
+    "./sockets": {
+      "import": {
+        "types": "./types/sockets.d.ts",
+        "default": "./esm/sockets.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {},
+  "type": "module",
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@polyengine/protocol": "0.1.0-pre.g633468a",
+    "@polyengine/runtime": "0.1.0-pre.g633468a"
+  },
+  "_generatedBy": "dnt@0.43.2"
+}

package/types/cli.d.ts

@@ -0,0 +1,44 @@
+export { type CliByteSource, type CliErrorCode, type CliIoResult, ExitError, TerminalInput, TerminalOutput, } from "./internal/cli_shared.js";
+export interface CliOptions {
+    /** `get-arguments`; default `[]`. */
+    args?: string[];
+    /** `get-environment`; default `{}`. */
+    env?: Record<string, string>;
+    /** `initial-cwd`; default `undefined` (none). */
+    cwd?: string;
+    /** `get-stdin`'s buffer contents; default empty (matches contract: "stdin (empty)"). */
+    stdinBuffer?: Uint8Array;
+    /** Also `console.log`/`console.error` captured stdout/stderr writes. Default false. */
+    passthrough?: boolean;
+    /** `exit()` throws `ExitError` instead of merely recording. Default false. */
+    throwOnExit?: boolean;
+}
+/** Captured host-observable state exposed on the returned handle (contract wording). */
+export interface CliCaptured {
+    stdout(): Uint8Array;
+    stderr(): Uint8Array;
+    stdoutText(): string;
+    stderrText(): string;
+    /** Whether `wasi:cli/exit#exit` has been called. */
+    exited(): boolean;
+    /** The `result` kind of the last `exit()` call's `status`, or `undefined` if never called. */
+    exitOk(): boolean | undefined;
+    /** The last `exit-with-code` status (0.3), or `undefined` if never called. */
+    exitCode(): number | undefined;
+}
+export interface CliResult {
+    imports: Record<string, unknown>;
+    captured: CliCaptured;
+}
+/**
+ * `wasi:cli@0.2` provider fragment (track key).
+ *
+ * `exit`'s WIT signature is `exit: func(status: result)` — `result` with no
+ * type parameters, i.e. `result<_, _>`. Per contracts/embedder-api.md's value
+ * table, a `result` in **parameter** (non-return) position is plain nested
+ * data: `{ kind: "ok" } | { kind: "err" }` (the A10 family — this comment
+ * and the impl carried the pre-A10 `tag` spelling until 2026-08-14, a
+ * latent bug the direct-call unit tests masked), never a throw. Only a
+ * function's own *return*-position result throws/rejects.
+ */
+export declare function cli(options?: CliOptions): CliResult;

package/types/cli_stdio.d.ts

@@ -0,0 +1,31 @@
+import { type ByteSink } from "./io.js";
+export { type ByteSink } from "./io.js";
+export interface CliStdioOptions {
+    /** stdin bytes; default: the host process's stdin. */
+    stdin?: AsyncIterable<Uint8Array>;
+    /** stdout sink; default: the host process's stdout. */
+    stdout?: ByteSink;
+    /** stderr sink; default: the host process's stderr. */
+    stderr?: ByteSink;
+    /** Terminal-ness per stream; default: the real streams' `isTTY`. */
+    isTty?: {
+        stdin?: boolean;
+        stdout?: boolean;
+        stderr?: boolean;
+    };
+    /** `get-arguments`; default: the host process's argv (script-relative). */
+    args?: string[];
+    /** `get-environment`; default: the host process's env. */
+    env?: Record<string, string>;
+    /** `initial-cwd`/`get-initial-cwd`; default: the host process's cwd. */
+    cwd?: string;
+    /** `exit` terminates the host process instead of throwing `ExitError`. */
+    exitProcess?: boolean;
+}
+export interface CliStdio {
+    imports: Record<string, unknown>;
+}
+/**
+ * `wasi:cli` over the host process's stdio (both tracks — module header).
+ */
+export declare function cliStdio(options?: CliStdioOptions): CliStdio;

package/types/clocks.d.ts

@@ -0,0 +1,8 @@
+export interface ClocksOptions {
+    /** Override the monotonic clock's `now()` (nanoseconds); default `performance.now()`-derived. */
+    now?: () => bigint;
+}
+/** `wasi:clocks@0.2` + `wasi:clocks@0.3` provider fragment (two track keys). */
+export declare function clocks(options?: ClocksOptions): {
+    imports: Record<string, unknown>;
+};

package/types/filesystem.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `wasi:filesystem/types.descriptor` — constructible-never.
+ *
+ * `preopens#get-directories` always returns `[]` (below), so no `descriptor`
+ * instance can ever reach a guest through this shim; the class exists only
+ * so the resource *type* is a legal, structurally-typeable import target.
+ * Every method throws if somehow reached — loud, not a silent wrong answer —
+ * because reaching one would mean a caller found a descriptor this shim never
+ * handed out.
+ */
+export declare class Descriptor {
+    #private;
+    constructor();
+    getFlags(): never;
+    getType(): never;
+    stat(): never;
+    statAt(): never;
+    openAt(): never;
+    readViaStream(): never;
+    writeViaStream(): never;
+    appendViaStream(): never;
+    metadataHashAt(): never;
+}
+/** `wasi:filesystem/types.directory-entry-stream` — same rationale as `Descriptor`. */
+export declare class DirectoryEntryStream {
+}
+/** `wasi:filesystem@0.2` provider fragment (track key). */
+export declare function filesystem(): {
+    imports: Record<string, unknown>;
+};

package/types/filesystem_node.d.ts

@@ -0,0 +1,16 @@
+import { type FilesystemAccessOptions, type FilesystemFragment, type MaybeAsync } from "./internal/fs_provider.js";
+export interface FilesystemNodeOptions extends FilesystemAccessOptions {
+    /**
+     * Guest name → host directory path. Each entry becomes a preopen
+     * (`preopens#get-directories`). No default: filesystem access is an
+     * explicit grant. Host paths are resolved (realpath) at construction
+     * and must name directories. Read-only unless `writable` is set.
+     */
+    preopens: Record<string, string>;
+}
+/**
+ * `wasi:filesystem` over node's `node:fs` builtin (module header).
+ * Serves both the `@0.2` and `@0.3` tracks.
+ */
+export declare function filesystemNode(options: FilesystemNodeOptions): FilesystemFragment;
+export type { FilesystemFragment, MaybeAsync };

package/types/filesystem_web.d.ts

@@ -0,0 +1,61 @@
+import { type FilesystemAccessOptions, type FilesystemFragment } from "./internal/fs_provider.js";
+export interface OpfsFileLike {
+    readonly size: number;
+    readonly lastModified: number;
+    slice(start: number, end: number): {
+        arrayBuffer(): Promise<ArrayBuffer>;
+    };
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+export interface OpfsWritable {
+    write(params: {
+        type: "write";
+        position: number;
+        data: Uint8Array;
+    }): Promise<void>;
+    truncate(size: number): Promise<void>;
+    close(): Promise<void>;
+}
+export interface OpfsFileHandle {
+    readonly kind: "file";
+    readonly name: string;
+    getFile(): Promise<OpfsFileLike>;
+    createWritable(opts?: {
+        keepExistingData?: boolean;
+    }): Promise<OpfsWritable>;
+    isSameEntry(other: OpfsFileHandle | OpfsDirectoryHandle): Promise<boolean>;
+    /** Chromium's FileSystemHandle.move; absent on Firefox/Safari. */
+    move?(parent: OpfsDirectoryHandle, name: string): Promise<void>;
+}
+export interface OpfsDirectoryHandle {
+    readonly kind: "directory";
+    readonly name: string;
+    getDirectoryHandle(name: string, opts?: {
+        create?: boolean;
+    }): Promise<OpfsDirectoryHandle>;
+    getFileHandle(name: string, opts?: {
+        create?: boolean;
+    }): Promise<OpfsFileHandle>;
+    removeEntry(name: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    entries(): AsyncIterable<[string, OpfsDirectoryHandle | OpfsFileHandle]>;
+    isSameEntry(other: OpfsFileHandle | OpfsDirectoryHandle): Promise<boolean>;
+    move?(parent: OpfsDirectoryHandle, name: string): Promise<void>;
+}
+export interface FilesystemWebOptions extends FilesystemAccessOptions {
+    /**
+     * Guest name → OPFS directory handle. Each entry becomes a preopen.
+     * No default: filesystem access is an explicit grant — pass
+     * `await navigator.storage.getDirectory()` (or any structural
+     * equivalent, e.g. an in-memory fake) yourself. Read-only unless
+     * `writable` is set.
+     */
+    preopens: Record<string, OpfsDirectoryHandle>;
+}
+/**
+ * `wasi:filesystem` over the Origin Private File System (module header).
+ * Serves both the `@0.2` (parking, JSPI) and `@0.3` tracks.
+ */
+export declare function filesystemWeb(options: FilesystemWebOptions): FilesystemFragment;
+export type { FilesystemFragment };