@polyengine/wasi 0.1.0-pre.g633468a

package/types/http.d.ts

@@ -0,0 +1,169 @@
+import { Stream } from "@polyengine/runtime/embedder";
+/** The compatibility track the fragment registers on by default. */
+export declare const HTTP_TRACK = "0.3";
+/** `method` — case names verbatim (A10). */
+export type Method = {
+    kind: "get";
+} | {
+    kind: "head";
+} | {
+    kind: "post";
+} | {
+    kind: "put";
+} | {
+    kind: "delete";
+} | {
+    kind: "connect";
+} | {
+    kind: "options";
+} | {
+    kind: "trace";
+} | {
+    kind: "patch";
+} | {
+    kind: "other";
+    value: string;
+};
+/** `scheme` — case names verbatim (the WIT capitalizes HTTP/HTTPS). */
+export type Scheme = {
+    kind: "HTTP";
+} | {
+    kind: "HTTPS";
+} | {
+    kind: "other";
+    value: string;
+};
+/**
+ * `error-code` — the case-name vocabulary, verbatim. Only the cases this
+ * provider can actually emit are listed with payload shapes; the guest
+ * switches against strings either way.
+ */
+export type ErrorCode = {
+    kind: string;
+    value?: unknown;
+};
+/** `header-error` (0.3.1 added `size-exceeded` and `other`). */
+export type HeaderError = {
+    kind: "invalid-syntax" | "forbidden" | "immutable" | "size-exceeded";
+} | {
+    kind: "other";
+    value?: string;
+};
+/** `request-options-error` (0.3.1 added `other`). */
+export type RequestOptionsError = {
+    kind: "not-supported" | "immutable";
+} | {
+    kind: "other";
+    value?: string;
+};
+/**
+ * `result<option<trailers>, error-code>` AS A VALUE (trailers futures).
+ * The ok side CARRIES a payload (`option<trailers>`), so `ok(none)` is
+ * `{ kind: "ok", value: undefined }` — the `value` key must be present
+ * (outermost-option-as-undefined; the adapter requires the key on
+ * payload-carrying cases).
+ */
+export type TrailersResult = {
+    kind: "ok";
+    value: Fields | undefined;
+} | {
+    kind: "err";
+    value: ErrorCode;
+};
+/** `result<_, error-code>` AS A VALUE (transmission futures). */
+export type HttpResult = {
+    kind: "ok";
+} | {
+    kind: "err";
+    value: ErrorCode;
+};
+/** Map a fetch failure onto `error-code` (sniff table + honest catch-all). */
+export declare function mapFetchError(e: unknown): ErrorCode;
+/** What body params accept: the lifted handle, or any natural byte producer. */
+export type BodySource = Stream<number> | AsyncIterable<Uint8Array | number[]> | Iterable<Uint8Array | number[]>;
+/** What future params accept: the lifted handle or a promise of the value. */
+export type FutureLike<T> = PromiseLike<T>;
+export interface HttpOptions {
+    /**
+     * Override the registration keys for a guest pinned to a PRERELEASE
+     * snapshot (`0.3.0-rc-*`), which the resolver matches exactly — no
+     * track exists for prereleases. Default: the `@0.3` track, serving
+     * every released 0.3.x.
+     */
+    version?: string;
+    /** Observe every entry point the guest reaches (see sockets' onCall). */
+    onCall?: (call: string) => void;
+}
+/** What `http()` returns: the imports fragment plus the fragment's classes. */
+export interface HttpFragment {
+    imports: Record<string, unknown>;
+    Fields: FieldsClass;
+    Request: RequestClass;
+    RequestOptions: RequestOptionsClass;
+    Response: ResponseClass;
+    /** The `client.send` impl, exposed so an embedder may re-key it (e.g. as a handler). */
+    send: HttpSend;
+}
+/** The `client.send` shape (module-scope names: the public interfaces). */
+export type HttpSend = (request: Request) => Promise<Response>;
+export interface Fields {
+    get(name: string): Uint8Array[];
+    has(name: string): boolean;
+    set(name: string, value: Uint8Array[]): void;
+    delete(name: string): void;
+    getAndDelete(name: string): Uint8Array[];
+    append(name: string, value: Uint8Array): void;
+    copyAll(): [string, Uint8Array][];
+    clone(): Fields;
+    [Symbol.dispose](): void;
+}
+export interface FieldsClass {
+    new (): Fields;
+    fromList(entries: [string, Uint8Array][]): Fields;
+}
+export interface Request {
+    getMethod(): Method;
+    setMethod(method: Method): void;
+    getPathWithQuery(): string | undefined;
+    setPathWithQuery(pathWithQuery: string | undefined): void;
+    getScheme(): Scheme | undefined;
+    setScheme(scheme: Scheme | undefined): void;
+    getAuthority(): string | undefined;
+    setAuthority(authority: string | undefined): void;
+    getOptions(): RequestOptions | undefined;
+    getHeaders(): Fields;
+    [Symbol.dispose](): void;
+}
+export interface RequestClass {
+    "new"(headers: Fields, contents: BodySource | undefined, trailers: FutureLike<TrailersResult>, options: RequestOptions | undefined): [Request, Promise<HttpResult>];
+    consumeBody(request: Request, res: FutureLike<HttpResult>): [AsyncIterable<Uint8Array>, Promise<TrailersResult>];
+}
+export interface RequestOptions {
+    getConnectTimeout(): bigint | undefined;
+    setConnectTimeout(duration: bigint | undefined): void;
+    getFirstByteTimeout(): bigint | undefined;
+    setFirstByteTimeout(duration: bigint | undefined): void;
+    getBetweenBytesTimeout(): bigint | undefined;
+    setBetweenBytesTimeout(duration: bigint | undefined): void;
+    clone(): RequestOptions;
+    [Symbol.dispose](): void;
+}
+export interface RequestOptionsClass {
+    new (): RequestOptions;
+}
+export interface Response {
+    getStatusCode(): number;
+    setStatusCode(statusCode: number): void;
+    getHeaders(): Fields;
+    [Symbol.dispose](): void;
+}
+export interface ResponseClass {
+    "new"(headers: Fields, contents: BodySource | undefined, trailers: FutureLike<TrailersResult>): [Response, Promise<HttpResult>];
+    consumeBody(response: Response, res: FutureLike<HttpResult>): [AsyncIterable<Uint8Array>, Promise<TrailersResult>];
+}
+/**
+ * `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 declare function http(options?: HttpOptions): HttpFragment;

package/types/internal/cli_shared.d.ts

@@ -0,0 +1,26 @@
+import { Stream } from "@polyengine/runtime/embedder";
+/** `wasi:cli/types@0.3`'s `error-code` ENUM: bare kebab-case strings (the
+ * A10 value table — enums are data strings, not `{kind}` variants; this
+ * type carried a `{kind}` wrapper until 2026-08-14, a latent bug no err
+ * path had exercised). */
+export type CliErrorCode = "io" | "illegal-byte-sequence" | "pipe";
+/** `result<_, error-code>` AS A VALUE (the 0.3 stdio futures). */
+export type CliIoResult = {
+    kind: "ok";
+} | {
+    kind: "err";
+    value: CliErrorCode;
+};
+/** What 0.3 write-via-stream accepts: the lifted handle or any byte producer. */
+export type CliByteSource = Stream<number> | AsyncIterable<Uint8Array | number[]> | Iterable<Uint8Array | number[]>;
+/** Raised by `exit()` when `throwOnExit` is set (contract: "option to throw a named ExitError"). */
+export declare class ExitError extends Error {
+    readonly ok: boolean;
+    readonly code?: number | undefined;
+    constructor(ok: boolean, code?: number | undefined);
+}
+/** `terminal-input`/`terminal-output` are opaque resources; never produced (no terminal). */
+export declare class TerminalInput {
+}
+export declare class TerminalOutput {
+}

