@polyengine/wasi 0.1.0-pre.g633468a

package/types/internal/sockets_shared.d.ts

@@ -0,0 +1,256 @@
+import { ComponentException, Stream } from "@polyengine/runtime/embedder";
+import type { NetAddr } from "./sockets_platform.js";
+export type { NetAddr };
+/** `wasi:sockets/types@0.3`'s `ip-address-family` enum. */
+export type IpAddressFamily = "ipv4" | "ipv6";
+/** `ipv4-address` = `tuple<u8, u8, u8, u8>`. */
+export type Ipv4Address = [number, number, number, number];
+/** `ipv6-address` = `tuple<u16 × 8>`. */
+export type Ipv6Address = [
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number
+];
+export interface Ipv4SocketAddress {
+    port: number;
+    address: Ipv4Address;
+}
+export interface Ipv6SocketAddress {
+    port: number;
+    flowInfo: number;
+    address: Ipv6Address;
+    scopeId: number;
+}
+/** The `ip-socket-address` variant, in `{ kind, value }` form (A10). */
+export type IpSocketAddress = {
+    kind: "ipv4";
+    value: Ipv4SocketAddress;
+} | {
+    kind: "ipv6";
+    value: Ipv6SocketAddress;
+};
+/** The address-only `ip-address` variant (ip-name-lookup's vocabulary). */
+export type IpAddress = {
+    kind: "ipv4";
+    value: Ipv4Address;
+} | {
+    kind: "ipv6";
+    value: Ipv6Address;
+};
+/** `wasi:sockets/ip-name-lookup@0.3`'s own `error-code` variant. */
+export type NameLookupErrorCode = {
+    kind: "access-denied";
+} | {
+    kind: "invalid-argument";
+} | {
+    kind: "name-unresolvable";
+} | {
+    kind: "temporary-resolver-failure";
+} | {
+    kind: "permanent-resolver-failure";
+} | {
+    kind: "other";
+    value?: string;
+};
+/**
+ * The `error-code` variant. Every case is listed so callers can switch
+ * exhaustively against the real WIT vocabulary.
+ */
+export type SocketErrorCode = {
+    kind: "access-denied";
+} | {
+    kind: "not-supported";
+} | {
+    kind: "invalid-argument";
+} | {
+    kind: "out-of-memory";
+} | {
+    kind: "timeout";
+} | {
+    kind: "invalid-state";
+} | {
+    kind: "address-not-bindable";
+} | {
+    kind: "address-in-use";
+} | {
+    kind: "remote-unreachable";
+} | {
+    kind: "connection-refused";
+} | {
+    kind: "connection-broken";
+} | {
+    kind: "connection-reset";
+} | {
+    kind: "connection-aborted";
+} | {
+    kind: "datagram-too-large";
+} | {
+    kind: "other";
+    value?: string;
+};
+/**
+ * The datagram payload ceiling, matching wasmtime-wasi's
+ * `MAX_UDP_DATAGRAM_SIZE` (`u16::MAX`). Larger sends fail
+ * `datagram-too-large` before reaching the OS; receives use a buffer of
+ * this size so no datagram the OS delivers is ever truncated.
+ */
+export declare const MAX_UDP_DATAGRAM_SIZE = 65535;
+/**
+ * A WIT `err` the branded way (contracts/embedder-api.md, "Error model"):
+ * an unbranded throw would become a trap naming the import instead of a
+ * guest-visible err.
+ */
+export declare function componentError(payload: SocketErrorCode, detail: string): ComponentException<SocketErrorCode>;
+/** Render the address part of `addr` as a Deno hostname string. */
+export declare function ipHostname(addr: IpSocketAddress): string;
+/**
+ * Parse a Deno `NetAddr` back into a WIT `ip-socket-address`.
+ *
+ * Handles the compressed (`::1`), full, IPv4-embedded (`::ffff:127.0.0.1` —
+ * what a dual-stack socket reports for IPv4 senders), and zoned
+ * (`fe80::1%3`) hostname spellings. A zone parses as the numeric scope-id
+ * when it is numeric and drops to 0 otherwise (interface names are not
+ * representable in the WIT shape); flow-info is not observable and is
+ * always 0.
+ */
+export declare function parseNetAddr(addr: NetAddr): IpSocketAddress;
+/**
+ * Whether `addr` may cross this socket's family boundary: same family, and
+ * never an IPv4-mapped or deprecated IPv4-compatible IPv6 address.
+ */
+export declare function isValidAddressFamily(family: IpAddressFamily, addr: IpSocketAddress): boolean;
+export declare function isUnspecified(addr: IpSocketAddress): boolean;
+/** Same endpoint: family, address, and port (udp connected-mode filter). */
+export declare function sameSocketAddress(a: IpSocketAddress, b: IpSocketAddress): boolean;
+/** `e instanceof Deno.errors[name]`, tolerating hosts/versions lacking the class. */
+export declare function isDenoError(e: unknown, name: string): boolean;
+/**
+ * Map a platform failure onto the WIT `error-code` vocabulary, mirroring
+ * wasmtime-wasi's io-error table where the platform exposes the
+ * distinction — Deno's error classes first, then Node-style `code`
+ * strings, then the plain-`Error` spellings Deno leaves unclassified. An
+ * already-branded error passes through unchanged — the codec and the
+ * capability re-detection throw branded errors from inside the same try
+ * blocks that guard the platform calls, and re-wrapping one would demote
+ * its payload to `other`.
+ */
+export declare function mapPlatformError(e: unknown, what: string): ComponentException<SocketErrorCode>;
+/** `result<_, error-code>` as a value (the payload of tcp send/receive futures). */
+export type SocketResult = {
+    kind: "ok";
+} | {
+    kind: "err";
+    value: SocketErrorCode;
+};
+export declare const RESULT_OK: SocketResult;
+export declare const RESULT_INVALID_STATE: SocketResult;
+/** The err side of a `SocketResult`, mapped from a platform failure. */
+export declare function resultErrOf(e: unknown, what: string): SocketResult;
+export interface SocketsOptions {
+    /**
+     * Observe every `wasi:sockets` entry point the guest reaches, in call
+     * order (`"udp-socket.create"`, `"tcp-socket.connect"`, …). For host-side
+     * test assertions — a relay-only scenario can assert zero calls, an exam
+     * can read back the guest's exact driving sequence. No default cost: when
+     * absent, nothing is recorded.
+     */
+    onCall?: (call: string) => void;
+}
+/**
+ * The host-implemented `udp-socket` resource surface: a plain class with
+ * camelCase methods and the WIT `static` as a JS static
+ * (contracts/embedder-api.md, "Resources"). The runtime calls
+ * `[Symbol.dispose]` when the guest drops its last handle; that closes the
+ * OS socket, settling any still-pending `receive` as a branded err.
+ */
+export interface UdpSocket {
+    bind(localAddress: IpSocketAddress): void;
+    connect(remoteAddress: IpSocketAddress): Promise<void>;
+    disconnect(): void;
+    send(data: Uint8Array, remoteAddress: IpSocketAddress | undefined): Promise<void>;
+    receive(): Promise<[Uint8Array, IpSocketAddress]>;
+    getLocalAddress(): IpSocketAddress;
+    getRemoteAddress(): IpSocketAddress;
+    getAddressFamily(): IpAddressFamily;
+    getUnicastHopLimit(): number;
+    setUnicastHopLimit(value: number): void;
+    getReceiveBufferSize(): bigint;
+    setReceiveBufferSize(value: bigint): void;
+    getSendBufferSize(): bigint;
+    setSendBufferSize(value: bigint): void;
+    [Symbol.dispose](): void;
+}
+/** The `udp-socket` resource class a fragment carries. */
+export interface UdpSocketClass {
+    create(addressFamily: IpAddressFamily): UdpSocket;
+}
+/**
+ * What tcp `send` accepts: the lifted `Stream<u8>` handle the runtime
+ * dispatches (its async iterator yields `Uint8Array` chunks), or any
+ * natural byte-chunk producer for direct/test use.
+ */
+export type TcpSendSource = Stream<number> | AsyncIterable<Uint8Array | number[]> | Iterable<Uint8Array | number[]>;
+/** What tcp `receive` returns in stream position: chunks of bytes. */
+export type TcpByteStream = AsyncIterable<Uint8Array> | Iterable<Uint8Array>;
+/**
+ * What tcp `listen` returns: the perpetual accept stream. `cancel` is the
+ * A13 producer-cancellation hook the runtime's pump invokes when the
+ * guest drops the stream while the loop is parked in accept(); direct
+ * (non-runtime) consumers may call it themselves to stop accepting.
+ */
+export type TcpAcceptStream = AsyncIterable<TcpSocket> & {
+    cancel(): void;
+};
+/**
+ * The host-implemented `tcp-socket` resource surface (client + listener
+ * halves — module header). `send` is a WIT sync func returning
+ * `future<result>`: the async method's promise is lowered as the future
+ * source (amendment A12), so the guest's call returns immediately and the
+ * future settles when transmission completes. `receive`'s tuple carries
+ * the byte stream and the future that reports FIN (`ok`) vs abnormal
+ * close (`err`). `listen` returns the perpetual accept stream — an
+ * async iterable of connected `TcpSocket` resources, lowered as
+ * `stream<own<tcp-socket>>` (amendment A13: elements the guest never
+ * takes are destroyed, closing their connections). Dropping the guest
+ * handle does NOT close a socket with live pumps or a live accept stream
+ * (the WIT's shared-ownership note); the OS socket closes when the
+ * handle and every derived stream are all retired.
+ */
+export interface TcpSocket {
+    bind(localAddress: IpSocketAddress): void;
+    connect(remoteAddress: IpSocketAddress): Promise<void>;
+    listen(): Promise<TcpAcceptStream>;
+    send(data: TcpSendSource): Promise<SocketResult>;
+    receive(): [TcpByteStream, Promise<SocketResult>];
+    getLocalAddress(): IpSocketAddress;
+    getRemoteAddress(): IpSocketAddress;
+    getAddressFamily(): IpAddressFamily;
+    getIsListening(): boolean;
+    setListenBacklogSize(value: bigint): void;
+    getKeepAliveEnabled(): boolean;
+    setKeepAliveEnabled(value: boolean): void;
+    getKeepAliveIdleTime(): bigint;
+    setKeepAliveIdleTime(value: bigint): void;
+    getKeepAliveInterval(): bigint;
+    setKeepAliveInterval(value: bigint): void;
+    getKeepAliveCount(): number;
+    setKeepAliveCount(value: number): void;
+    getHopLimit(): number;
+    setHopLimit(value: number): void;
+    getReceiveBufferSize(): bigint;
+    setReceiveBufferSize(value: bigint): void;
+    getSendBufferSize(): bigint;
+    setSendBufferSize(value: bigint): void;
+    [Symbol.dispose](): void;
+}
+/** The `tcp-socket` resource class a fragment carries. */
+export interface TcpSocketClass {
+    create(addressFamily: IpAddressFamily): TcpSocket;
+}
+/** The family's wildcard address, port 0 (tcp listen's implicit bind). */
+export declare function wildcardAddress(family: IpAddressFamily): IpSocketAddress;

