From f77f3968523bcbd9ff6ef2db4b9c3e3904ab90b7 Mon Sep 17 00:00:00 2001 From: Bailey Hayes Date: Mon, 2 Mar 2026 22:14:43 -0500 Subject: [PATCH] Document implementation-defined resource limits in Canonical ABI Allow implementations to non-deterministically trap on cross-component calls when resource limits are exceeded, covering handle table capacity and value transfer size. This aligns with how memory.grow works in Core WebAssembly. See WebAssembly/WASI#890 for context. --- design/mvp/CanonicalABI.md | 29 ++++++++++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/design/mvp/CanonicalABI.md b/design/mvp/CanonicalABI.md index 32fb81fd..233e8675 100644 --- a/design/mvp/CanonicalABI.md +++ b/design/mvp/CanonicalABI.md @@ -106,6 +106,31 @@ nature of eliminating `realloc`, switching to [lazy lowering] would obviate this issue, allowing guest wasm code to handle failure by eagerly returning some value of the declared return type to indicate failure. +### Implementation-Defined Limits + +Beyond the explicit `trap_if` checks in the Python code below, implementations +may also trap during any cross-component call when +implementation-defined resource limits have been reached. In particular: +* An implementation may trap when the handles table has reached an + implementation-defined capacity that is at or below `Table.MAX_LENGTH`. This + allows implementations to bound the host-side memory used to track resources, + waitables and other table elements. This is analogous to how `memory.grow` + may non-deterministically return `-1` in Core WebAssembly when the + implementation cannot satisfy the allocation. +* An implementation may trap when the total size of values being transferred + across a component boundary (via lifting or lowering) exceeds an + implementation-defined limit. For example, lifting a `list` of length N + from guest linear memory requires an intermediate allocation of at least N + bytes on the host, and implementations may refuse to perform such an + allocation when N is very large. + +In both cases, the resulting trap is non-deterministic: the same call with the +same arguments may succeed at one point and trap at another depending on the +current resource usage of the implementation. Guest code should be written +defensively, but WASI-level interfaces are also encouraged to use `result` +return types with explicit error cases for resource exhaustion where possible, +enabling guests to handle limits gracefully rather than trapping. + ## Embedding A WebAssembly Component Model implementation will typically be *embedded* into @@ -492,7 +517,9 @@ free list in the free elements of `array`. The limit of `2**28` ensures that the high 2 bits of table indices are unset and available for other use in guest code (e.g., for tagging, packed words or -sentinel values). +sentinel values). As described in the [Introduction](#introduction), +implementations may trap at a lower limit than `MAX_LENGTH` based on +implementation-defined resource constraints. #### Resource State