package/types/internal/fs_provider.d.ts

@@ -0,0 +1,174 @@
+import { ComponentException, Stream } from "@polyengine/runtime/embedder";
+import { IoError } from "../io.js";
+/** `wasi:filesystem/types.error-code` labels. 0.2 (enum): all of these,
+ * bare. 0.3 (variant): all but `would-block`, as `{kind}` — this package
+ * never produces `would-block`, so the union serves both tracks. */
+export type FsErrorCode = "access" | "would-block" | "already" | "bad-descriptor" | "busy" | "deadlock" | "quota" | "exist" | "file-too-large" | "illegal-byte-sequence" | "in-progress" | "interrupted" | "invalid" | "io" | "is-directory" | "loop" | "too-many-links" | "message-size" | "name-too-long" | "no-device" | "no-entry" | "no-lock" | "insufficient-memory" | "insufficient-space" | "not-directory" | "not-empty" | "not-recoverable" | "unsupported" | "no-tty" | "no-such-device" | "overflow" | "not-permitted" | "pipe" | "read-only" | "invalid-seek" | "text-file-busy" | "cross-device";
+/** `descriptor-type` (enum: bare strings). */
+export type DescriptorType = "unknown" | "block-device" | "character-device" | "directory" | "fifo" | "symbolic-link" | "regular-file" | "socket";
+/** `wasi:clocks` wall-clock `datetime` record, as a value. */
+export interface Datetime {
+    seconds: bigint;
+    nanoseconds: number;
+}
+/** What a backend reports from stat; absent timestamp = unavailable. */
+export interface FsStat {
+    type: DescriptorType;
+    linkCount: bigint;
+    size: bigint;
+    atimeNs?: bigint;
+    mtimeNs?: bigint;
+    ctimeNs?: bigint;
+}
+/** A stable per-object identity (dev/ino-ish) for metadata-hash and
+ * is-same-object; backends without a native one synthesize (e.g. from
+ * the path). */
+export interface FsIdentity {
+    a: bigint;
+    b: bigint;
+}
+/** A set-times instruction, backend-facing (ns since epoch). */
+export type TimeSpec = {
+    kind: "no-change";
+} | {
+    kind: "now";
+} | {
+    kind: "timestamp";
+    ns: bigint;
+};
+/** Decoded open-at intent (path-flags + open-flags + descriptor-flags). */
+export interface OpenOptions {
+    follow: boolean;
+    create: boolean;
+    directory: boolean;
+    exclusive: boolean;
+    truncate: boolean;
+    read: boolean;
+    write: boolean;
+}
+export interface Opened<H> {
+    handle: H;
+    type: DescriptorType;
+}
+export type MaybeAsync<T> = T | Promise<T>;
+/**
+ * The backend seam. `isSync: true` promises every op returns a plain
+ * value (node); `false` allows promises everywhere and buys the 0.2
+ * track its suspending marks (OPFS). Ops receive validated, non-escaping
+ * segment lists (possibly empty = the base itself). Ops throw RAW
+ * platform errors; `mapError` names them.
+ */
+export interface FsBackend<H> {
+    isSync: boolean;
+    mapError(e: unknown): FsErrorCode;
+    openAt(base: H, segments: string[], opts: OpenOptions): MaybeAsync<Opened<H>>;
+    close(h: H): void;
+    stat(h: H): MaybeAsync<FsStat>;
+    statAt(base: H, segments: string[], follow: boolean): MaybeAsync<FsStat>;
+    /** Short reads are fine; empty result with `length > 0` = EOF. */
+    read(h: H, length: number, offset: number): MaybeAsync<Uint8Array>;
+    write(h: H, buffer: Uint8Array, offset: number): MaybeAsync<number>;
+    append(h: H, buffer: Uint8Array): MaybeAsync<number>;
+    setSize(h: H, size: number): MaybeAsync<void>;
+    setTimes(h: H, atime: TimeSpec, mtime: TimeSpec): MaybeAsync<void>;
+    setTimesAt(base: H, segments: string[], follow: boolean, atime: TimeSpec, mtime: TimeSpec): MaybeAsync<void>;
+    syncAll(h: H): MaybeAsync<void>;
+    syncData(h: H): MaybeAsync<void>;
+    readDirectory(h: H): MaybeAsync<{
+        name: string;
+        type: DescriptorType;
+    }[]>;
+    createDirectoryAt(base: H, segments: string[]): MaybeAsync<void>;
+    removeDirectoryAt(base: H, segments: string[]): MaybeAsync<void>;
+    unlinkFileAt(base: H, segments: string[]): MaybeAsync<void>;
+    renameAt(oldBase: H, oldSegments: string[], newBase: H, newSegments: string[]): MaybeAsync<void>;
+    /** Optional families: absent = `unsupported`. */
+    linkAt?(oldBase: H, oldSegments: string[], follow: boolean, newBase: H, newSegments: string[]): MaybeAsync<void>;
+    symlinkAt?(target: string, base: H, segments: string[]): MaybeAsync<void>;
+    readlinkAt?(base: H, segments: string[]): MaybeAsync<string>;
+    identity(h: H): MaybeAsync<FsIdentity>;
+    identityAt(base: H, segments: string[], follow: boolean): MaybeAsync<FsIdentity>;
+    isSame(a: H, b: H): MaybeAsync<boolean>;
+}
+/** `descriptor-stat` record as a value (option fields: absent = none). */
+export interface DescriptorStatValue {
+    type: DescriptorType;
+    linkCount: bigint;
+    size: bigint;
+    dataAccessTimestamp?: Datetime;
+    dataModificationTimestamp?: Datetime;
+    statusChangeTimestamp?: Datetime;
+}
+/** `descriptor-flags` as a value (flags record: camelCase booleans). */
+export interface DescriptorFlagsValue {
+    read: boolean;
+    write: boolean;
+    fileIntegritySync: boolean;
+    dataIntegritySync: boolean;
+    requestedWriteSync: boolean;
+    mutateDirectory: boolean;
+}
+/** `directory-entry` record. */
+export interface DirectoryEntryValue {
+    type: DescriptorType;
+    name: string;
+}
+export interface MetadataHashValue {
+    lower: bigint;
+    upper: bigint;
+}
+/** 0.3 `result<_, error-code>` as a future/tuple VALUE (A12 shapes). */
+export type FsResult03 = {
+    kind: "ok";
+} | {
+    kind: "err";
+    value: {
+        kind: FsErrorCode;
+    };
+};
+/** What 0.3 write/append-via-stream accepts (the lifted stream handle or
+ * any byte producer, mirroring cli's CliByteSource). */
+export type FsByteSource = Stream<number> | AsyncIterable<Uint8Array | number[]> | Iterable<Uint8Array | number[]>;
+/**
+ * The io `error` resource minted by filesystem STREAM failures, carrying
+ * the error-code so 0.2's `filesystem-error-code(borrow<error>)` can
+ * downcast it (SinkOutputStream preserves IoError subclasses).
+ */
+export declare class FsIoError extends IoError {
+    readonly code: FsErrorCode;
+    constructor(code: FsErrorCode, message: string);
+}
+type ErrShape = (code: FsErrorCode) => ComponentException<unknown>;
+/**
+ * Validate and normalize a guest path to non-escaping segments (module
+ * header). `shape` picks the track's error payload.
+ */
+export declare function parsePath(path: string, shape: ErrShape): string[];
+export interface FilesystemFragment {
+    imports: Record<string, unknown>;
+}
+/**
+ * Package-level capability options shared by every `wasi:filesystem`
+ * implementation (module header, "READ-ONLY BY DEFAULT").
+ */
+export interface FilesystemAccessOptions {
+    /**
+     * Grant write access to the WHOLE implementation. Default `false`:
+     * every mutating operation refuses with the WIT `read-only` error
+     * code, `get-flags` never advertises `write`/`mutate-directory`, and
+     * `open-at` refuses write descriptor-flags as well as the
+     * `create`/`truncate`/`exclusive` open-flags.
+     *
+     * Deliberately NOT per-preopen: see the module header for why a
+     * global flag is the checkable design.
+     */
+    writable?: boolean;
+}
+/**
+ * Build the two-track `wasi:filesystem` import fragment over a backend.
+ * `preopens`: directory handles with their guest names, served (as fresh
+ * per-call descriptors) by both tracks' `preopens#get-directories`.
+ * `access.writable` (default false) is the package-level write grant.
+ */
+export declare function makeFilesystem<H>(backend: FsBackend<H>, preopens: [H, string][], access?: FilesystemAccessOptions): FilesystemFragment;
+export {};