package/types/io.d.ts

@@ -0,0 +1,177 @@
+/** A p2 `stream-error` value (variant): `closed` or `last-operation-failed`. */
+export type StreamErrorValue = {
+    kind: "closed";
+} | {
+    kind: "last-operation-failed";
+    value: IoError;
+};
+/**
+ * `wasi:io/error.error` — the generic downcastable error resource
+ * (io.wit:23). This shim never produces one organically (streams fail with
+ * `closed` only, never `last-operation-failed`); the class exists so the
+ * resource *type* is a legal import target and so a future producer of one
+ * has somewhere to construct it.
+ */
+export declare class IoError {
+    #private;
+    constructor(message?: string);
+    toDebugString(): string;
+}
+/**
+ * A pollable over host-supplied readiness.
+ *
+ * WIT-facing surface: `ready()` and `block()` (the latter parks the
+ * calling wasm frame when unready — @suspending, embedder-api.md A2:
+ * the class prototype is the brand authority).
+ *
+ * Host-facing surface: the constructor and `waitPromise()`. `ready` must
+ * be cheap and side-effect-free; `wait` returns a promise that settles
+ * when readiness MAY have changed — block/poll re-check and re-wait in a
+ * loop, so spurious wakes are fine and `wait` is called repeatedly (return
+ * the CURRENT epoch's promise each call; the promise-swap pattern — settle
+ * and re-arm on every event — is the intended producer shape). The default
+ * (no arguments) is an always-ready pollable, the honest shape for
+ * type-only linkage and never-backpressured sinks.
+ */
+export declare class Pollable {
+    #private;
+    constructor(ready?: () => boolean, wait?: () => Promise<void>);
+    /**
+     * A pollable that becomes ready at `deadline` (nanoseconds on the
+     * caller's clock). One in-flight sleep is shared by concurrent waiters
+     * and RE-ARMED after every settle with the delta recomputed:
+     * `ready()` consults the clock, so an early-firing sleep (timer slop,
+     * or the engine's setTimeout ceiling below) hands the wait loop a
+     * fresh sleep for the remainder instead of a permanently-resolved
+     * promise — the cached-forever arm was a hot microtask livelock for
+     * any deadline past the ceiling (block/poll re-check `ready()` and
+     * re-await; awaiting an already-settled promise never yields to the
+     * timer that would make it ready).
+     *
+     * Engines clamp setTimeout delays above 2^31-1 ms to ~0 (node/Deno
+     * warn and use 1 ms), so far deadlines sleep in ceiling-sized chunks;
+     * each chunk end re-checks the clock and re-arms.
+     */
+    static timer(deadlineNs: bigint, nowNs: () => bigint): Pollable;
+    ready(): boolean;
+    /** Parks the calling wasm frame until ready (sync fast path when
+     * already ready — no suspension, per-declaration marking only adds the
+     * engine's continuation hop). */
+    block(): void | Promise<void>;
+    /** Host-facing (not part of the WIT resource surface): the current
+     * epoch's wake promise, raced by `poll`. */
+    waitPromise(): Promise<void>;
+}
+/**
+ * `wasi:io/poll.poll` — indices of the ready pollables, parking the
+ * calling frame until at least one is ready. Sync fast path: if anything
+ * is ready right now, the indices return without a suspension.
+ *
+ * The explicit annotation is JSR's no-slow-types rule (the `suspending`
+ * wrapper would otherwise leave this public symbol's type inferred).
+ */
+export declare const poll: (pollables: readonly Pollable[]) => number[] | Promise<number[]>;
+/**
+ * Buffer-backed input stream: serves `read`/`blocking-read` synchronously
+ * from an in-memory buffer supplied at construction (default empty,
+ * matching stdin's default in this package). Blocking degenerates to the
+ * sync read because the buffer is always immediately available.
+ */
+export declare class InputStream {
+    #private;
+    constructor(buf?: Uint8Array);
+    read(len: bigint): Uint8Array;
+    /** Park-capable (A14): the buffer-backed base never parks. */
+    blockingRead(len: bigint): Uint8Array | Promise<Uint8Array>;
+    skip(len: bigint): bigint;
+    /** Park-capable (A14): the buffer-backed base never parks. */
+    blockingSkip(len: bigint): bigint | Promise<bigint>;
+    subscribe(): Pollable;
+    [Symbol.dispose](): void;
+}
+/**
+ * Buffer-backed output stream over a byte sink. `checkWrite` always
+ * reports a large permit (the sink never truly backs up), so the
+ * synchronous fast path is always taken and `blocking-*` methods
+ * degenerate to their non-blocking counterparts.
+ */
+export declare class OutputStream {
+    #private;
+    constructor(sink: (chunk: Uint8Array) => void);
+    checkWrite(): bigint;
+    write(contents: Uint8Array): void;
+    /** Park-capable (A14): the never-backpressured base never parks. */
+    blockingWriteAndFlush(contents: Uint8Array): void | Promise<void>;
+    flush(): void;
+    /** Park-capable (A14): the never-backpressured base never parks. */
+    blockingFlush(): void | Promise<void>;
+    subscribe(): Pollable;
+    writeZeroes(len: bigint): void;
+    /** Park-capable (A14): the never-backpressured base never parks. */
+    blockingWriteZeroesAndFlush(len: bigint): void | Promise<void>;
+    splice(src: InputStream, len: bigint): bigint;
+    /** Park-capable (A14): the never-backpressured base never parks. */
+    blockingSplice(src: InputStream, len: bigint): bigint | Promise<bigint>;
+    [Symbol.dispose](): void;
+}
+/** Default high-water mark for the async-backed streams below: how many
+ * buffered bytes pause a `FedInputStream`'s feed, and the byte budget a
+ * `SinkOutputStream`'s `check-write` reports. */
+export declare const STREAM_HIGH_WATER = 65536;
+/** An async byte sink; the returned promise settling = the chunk drained. */
+export type ByteSink = (chunk: Uint8Array) => void | Promise<void>;
+/**
+ * The p2 `input-stream` surface over an asynchronously-fed buffer: the
+ * generic bridge from any `AsyncIterable<Uint8Array>` (host stdin, an
+ * OPFS file read) to p2 stream semantics. `read` on an empty open stream
+ * returns an empty list (p2's non-blocking contract), `blocking-read`
+ * parks until bytes or EOF (A14/A2 mark relay — duck-typed against the
+ * registered `InputStream`, the marks relay from that prototype), and
+ * EOF-with-drained-buffer is the `closed` stream-error. The feed pauses
+ * past the high-water mark (no unbounded buffering).
+ */
+export declare class FedInputStream {
+    #private;
+    constructor(source: AsyncIterable<Uint8Array>, highWater?: number);
+    read(len: bigint): Uint8Array;
+    /** Parks (A14/A2 mark relay from the registered prototype). */
+    blockingRead(len: bigint): Uint8Array | Promise<Uint8Array>;
+    skip(len: bigint): bigint;
+    blockingSkip(len: bigint): bigint | Promise<bigint>;
+    subscribe(): Pollable;
+    [Symbol.dispose](): void;
+}
+/**
+ * The p2 `output-stream` surface over an async sink, with a real byte
+ * budget: `check-write` reports the remaining permit (writing past it is
+ * the guest's contract violation and traps via unbranded throw),
+ * `blocking-flush`/`blocking-write-and-flush` park until the sink
+ * drained everything (A14/A2 mark relay), `subscribe` wakes when budget
+ * frees. A sink failure surfaces as the `last-operation-failed`
+ * stream-error carrying an `IoError`.
+ */
+export declare class SinkOutputStream {
+    #private;
+    constructor(sink: ByteSink, highWater?: number);
+    checkWrite(): bigint;
+    write(contents: Uint8Array): void;
+    flush(): void;
+    /** Parks until the sink drained everything (A14/A2 mark relay). */
+    blockingFlush(): void | Promise<void>;
+    /** Parks until this write (and everything before it) drained. */
+    blockingWriteAndFlush(contents: Uint8Array): void | Promise<void>;
+    subscribe(): Pollable;
+    writeZeroes(len: bigint): void;
+    blockingWriteZeroesAndFlush(len: bigint): void | Promise<void>;
+    splice(src: {
+        read(len: bigint): Uint8Array;
+    }, len: bigint): bigint;
+    blockingSplice(src: {
+        read(len: bigint): Uint8Array;
+    }, len: bigint): bigint | Promise<bigint>;
+    [Symbol.dispose](): void;
+}
+/** `wasi:io@0.2` provider fragment (track key). */
+export declare function io(): {
+    imports: Record<string, unknown>;
+};

