doc(wasip2): note implementation limits may trap

proposals/clocks/wit/monotonic-clock.wit

@@ -41,13 +41,23 @@ interface monotonic-clock {
 
     /// Create a `pollable` which will resolve once the specified instant
     /// has occurred.
+    ///
+    /// Each call creates a new resource handle in the component's handle
+    /// table. Implementations may trap if the handle table is full. Guests
+    /// should drop `pollable` handles promptly after use and avoid creating
+    /// unbounded numbers of subscriptions.
     @since(version = 0.2.0)
     subscribe-instant: func(
         when: instant,
     ) -> pollable;
 
     /// Create a `pollable` that will resolve after the specified duration has
     /// elapsed from the time this function is invoked.
+    ///
+    /// Each call creates a new resource handle in the component's handle
+    /// table. Implementations may trap if the handle table is full. Guests
+    /// should drop `pollable` handles promptly after use and avoid creating
+    /// unbounded numbers of subscriptions.
     @since(version = 0.2.0)
     subscribe-duration: func(
         when: duration,

proposals/filesystem/wit/types.wit

@@ -407,6 +407,9 @@ interface types {
         ///
         /// In the future, this may change to return a `stream<u8, error-code>`.
         ///
+        /// Implementations may trap if `length` exceeds an
+        /// implementation-defined limit.
+        ///
         /// Note: This is similar to `pread` in POSIX.
         @since(version = 0.2.0)
         read: func(
@@ -424,6 +427,9 @@ interface types {
         ///
         /// In the future, this may change to take a `stream<u8, error-code>`.
         ///
+        /// Implementations may trap if the buffer size exceeds an
+        /// implementation-defined limit.
+        ///
         /// Note: This is similar to `pwrite` in POSIX.
         @since(version = 0.2.0)
         write: func(

proposals/http/wit/types.wit

@@ -122,6 +122,9 @@ interface types {
 
   /// This type enumerates the different kinds of errors that may occur when
   /// setting or appending to a `fields` resource.
+  ///
+  /// Note: Implementations may also trap when an operation would cause the
+  /// `fields` to exceed an implementation-defined size limit.
   @since(version = 0.2.0)
   variant header-error {
     /// This error indicates that a `field-name` or `field-value` was
@@ -149,9 +152,9 @@ interface types {
   ///
   /// Field keys should always be treated as case insensitive by the `fields`
   /// resource for the purposes of equality checking.
-  /// 
+  ///
   /// # Deprecation
-  /// 
+  ///
   /// This type has been deprecated in favor of the `field-name` type.
   @since(version = 0.2.0)
   @deprecated(version = 0.2.2)
@@ -173,6 +176,10 @@ interface types {
   /// `incoming-request.headers`, `outgoing-request.headers`) might be
   /// immutable. In an immutable fields, the `set`, `append`, and `delete`
   /// operations will fail with `header-error.immutable`.
+  ///
+  /// Implementations may impose limits on individual field values and on the
+  /// total aggregate field section size. Operations that would exceed these
+  /// limits may trap.
   @since(version = 0.2.0)
   resource fields {
 
@@ -195,6 +202,9 @@ interface types {
     ///
     /// An error result will be returned if any `field-name` or `field-value` is
     /// syntactically invalid, or if a field is forbidden.
+    ///
+    /// Implementations may trap if the entries would exceed an
+    /// implementation-defined size limit.
     @since(version = 0.2.0)
     from-list: static func(
       entries: list<tuple<field-name,field-value>>
@@ -219,6 +229,9 @@ interface types {
     ///
     /// Fails with `header-error.invalid-syntax` if the `field-name` or any of
     /// the `field-value`s are syntactically invalid.
+    ///
+    /// Implementations may trap if the name or values would exceed an
+    /// implementation-defined size limit.
     @since(version = 0.2.0)
     set: func(name: field-name, value: list<field-value>) -> result<_, header-error>;
 
@@ -239,6 +252,9 @@ interface types {
     ///
     /// Fails with `header-error.invalid-syntax` if the `field-name` or
     /// `field-value` are syntactically invalid.
+    ///
+    /// Implementations may trap if the value would exceed an
+    /// implementation-defined size limit.
     @since(version = 0.2.0)
     append: func(name: field-name, value: field-value) -> result<_, header-error>;
 

proposals/random/wit/insecure.wit

@@ -13,6 +13,10 @@ interface insecure {
     /// There are no requirements on the values of the returned bytes, however
     /// implementations are encouraged to return evenly distributed values with
     /// a long period.
+    ///
+    /// Implementations may trap if `len` exceeds an implementation-defined
+    /// limit. Guests requiring more bytes should call this function multiple
+    /// times.
     @since(version = 0.2.0)
     get-insecure-random-bytes: func(len: u64) -> list<u8>;
 

proposals/random/wit/random.wit

@@ -17,6 +17,9 @@ interface random {
     /// This function must always return fresh data. Deterministic environments
     /// must omit this function, rather than implementing it with deterministic
     /// data.
+    ///
+    /// Implementations may trap if `len` exceeds an implementation-defined
+    /// limit.
     @since(version = 0.2.0)
     get-random-bytes: func(len: u64) -> list<u8>;