package/types/internal/sockets_02.d.ts

@@ -0,0 +1,37 @@
+import { IoError } from "../io.js";
+import { type IpSocketAddress } from "./sockets_shared.js";
+/** `wasi:sockets/network@0.2`'s `error-code` ENUM: bare strings. */
+export type SocketErrorCode02 = "unknown" | "access-denied" | "not-supported" | "invalid-argument" | "out-of-memory" | "timeout" | "concurrency-conflict" | "not-in-progress" | "would-block" | "invalid-state" | "new-socket-limit" | "address-not-bindable" | "address-in-use" | "remote-unreachable" | "connection-refused" | "connection-reset" | "connection-aborted" | "datagram-too-large" | "name-unresolvable" | "temporary-resolver-failure" | "permanent-resolver-failure";
+/**
+ * The io `error` resource minted by 0.2 socket STREAM failures, carrying
+ * the error-code so `network-error-code(borrow<error>)` can downcast it
+ * (the filesystem-error-code pattern; SinkOutputStream and
+ * FedInputStream preserve IoError subclasses).
+ */
+export declare class SocketIoError extends IoError {
+    readonly code: SocketErrorCode02;
+    constructor(code: SocketErrorCode02, message: string);
+}
+/** `wasi:sockets/network@0.2`'s opaque capability resource. */
+export declare class Network {
+}
+/** `shutdown-type` enum values. */
+export type ShutdownType = "receive" | "send" | "both";
+/** `incoming-datagram` / `outgoing-datagram` records. */
+export interface IncomingDatagram {
+    data: Uint8Array;
+    remoteAddress: IpSocketAddress;
+}
+export interface OutgoingDatagram {
+    data: Uint8Array;
+    remoteAddress?: IpSocketAddress;
+}
+/** What `sockets02()` hands back for registration by `sockets()`. */
+export interface Sockets02Fragment {
+    imports: Record<string, unknown>;
+}
+/**
+ * Build the `wasi:sockets@0.2` interfaces (module header). `onCall` is
+ * the same fragment-scoped observer the 0.3 track takes.
+ */
+export declare function sockets02(onCall: (call: string) => void): Sockets02Fragment;