package/types/mod.d.ts

@@ -0,0 +1,31 @@
+import { type CliCaptured, type CliOptions } from "./cli.js";
+import { type ClocksOptions } from "./clocks.js";
+import { type RandomOptions } from "./random.js";
+export { type CliCaptured, type CliOptions } from "./cli.js";
+export { ExitError } from "./internal/cli_shared.js";
+export { type ClocksOptions } from "./clocks.js";
+export { type RandomOptions } from "./random.js";
+export interface WasiOptions {
+    cli?: CliOptions;
+    clocks?: ClocksOptions;
+    random?: RandomOptions;
+}
+/**
+ * The merged imports record plus the one piece of host-observable state a
+ * caller needs back out (contract wording: "expose captured output on the
+ * returned handle"). `captured` is a plain extra property, not a WIT
+ * interface-id key, so it never participates in `ImportResolver`'s
+ * track/exact matching (`parseInterfaceId("captured")` has no `@`, and it is
+ * excluded from the unversioned-track bookkeeping because it contains
+ * neither `:` nor `/` — see `runtime/src/embedder/version.ts`
+ * `#register`).
+ */
+export interface WasiImports extends Record<string, unknown> {
+    readonly captured: CliCaptured;
+}
+/**
+ * Build the merged `wasi:*` imports fragment for `instantiate`.
+ *
+ * Usage: `instantiate(artifacts, { ...wasi(), ...moreImports })`.
+ */
+export declare function wasi(options?: WasiOptions): WasiImports;

