#WebAssembly Components
Rig builds WebAssembly Components with typed imports and exports. Components let code written in different languages share an explicit contract without sharing a language-specific heap or object model.
WIT describes those contracts. An interface groups related types and functions; a world describes a complete set of imports and exports. Rig derives its Component surface from ordinary require and provide forms rather than selecting a special compilation mode for each application kind.
#Named Imports
Select members of an exact interface:
This library imports the standard argument operation and exposes a root function named arguments. The WIT name get-arguments becomes get_arguments in Rig. WIT type names use UpperCamelCase bindings.
The named reference resolves its exact WIT package through package resolution. The definition establishes types, not an implementation. A host must supply the imported interface with the appropriate authority.
For an implementation supplied by a Component package, select its exported instance explicitly, as in from="pkg:acme/store@2.0.0#example:storage/store@1.0.0". A matching contract elsewhere does not cause automatic provider selection.
#Exporting an Interface
as= states which external interface a group implements. This is a complete WASI command that succeeds without writing output:
The host recognizes the command interface and invokes run. Another application host can recognize another exported interface; the compiler still lowers the declared contract generically. rig run is specifically a command host, not a general server for every Component application.
Imports may select the members they need from a complete resolved interface. An export must implement the entire interface, with no missing, extra, or duplicate members. Root exports and other interface groups remain separate.
Public callable exports belong to Stage 0. Source modules may still provide higher-stage bindings through unqualified provide. An imported resource type at Stage 1 is contract metadata for its Stage 0 operations, not a public Stage 1 Component value.
#Boundary Types
The native type and external contract are related but distinct:
| WIT | Rig |
|---|---|
Integer/float scalars, bool |
Matching scalar width and signedness |
string |
Text |
list<T> |
(List T) |
record |
Record with corresponding fields |
tuple |
Record with fields _0, _1, and so on |
variant |
Variant with typed payloads; Null for absent payloads |
enum |
Variant whose cases all carry Null |
option<T> |
(Variant none:Null some:T) |
result<T, E> |
(Variant error:E value:T) |
flags |
Record with one Bool field per flag |
future<T>, stream<T> |
(Future T), (Stream T) |
| Resource | Selected nominal Movable type |
The resolved contract preserves distinctions that share a native shape. A flags contract is not an ordinary Boolean Record, and an enum is not interchangeable with a payload-free WIT variant. Structural compatibility does not erase foreign resource identity.
When Rig derives its own unqualified contract, it converts source field and case names to WIT spelling, such as file_size to file-size. Names that normalize to the same spelling produce a diagnostic. The exact none/some and error/value shapes select option and result. A Record projects to a tuple only when all fields are exactly _0 through _N without gaps. Other Records remain records; a Boolean Record becomes flags only under a resolved flags contract.
Fixed String, Sequence, Block, Box, Mutable, and closure values do not cross public boundaries directly. Convert String to Text or snapshot Block into List explicitly. An exported function is an interface operation; passing a native Fn as its argument or result is not supported.
Rig accepts contracts it can faithfully project. Unsupported public type or resource-sharing relationships produce diagnostics rather than losing identity or flattening interfaces.
#Resources and Ownership
A foreign resource is an opaque handle with nominal identity. Select its type and operations through the interface:
The synthetic terminal_output_drop binding performs canonical resource release; it does not require the WIT interface to declare a separate drop function. Real APIs obtain a handle through a constructor or another interface operation. Rig code cannot manufacture or inspect a foreign resource's payload.
Resource constructors, methods, and static functions project to ordinary prefixed calls: a constructor becomes descriptor_make, a method read becomes descriptor_read, and a static open becomes descriptor_open. Methods receive the resource as their first argument.
WIT own and borrow use the same selected Rig type. The exact contract records which operation transfers ownership and which temporarily lends it. An owning transfer invalidates previous Rig aliases. A borrow does not transfer ownership, but movement or release while lent traps. Received borrowed aliases become stale when their call or task ends, even if copied into longer-lived storage.
While an owning transfer is pending, conflicting use through aliases traps. After settlement, accepted aliases stay stale and rejected values become usable again.
Native packages can export named Movable references as resources, selecting their type and explicit destructor through the named provide form. The defining package retains payload authority; callers use the API. Native named Box and Mutable references are not resource projections because they lack invalidating transfer.
Release is explicit. Dropping an owned foreign resource invalidates every alias; use after transfer or release traps. Losing the last alias does not arrange deterministic release, and a trap does not guarantee cleanup.
#Asynchronous Interfaces
Call a WIT async func as an ordinary Rig function. The expression waits for the result, and the host may suspend the Component task during that wait so other components can make progress.
A synchronous Component export traps if it reaches an operation that would suspend. Static initialization forbids asynchronous host calls, even if the particular call could complete immediately.
Future T and Stream T are readable, dynamically checked endpoints. A Future yields one value; a Stream yields bounded chunks. Copies share an identity rather than creating independent consumers.
Accepting an endpoint does not accept its unread payload. That payload crosses its own ownership boundary when consumed.
#Completing a Future
bond creates a structural pair of a readable Future and a completion function:
A local Bond buffers its one value, so completing it does not wait for a local reader. wait consumes the Future and returns the value, invalidating readable aliases. Completion reports closed=true if the reader has cancelled; either result ends the writer, and completing it again traps.
After the readable end is transferred, completion may suspend until the external reader accepts or closes it. A Bond has no automatic abandonment: losing its completion function without calling it can leave the Future pending.
The Record shape is ordinary Rig data, not a compiler-owned Bond type. A library can name that shape with a staged type function. Completion functions are native Fn values and obey the ordinary capture limits.
#Streams and Backpressure
pipe similarly constructs a Record containing a stream, send, and close. send takes an immutable List and returns (Record count:Int closed:Bool). Function fields use ordinary projection and explicit application, such as ((send output) values).
A Pipe is unbuffered. A nonempty send needs a progressing reader; current native Rig execution does not schedule an independent local producer and consumer. An external component or host can supply that progress, as the output helper does with WASI stdout. Native concurrent computation and multi-source waits are not yet available.
closed=false means the entire List was accepted. With closed=true, count is the accepted prefix length, and later sends trap. Call close once to release the writer, including after reader closure. At an owning Component boundary, only accepted values invalidate their producer aliases; rejected values remain usable.
(wait input limit=4096) returns (Record values:(List T) closed:Bool) with at most that many elements. The limit must be positive. A nonfinal chunk is nonempty and leaves the Stream live. A final chunk may contain values or be empty; closed=true ends the readable identity. Here closed describes the writer ending, while send's closed describes the reader ending.
cancel explicitly ends readable interest in a Future or Stream. It is not a promise to stop a producer computation or release payload-specific resources. Endpoint aliases become stale; resource cleanup on normal paths remains explicit API code. Only one consumer or writer operation may be pending on its respective endpoint at a time.
#Hosting and Stages
The same endpoint and interface concepts exist at every stage. To call a runtime Component API at compile time, use a lifted import with the matching staged signature. The compile capability profile governs those calls. Live endpoint identities cannot be persisted through const into a later stage's execution.
The native CLI hosts commands with Wasmtime. The browser adapter uses its own engine integration and explicit host bindings, initially providing WASI environment, exit, stdout, and stderr. A Component that needs other interfaces requires a host that implements them. Capabilities explains why a valid import does not itself grant that authority.