package/types/internal/sockets_03.d.ts

@@ -0,0 +1,12 @@
+import { type IpAddress, type TcpSocketClass, type UdpSocketClass } from "./sockets_shared.js";
+/**
+ * Build the `@0.3` track: `wasi:sockets/types@0.3` (UDP + TCP resource
+ * classes, per-fragment so the `onCall` observer is scoped) and
+ * `wasi:sockets/ip-name-lookup@0.3`.
+ */
+export declare function sockets03(onCall: (call: string) => void): {
+    imports: Record<string, unknown>;
+    UdpSocket: UdpSocketClass;
+    TcpSocket: TcpSocketClass;
+    resolveAddresses: (name: string) => Promise<IpAddress[]>;
+};

package/types/internal/sockets_platform.d.ts

@@ -0,0 +1,112 @@
+/** The address shape the socket backends speak. */
+export interface NetAddr {
+    transport?: string;
+    hostname: string;
+    port: number;
+}
+/** The bound-datagram-socket seam. */
+export interface DatagramConn {
+    readonly addr: NetAddr;
+    /** No `addr` = connected-mode send (valid only after `connect`). */
+    send(p: Uint8Array, addr?: NetAddr): Promise<number>;
+    receive(): Promise<[Uint8Array, NetAddr]>;
+    close(): void;
+    /** OS-level connected mode (kernel filters + default destination).
+     * Optional capability: absent = the provider answers `not-supported`. */
+    connect?(addr: NetAddr): Promise<void>;
+    disconnect?(): void;
+    /** IP_TTL / IPV6_UNICAST_HOPS. Optional capability. */
+    setTtl?(ttl: number): void;
+    /** SO_RCVBUF / SO_SNDBUF. Optional capabilities. */
+    getRecvBufferSize?(): number;
+    setRecvBufferSize?(size: number): void;
+    getSendBufferSize?(): number;
+    setSendBufferSize?(size: number): void;
+    /** Non-blocking queue access + readiness (the 0.2 datagram streams:
+     * poll-shaped receive instead of the promise-shaped one above).
+     * Optional capabilities. */
+    tryReceive?(): [Uint8Array, NetAddr] | undefined;
+    receiveReady?(): boolean;
+    /** The CURRENT epoch's wake promise (promise-swap: settles when a
+     * datagram arrives, the socket errors, or it closes; re-armed per event). */
+    waitReceive?(): Promise<void>;
+}
+export type ListenDatagram = (options: {
+    transport: "udp";
+    hostname: string;
+    port: number;
+}) => DatagramConn;
+/** The connected-TCP-socket seam. */
+export interface TcpConn {
+    readonly localAddr: NetAddr;
+    readonly remoteAddr: NetAddr;
+    /** Up to `max` bytes (node's own buffer, no copy); `null` = peer FIN. */
+    read(max: number): Promise<Uint8Array | null>;
+    write(p: Uint8Array): Promise<number>;
+    closeWrite(): Promise<void>;
+    close(): void;
+    /** SO_KEEPALIVE + TCP_KEEPIDLE (node exposes exactly this pair).
+     * Optional capability: absent = the provider answers `not-supported`. */
+    setKeepAlive?(enabled: boolean, idleMs: number): void;
+}
+export type TcpConnect = (options: {
+    transport: "tcp";
+    hostname: string;
+    port: number;
+    /** Source binding (connect-from-bound); both or neither. */
+    localHostname?: string;
+    localPort?: number;
+}) => Promise<TcpConn>;
+/**
+ * The listening-TCP-socket seam. The OS bind is deferred (module header):
+ * `settled()` resolves once the listener is live (rejects with the bind
+ * failure), after which `addr` is non-null.
+ */
+export interface TcpListener {
+    readonly addr: NetAddr | null;
+    settled(): Promise<void>;
+    accept(): Promise<TcpConn>;
+    close(): void;
+    /** Non-blocking accept + readiness (the 0.2 poll-shaped accept).
+     * Optional capabilities; same promise-swap contract as `waitReceive`. */
+    tryAccept?(): TcpConn | undefined;
+    acceptReady?(): boolean;
+    waitAccept?(): Promise<void>;
+}
+export type TcpListen = (options: {
+    transport: "tcp";
+    hostname: string;
+    port: number;
+    /** The accept queue hint (SOMAXCONN-clamped by the OS). */
+    backlog?: number;
+}) => TcpListener;
+/** One `getaddrinfo` answer. */
+export interface LookupAnswer {
+    address: string;
+    family: number;
+}
+/** The name-resolution seam (node:dns `lookup` with `all: true`). */
+export type DnsLookup = (name: string) => Promise<LookupAnswer[]>;
+/** The datagram backend, re-detected per call. */
+export declare function listenDatagram(): ListenDatagram | undefined;
+/** The TCP-connect backend, re-detected per call. */
+export declare function tcpConnect(): TcpConnect | undefined;
+/** The TCP-listen backend, re-detected per call. */
+export declare function tcpListen(): TcpListen | undefined;
+/** The name-resolution backend, re-detected per call. */
+export declare function dnsLookup(): DnsLookup | undefined;
+/**
+ * Queued-but-unread datagrams past this bound are dropped (tail-drop, the
+ * kernel-buffer analogue). Node's `'message'` push keeps delivering
+ * whether or not the guest reads; unread datagrams must not accumulate
+ * without bound.
+ */
+export declare const MAX_QUEUED_DATAGRAMS = 256;
+/**
+ * Accepted-but-unread connections past this bound are REFUSED (destroyed)
+ * — node's `'connection'` push keeps accepting whether or not the guest
+ * reads the accept stream, and unlike datagrams an accepted connection is
+ * a live socket, so tail-drop here means an active refusal rather than a
+ * silent discard (the polymorph-iroh#56 stance).
+ */
+export declare const MAX_QUEUED_CONNECTIONS = 64;