Canonical definitions (section 8) are how a component crosses its shared-nothing
boundary. From the point of view of the core code inside a component, the component model is
the embedder: lift and lower wrap existing functions to convert
values between component types and core values and linear memory, and the built-ins create
core functions “out of nothing” that core modules import to work with resources, tasks,
streams and threads. This page follows design/mvp/Binary.md in the
component-model repository
(branch main, read 2026-11-18), with Text.md and
CanonicalABI.md for meanings and validation. Marks are the specification’s gates
(🔀 concurrency, 🧵 threads, 🧵② shared-everything threads, 📝 error-context, ➡️ forward);
see the status table. Only
lift, lower and the three resource built-ins, with options
00 to 05, are in the stable WASI 0.2 set.
The canon section
The contents are vec(canon). Each canon starts with an opcode byte. Opcodes
00 and 01 are followed by a second byte that stands for the
func sort. The immediates that follow are listed below; opts is a
vec(canonopt), async? and sh? are one byte (00 absent,
01 present).
| Opcode | Immediates | Definition | Gate |
|---|---|---|---|
00 00 | core funcidx, opts, typeidx | lift | |
01 00 | funcidx, opts | lower | |
02 | typeidx | resource.new | |
03 | typeidx | resource.drop | |
04 | typeidx | resource.rep | |
05 | task.cancel | 🔀 | |
06 | async? | subtask.cancel | 🔀 |
09 | resultlist, opts | task.return | 🔀 |
0A | core valtype, u32 | context.get | 🔀 |
0B | core valtype, u32 | context.set | 🔀 |
0C 00 | thread.yield | 🔀 | |
0D | subtask.drop | 🔀 | |
0E | typeidx | stream.new | 🔀 |
0F | typeidx, opts | stream.read | 🔀 |
10 | typeidx, opts | stream.write | 🔀 |
11 | typeidx, async? | stream.cancel-read | 🔀 |
12 | typeidx, async? | stream.cancel-write | 🔀 |
13 | typeidx | stream.drop-readable | 🔀 |
14 | typeidx | stream.drop-writable | 🔀 |
15 | typeidx | future.new | 🔀 |
16 | typeidx, opts | future.read | 🔀 |
17 | typeidx, opts | future.write | 🔀 |
18 | typeidx, async? | future.cancel-read | 🔀 |
19 | typeidx, async? | future.cancel-write | 🔀 |
1A | typeidx | future.drop-readable | 🔀 |
1B | typeidx | future.drop-writable | 🔀 |
1C | opts | error-context.new | 📝 |
1D | opts | error-context.debug-message | 📝 |
1E | error-context.drop | 📝 | |
1F | waitable-set.new | 🔀 | |
20 00 | core memoryidx | waitable-set.wait | 🔀 |
21 00 | core memoryidx | waitable-set.poll | 🔀 |
22 | waitable-set.drop | 🔀 | |
23 | waitable.join | 🔀 | |
24 | backpressure.inc | 🔀 | |
25 | backpressure.dec | 🔀 | |
26 | thread.index | 🧵 | |
27 | core typeidx, core tableidx | thread.new-indirect | 🧵 |
28 | thread.resume-later | 🧵 | |
29 00 | thread.suspend | 🧵 | |
2A 00 | thread.suspend-then-resume | 🧵 | |
2B 00 | thread.yield-then-resume | 🧵 | |
2C 00 | thread.suspend-then-promote | 🧵 | |
2D 00 | thread.yield-then-promote | 🧵 | |
2E | typeidx | stream.forward | ➡️ |
2F | typeidx | future.forward | ➡️ |
40 | sh?, core typeidx | thread.spawn-ref | 🧵② |
41 | sh?, core typeidx, core tableidx | thread.spawn-indirect | 🧵② |
42 | sh? | thread.available-parallelism | 🧵② |
Opcodes 07, 08, 30 to 3F and anything above
42 have no meaning in Binary.md. In the
second-byte cases (0C, 20 to 21 and 29 to
2D) the 00 is vestigial and may be removed in version 1.0; the
wart list also says the opcodes are to be re-sorted and most built-ins should take a
canonopt vector. In the binary, the async? byte is where the text
format writes the optional word async.
Example: section 8 holding one lift of core function 0, with no options, as
component function type 0: 08 06 01 00 00 00 00 00. That is: ID 8, size 6, count 1,
opcode 00 00, core funcidx 00, empty option vector 00,
typeidx 00. The bytes are worked out from the grammar; the type has to be a
function type whose canonical-ABI form matches the core function.
lift and lower
lift wraps a core function (a core:functype) to make a component
function (a functype) that can be passed to other components. lower
wraps a component function to make a core function that core code in this component can
import and call. The typeidx of lift names the component function type of the
result; the funcidx of lower is a component function and the result is a core
function whose type derives from it by flattening.
Extra validation for lift (from CanonicalABI.md): the core
function must have the flattened form of the function type; if a post-return
is present it takes the flattened results and returns nothing; options are required by the
parameter and result types, as in the option rules below; if the flattened parameters exceed
MAX_FLAT_PARAMS (16) a realloc is required; if the flattened
results exceed the maximum (MAX_FLAT_RESULTS, 1, for synchronous lifts;
MAX_FLAT_PARAMS for async lifts) a memory is required. MAX_FLAT_ASYNC_PARAMS (4) is not used by lift: it applies
only when lowering an 🔀 async function (flatten_functype
with direction lower; see Flattening); an async lift uses
MAX_FLAT_PARAMS. In 🔀 async lifts the result
type’s memory option must be exactly that of the task.return called
at run time.
Canonical options
An opts is vec(canonopt), each a code byte and optionally an index.
| Code | Immediate | Option | Meaning | Gate |
|---|---|---|---|---|
00 | string-encoding=utf8 | Strings are UTF-8 (the default when no string-encoding option is present). | ||
01 | string-encoding=utf16 | Strings are UTF-16. | ||
02 | string-encoding=latin1+utf16 | A dynamic choice per string between Latin-1 (one byte per code point, limited range) and UTF-16. It reflects a common encoding of Java, JavaScript and .NET. | ||
03 | core memoryidx | (memory m) | The linear memory used to load and store values. Required whenever the ABI needs to load or store; no default. | |
04 | core funcidx | (realloc f) | The function the ABI calls to allocate (passing 0 for the first two arguments) and reallocate. Required when it needs one; no default. | |
05 | core funcidx | (post-return f) | Called after the results have been read, with the original results, so memory can be freed. Only in lift; optional. | |
06 | async | The component makes (import) or supports (export) several concurrent calls. Only with async function types. | 🔀 | |
07 | core funcidx | (callback f) | The callback function of an async lift. Only in lift and only with async. | 🔀 |
Validation:
- Duplicate or conflicting options are rejected: each option at most once, and at most one
string-encodingwhichever it is. memorymust be a subtype of(memory 0); with 🐘 also of(memory i64 0).reallocmust have type(func (param addr addr addr addr) (result addr))whereaddris the address type of thememoryoption (i32; with 🐘 possiblyi64): the four parameters are the original pointer, original size, alignment and new size. Areallocneeds amemory.post-returnis only allowed inlift, not together withasync.asyncneeds an async function type and cannot be combined withpost-return; without the 🚟 feature it also needscallback.callbackneedsasync, is only forlift, and has type(func (param i32 i32 i32) (result i32)).- For
lowerof a type containing alistorstring,memoryis required; forliftof such a type,reallocis required.
Resource built-ins
| Built-in | Core signature | Meaning |
|---|---|---|
resource.new | [rep] -> [i32] | Creates a resource of the type with rep as its representation and returns a new owning handle. Valid only inside the component that defined the type. |
resource.drop | [i32] -> [] | Drops a handle; if it was an owning handle and the resource has a destructor, calls it. |
resource.rep | [i32] -> [rep] | Returns the representation of the resource a handle points to. Valid only inside the component that defined the type. |
Here rep is the representation type of the resource type: i32, or
i64 with the 🐘 gate.
Concurrency, thread and error-context built-ins
All are gated. The core signature is the “Canonical ABI signature” of Text.md;
memory.addrtype is i32 or (🐘) i64, the address type of the
memory named by the option or immediate. The purpose is the specification’s own summary, shortened;
the full semantics are in the concurrency explainer, which is not covered here.
| Built-in | Core signature | Purpose |
|---|---|---|
context.get 🔀 | [] -> [T] | Returns the ith element of the current thread’s context slots (T and i are immediates). |
context.set 🔀 | [T] -> [] | Sets the ith context slot of the current thread. |
backpressure.inc, backpressure.dec 🔀 | [] -> [] | Increase and decrease the backpressure on the component (semantics in the concurrency explainer). |
task.return 🔀 | [lowered results] -> [] | Returns the result values of the current task. |
task.cancel 🔀 | [] -> [] | Says the current task is now resolved as cancelled. |
waitable-set.new 🔀 | [] -> [i32] | Returns the index of a new waitable set. |
waitable-set.wait 🔀 | [i32 addr] -> [i32] | Suspends the current thread until an event is available from the set; the event code is returned and its payload written at the address. |
waitable-set.poll 🔀 | [i32 addr] -> [i32] | Returns an event from the set if there is one, without waiting. |
waitable-set.drop 🔀 | [i32] -> [] | Removes a waitable set. |
waitable.join 🔀 | [i32 i32] -> [] | Adds a waitable to a waitable set (or removes it from its set). |
subtask.cancel 🔀 | [i32] -> [i32] | Requests cancellation of a subtask; async? selects the asynchronous form. |
subtask.drop 🔀 | [i32] -> [] | Removes a subtask from the table. |
stream.new, future.new 🔀 | [] -> [i64] | Create a stream or future; the result packs the two ends (readable and writable). |
stream.read, stream.write 🔀 | [i32 addr addr] -> [addr] | Read from or write to a stream end using a buffer in memory; the result reports progress. |
future.read, future.write 🔀 | [i32 addr] -> [i32] | Read from or write to a future end. |
stream.cancel-read, stream.cancel-write, future.cancel-read, future.cancel-write 🔀 | [i32] -> [i32] | Cancel a pending read or write. |
stream.drop-readable, stream.drop-writable, future.drop-readable, future.drop-writable 🔀 | [i32] -> [] | Drop one end. |
stream.forward, future.forward ➡️ | [i32 i32] -> [] | Forward a readable end into a writable end. |
thread.index 🧵 | [] -> [i32] | Returns the index of the current thread. |
thread.new-indirect 🧵 | [addr, first param] -> [i32] | Adds a new thread to the component instance that will call a table function. |
thread.resume-later 🧵 | [i32] -> [] | Changes the state of a thread so that it can be resumed later (see the concurrency explainer). |
thread.suspend 🧵 | [] -> [i32] | Suspends the current thread until resumed. |
thread.yield 🔀 | [] -> [i32] | Lets the runtime switch to another thread. |
thread.suspend-then-resume, thread.yield-then-resume, thread.suspend-then-promote, thread.yield-then-promote 🧵 | [i32] -> [i32] | Suspend or yield the current thread and then resume or promote another thread. |
thread.spawn-ref, thread.spawn-indirect 🧵② | […] -> [i32] | Fused thread creation and start, optionally of a shared function. |
thread.available-parallelism 🧵② | [] -> [i32] | The number of threads that can run in parallel. |
error-context.new 📝 | [addr addr] -> [i32] | Creates an error-context from a message in memory; the host may alter the message. |
error-context.debug-message 📝 | [i32 addr] -> [] | Writes the debug message of an error-context to memory. |
error-context.drop 📝 | [i32] -> [] | Drops an error-context. |
The 🚝 gate (“more canonical ABI options on more async-related built-ins”) is not marked
on any production in Binary.md, which today gives canonopts to only some
built-ins (stream.read, stream.write, future.read,
future.write, task.return and the error-context ones).
Validation of each canonical definition
Binary.md sends the validation of the individual canonical definitions to
CanonicalABI.md, “Canonical Definitions”. This section lists the static
checks that text gives for every definition, apart from lift and lower
(above) and the option rules (Canonical options). The run-time behaviour
of each built-in (traps, tables, tasks) is the part of the Canonical ABI that is outside a
binary-format reference and is not described. In the rules, $f is the core function
the definition creates and “is given type” means that is the type the core function gets;
addr and T are i32, and with 🐘 (64-bit memories) may also be
i64, as the address type of the memory or table involved. A stream or future
type must be of the form (stream $t?) or (future $t?).
| Definition | Rules |
|---|---|
lower | With cx = lower context and the callee type ft: $f is given type flatten_functype(cx, ft); options required by lower(param) for every parameter and by lift(result) if there is a result; if the flattened parameters exceed the maximum, or the flattened results exceed the maximum, memory is required (the text names the limits max_flat_params and max_flat_results). |
resource.new | $rt must be a locally defined (not imported) resource type; $f has type (func (param $rt.rep) (result i32)), where $rt.rep is i32 (🐘: i32 or i64). |
resource.drop | $rt must be a resource type (imported ones too); $f has type (func (param i32)). |
resource.rep | $rt must be a locally defined (not imported) resource type; $f has type (func (param i32) (result $rt.rep)) with $rt.rep as for resource.new. The “locally defined” rule is what restricts access to a representation to the instance that defines the resource. |
context.get 🔀 | $t must be i32 (🐘: also i64, and all context.get and context.set of one component must give the same $t); $i must be 0 (🧵: also 1); $f has type (func (result $t)). |
context.set 🔀 | The same rules on $t and $i; $f has type (func (param $t)). |
backpressure.inc, backpressure.dec 🔀 | Type (func). |
task.return 🔀 | In addition to the general option rules: $f has type flatten_functype(('lower', $opts), (func (param $t)?)); $t must not transitively contain a borrow; the options may contain only memory and string-encoding; the options that lift of the result type requires are required. |
task.cancel 🔀 | Type (func). |
waitable-set.new 🔀 | Type (func (result i32)). |
waitable-set.wait, waitable-set.poll 🔀 | Type (func (param $si i32) (param $ptr T) (result i32)), where T is i32 (🐘: i32 or i64 as the address type of the memory $mem). |
waitable-set.drop 🔀 | Type (func (param i32)). |
waitable.join 🔀 | Type (func (param $wi i32) (param $si i32)). |
subtask.cancel 🔀 | Type (func (param i32) (result i32)). 🚝: async is allowed; otherwise it must be absent. |
subtask.drop 🔀 | Type (func (param i32)). |
stream.new, future.new 🔀 | Type (func (result i64)); the type must be a stream or future type. |
stream.read, stream.write 🔀 | In addition to the general option rules: type (func (param i32 T T) (result T)), T being i32 (🐘: i32 or i64 as the address type of the memory option, or i32 if there is none); a stream type. If the element type $t is present: the options that lower($t) requires (for write) or lift($t) requires (for read), and memory must be present. 🚝: async may be omitted; otherwise it must be present. |
future.read, future.write 🔀 | As above, with type (func (param i32 T) (result i32)) and a future type. |
stream.cancel-read, stream.cancel-write, future.cancel-read, future.cancel-write 🔀 | Type (func (param i32) (result i32)); a stream or future type; 🚝: async allowed, otherwise it must be absent. |
stream.drop-readable, stream.drop-writable, future.drop-readable, future.drop-writable 🔀 | Type (func (param i32)); a stream or future type. |
stream.forward, future.forward ➡️ | Type (func (param $ri i32) (param $wi i32)); a stream or future type. |
thread.index 🧵 | Type (func (result i32)). |
thread.new-indirect 🧵 | $ft must refer to the type (func (param $c T)) with T i32 (🐘: also i64); $ftbl must refer to a table whose element type is funcref; $f has type (func (param $fi U) (param $c T) (result i32)), U being i32 (🐘: as the address type of the table). |
thread.resume-later 🧵 | Type (func (param $i i32)). |
thread.suspend 🧵, thread.yield 🔀 | Type (func (result i32)). |
thread.suspend-then-resume, thread.yield-then-resume, thread.suspend-then-promote, thread.yield-then-promote 🧵 | Type (func (param $i i32) (result i32)). |
error-context.new 📝 | Type (func (param $ptr T) (param $units T) (result i32)), T being i32 (🐘: as the address type of the memory option); async must not be present; memory must be present. |
error-context.debug-message 📝 | Type (func (param i32) (param $ptr T)) with T as above; async must not be present; memory and realloc must be present. |
error-context.drop 📝 | Type (func (param i32)). |
thread.spawn-ref 🧵② | $ft must refer to (shared? (func (param $c T))), T being i32 (🐘: also i64); $f has type (shared? (func (param $f (ref null $ft)) (param $c T) (result $e i32))). Without shared the spawned thread is cooperative; with it, preemptive and able to run in parallel. |
thread.spawn-indirect 🧵② | $ft as for thread.spawn-ref; $tbl must refer to a shared table whose element type matches (ref null (shared? func)); $f has type (shared? (func (param $i U) (param $c T) (result $e i32))), U being i32 (🐘: as the address type of the table). |
thread.available-parallelism 🧵② | Type (func shared? (result i32)). |
In thread.new-indirect the parameter $c is the closure value that is passed to the
table function when the new thread is first resumed (CanonicalABI.md).
Flattening, alignment and element size
The two rules that Binary.md states for validation, that the core function of a
lift has the type flatten_functype(cx, ft) and that every value type defined by a
component has an element size below 228, use the functions below, from
CanonicalABI.md (“Flattening”, “Alignment”, “Element Size”, “Despecialization”). The
context cx holds the direction (lift or lower) and the
canonical options; the memory’s pointer type ptr_type is its address type
(i32, or i64 for 🐘), and ptr_size is 4 or 8 bytes.
Despecialisation
The specialised value types are replaced by their expansion before flattening, alignment and size are
worked out: tuple becomes a record with fields named 0,
1 and so on; enum a variant whose cases have no payload;
option<T> a variant of none and some(T);
result<ok, err> a variant of ok(ok) and error(err); and a 🗺️
map a list of (key, value) tuples. string and flags have their own
representations and are not expanded.
flatten_functype
Limits: MAX_FLAT_PARAMS 16, MAX_FLAT_ASYNC_PARAMS 4,
MAX_FLAT_RESULTS 1. The parameters are flattened with the reversed direction (a
lifted function’s parameters are lowered into the callee, and the reverse) and the results with the
direction of the context. A function is synchronous or async by its option.
| Function | Direction | Core parameters | Core results |
|---|---|---|---|
| synchronous | either | the flat parameters; if there are more than 16, a single ptr_type (pointer to a tuple in memory) | the flat results if there are at most 1; otherwise, for lift a single ptr_type result, for lower an extra ptr_type parameter at the end and no results |
async 🔀 | lift | the flat parameters; if there are more than MAX_FLAT_PARAMS (16), a single ptr_type | i32 if a callback option is present, otherwise none |
async 🔀 | lower | the flat parameters; if there are more than MAX_FLAT_ASYNC_PARAMS (4), a single ptr_type; then, if the function has any flat result, one more ptr_type parameter (where the result is written) | always i32 |
flatten_types of a list of types is the concatenation of flatten_type of each.
flatten_type
| Type | Flat core types |
|---|---|
bool, u8, u16, u32, s8, s16, s32, char | i32 |
u64, s64 | i64 |
f32, f64 | f32, f64 |
string | two ptr_type (address, length or tagged length) |
error-context, flags, own, stream, future | i32 |
borrow | i32, except that a handle lowered into the component that defined the resource is passed as the resource’s representation type (pass_rep_not_handle: the context is that instance, direction lower) |
| list (variable length) | two ptr_type |
| fixed-length list 🔧 of length n | the flat types of the element, repeated n times |
| record | the flat types of the fields, in order |
| variant | the flat type of the discriminant (i32), then, for each position, the join of the types at that position across all cases that have a payload (the longest case sets the length) |
The join of two core types is the type itself if they are equal, i32 if one is
i32 and the other f32, and i64 in every other case.
Alignment
| Type | Alignment (bytes) |
|---|---|
bool, u8, s8 | 1 |
u16, s16 | 2 |
u32, s32, f32, char, error-context, own, stream, future | 4 |
u64, s64, f64 | 8 |
string, variable-length list | ptr_size (4 or 8) |
| fixed-length list 🔧 | that of the element |
| record | the largest alignment of its fields (1 if none) |
| variant | the larger of the discriminant’s alignment and the largest alignment of any case payload (1 if no case has a payload) |
| flags | 1 for up to 8 labels, 2 for up to 16, 4 for up to 32 |
borrow | 4, or, when passed as its representation (as under flatten_type), the pointer size of the resource’s representation type |
The discriminant type of a variant with n cases is the smallest unsigned integer that
covers the case numbers: u8 for up to 256 cases, u16 for up to 65,536 and u32
beyond (the source computes ceil(log2(n) / 8) and maps 0 and 1 to u8, 2 to u16,
3 to u32, with n below 232). A flags type has 1 to 32 labels.
Element size (elem_size)
| Type | Size in memory (bytes) |
|---|---|
bool, u8, s8 | 1 |
u16, s16 | 2 |
u32, s32, f32, char, error-context, own, stream, future | 4 |
u64, s64, f64 | 8 |
string, variable-length list | 2 × ptr_size |
| fixed-length list 🔧 | length × the element’s size |
| record | start at 0; for each field, round up to the field’s alignment, then add the field’s size; finally round up to the record’s alignment. A record with no fields (total size 0) is not permitted |
| variant | the discriminant’s size, rounded up to the largest case alignment, plus the largest case payload size, rounded up to the variant’s alignment |
| flags | 1, 2 or 4, as for the alignment |
borrow | as for the alignment: 4, or the representation’s pointer size |
The 228 rule. “Component validation rules require that for every value type
t defined by a component and every possible cx, elem_size(cx, t) is less
than 228”, which is the same bound as MAX_LIST_BYTE_LENGTH. “Empty types, such as records with no fields, are not
permitted.” (CanonicalABI.md, “Element Size”; the rule is also in the type validation of
Types.)
The lift rule. For (canon lift $callee $opts (func $f (type $ft))) the core
function $callee must have exactly the type flatten_functype(cx, $ft), with
cx the lift context of the options, as defined above; $f gets the type
$ft. For a post-return the type is
(func (param flatten_functype(cx, $ft).results)).
Sources
design/mvp/Binary.md (“Canonical Definitions” and its notes),
design/mvp/Text.md (“Canonical Definitions”, “Canonical ABI”, “Canonical
Built-ins” and the built-in subsections) and design/mvp/CanonicalABI.md
(“Canonical ABI Options”, “Flattening”, “canonopt Validation”, “canon lift”, and every subsection of
“Canonical Definitions” for the validation table; “Despecialization”, “Alignment”, “Element Size”) in
github.com/WebAssembly/component-model,
raw files read 2026-11-18, and again 2026-11-19 for the validation and flattening sections.