package/types/random.d.ts

@@ -0,0 +1,17 @@
+export interface RandomOptions {
+    /** Override the deterministic default `insecure-seed` value. */
+    insecureSeed?: readonly [bigint, bigint];
+    /**
+     * Replace the CSPRNG (virtualization: tests selectively stubbing
+     * randomness while keeping the WIT shapes). Must return EXACTLY `len`
+     * bytes — the @0.2 contract's no-short-reads rule is enforced here, so
+     * a misbehaving source is a loud host error, not a guest corruption.
+     * Serves `random`, `insecure`, and `get-*-u64` alike; `insecure-seed`
+     * stays governed by `insecureSeed`.
+     */
+    source?: (len: number) => Uint8Array;
+}
+/** `wasi:random@0.2` + `@0.3` provider fragment (two track keys). */
+export declare function random(options?: RandomOptions): {
+    imports: Record<string, unknown>;
+};

package/types/sockets.d.ts

@@ -0,0 +1,22 @@
+import type { IpAddress, SocketsOptions, TcpSocketClass, UdpSocketClass } from "./internal/sockets_shared.js";
+export { type IpAddress, type IpAddressFamily, ipHostname, type IpSocketAddress, type Ipv4Address, type Ipv4SocketAddress, type Ipv6Address, type Ipv6SocketAddress, isUnspecified, isValidAddressFamily, mapPlatformError, MAX_UDP_DATAGRAM_SIZE, type NameLookupErrorCode, type NetAddr, parseNetAddr, sameSocketAddress, type SocketErrorCode, type SocketResult, type SocketsOptions, type TcpAcceptStream, type TcpByteStream, type TcpSendSource, type TcpSocket, type TcpSocketClass, type UdpSocket, type UdpSocketClass, wildcardAddress, } from "./internal/sockets_shared.js";
+export { Network, type SocketErrorCode02, SocketIoError, } from "./internal/sockets_02.js";
+export declare const SOCKETS_TYPES_INTERFACE = "wasi:sockets/types@0.3";
+/** What `sockets()` returns: the imports fragment plus the fragment's classes. */
+export interface SocketsShim {
+    imports: Record<string, unknown>;
+    /** The 0.3 track's resource classes (exposed for direct/test use). */
+    UdpSocket: UdpSocketClass;
+    TcpSocket: TcpSocketClass;
+    /** 0.3 `ip-name-lookup.resolve-addresses` (exposed for direct/test use). */
+    resolveAddresses: (name: string) => Promise<IpAddress[]>;
+}
+/**
+ * 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 declare function sockets(options?: SocketsOptions): SocketsShim;