feat: add future.forward canon builtin

Implement parsing, validation, encoding, and printing support for the
⏩-gated `future.forward` built-in proposed in
WebAssembly/component-model#658:

    (canon future.forward $futureT (core func $f))

where `$f` has type `(func (param i32 i32))`, taking a readable future
end and a writable future end.  Exactly like its `stream.forward`
counterpart, `future.forward` transfers both ends out of the calling
instance and returns immediately with no result, so it takes neither
an `async` immediate nor any `canonopt`s, since the value does not
pass through the caller's linear memory.

The binary encoding uses opcode 0x2e as assigned in the proposed
specification change, and validation gates the built-in behind the
component model async and "more async builtins" features.

Assisted-by: claude:claude-fable-5

Author: rvolosatovs

crates/wasm-encoder/src/component/builder.rs

@@ -612,6 +612,12 @@ impl ComponentBuilder {
         self.core_funcs.add(Some("future.write"))
     }
 
+    /// Declares a new `future.forward` intrinsic.
+    pub fn future_forward(&mut self, ty: u32) -> u32 {
+        self.canonical_functions().future_forward(ty);
+        self.core_funcs.add(Some("future.forward"))
+    }
+
     /// Declares a new `future.cancel-read` intrinsic.
     pub fn future_cancel_read(&mut self, ty: u32, async_: bool) -> u32 {
         self.canonical_functions().future_cancel_read(ty, async_);

crates/wasm-encoder/src/component/canonicals.rs

@@ -381,6 +381,16 @@ impl CanonicalFunctionSection {
         self
     }
 
+    /// Defines a function to forward the value of the readable end of one
+    /// `future` to the writable end of another `future` of the specified
+    /// type, transferring both ends out of the calling instance.
+    pub fn future_forward(&mut self, ty: u32) -> &mut Self {
+        self.bytes.push(0x2f);
+        ty.encode(&mut self.bytes);
+        self.num_added += 1;
+        self
+    }
+
     /// Defines a function to cancel an in-progress read from a `future` of the
     /// specified type.
     pub fn future_cancel_read(&mut self, ty: u32, async_: bool) -> &mut Self {

crates/wasm-encoder/src/reencode/component.rs

@@ -1062,6 +1062,9 @@ pub mod component_utils {
                     .collect::<Result<Vec<_>, _>>()?;
                 section.future_write(reencoder.component_type_index(ty), options);
             }
+            wasmparser::CanonicalFunction::FutureForward { ty } => {
+                section.future_forward(reencoder.component_type_index(ty));
+            }
             wasmparser::CanonicalFunction::FutureCancelRead { ty, async_ } => {
                 section.future_cancel_read(reencoder.component_type_index(ty), async_);
             }

crates/wasmparser/src/readers/component/canonicals.rs

@@ -218,6 +218,17 @@ pub enum CanonicalFunction {
         /// memory.
         options: Box<[CanonicalOption]>,
     },
+    /// A function to forward the value of the readable end of one `future`
+    /// to the writable end of another `future` of the same specified type,
+    /// transferring both ends out of the calling instance.
+    ///
+    /// 🚧 This is an experimental builtin sketched in
+    /// <https://github.com/WebAssembly/component-model/issues/658> and not yet
+    /// part of the Component Model specification.
+    FutureForward {
+        /// The `future` type to expect.
+        ty: u32,
+    },
     /// A function to cancel an in-progress read from a `future` of the
     /// specified type.
     FutureCancelRead {
@@ -402,6 +413,7 @@ impl<'a> FromReader<'a> for CanonicalFunction {
                 ty: reader.read()?,
                 options: read_opts(reader)?,
             },
+            0x2f => CanonicalFunction::FutureForward { ty: reader.read()? },
             0x18 => CanonicalFunction::FutureCancelRead {
                 ty: reader.read()?,
                 async_: reader.read()?,

crates/wasmparser/src/validator/component.rs

@@ -1262,6 +1262,7 @@ impl ComponentState {
             CanonicalFunction::FutureWrite { ty, options } => {
                 self.future_write(ty, &options, types, offset)
             }
+            CanonicalFunction::FutureForward { ty } => self.future_forward(ty, types, offset),
             CanonicalFunction::FutureCancelRead { ty, async_ } => {
                 self.future_cancel_read(ty, async_, types, offset)
             }
@@ -1940,6 +1941,28 @@ impl ComponentState {
         Ok(())
     }
 
+    fn future_forward(&mut self, ty: u32, types: &mut TypeAlloc, offset: u64) -> Result<()> {
+        require_feature::cm_async(
+            self.features,
+            "`future.forward` requires the component model async feature",
+            offset,
+        )?;
+        require_feature::cm_more_async_builtins(
+            self.features,
+            "`future.forward` requires the component model more async builtins feature",
+            offset,
+        )?;
+
+        let ty = self.defined_type_at(ty, offset)?;
+        let ComponentDefinedType::Future { .. } = &types[ty] else {
+            bail!(offset, "`future.forward` requires a future type")
+        };
+
+        self.core_funcs
+            .push(types.intern_func_type(FuncType::new([ValType::I32; 2], []), offset));
+        Ok(())
+    }
+
     fn future_cancel_read(
         &mut self,
         ty: u32,

crates/wasmprinter/src/component.rs

@@ -1098,6 +1098,11 @@ impl Printer<'_, '_> {
                         me.print_canonical_options(state, &options)
                     })?;
                 }
+                CanonicalFunction::FutureForward { ty } => {
+                    self.print_intrinsic(state, "canon future.forward ", &|me, state| {
+                        me.print_idx(&state.component.type_names, ty)
+                    })?;
+                }
                 CanonicalFunction::FutureCancelRead { ty, async_ } => {
                     self.print_intrinsic(state, "canon future.cancel-read ", &|me, state| {
                         me.print_idx(&state.component.type_names, ty)?;

crates/wast/src/component/binary.rs

@@ -454,6 +454,10 @@ impl<'a> Encoder<'a> {
                     self.funcs
                         .future_write((&info.ty).into(), info.opts.iter().map(Into::into));
                 }
+                CoreFuncKind::FutureForward(info) => {
+                    self.core_func_names.push(name);
+                    self.funcs.future_forward((&info.ty).into());
+                }
                 CoreFuncKind::FutureCancelRead(info) => {
                     self.core_func_names.push(name);
                     self.funcs

crates/wast/src/component/func.rs

@@ -73,6 +73,7 @@ pub enum CoreFuncKind<'a> {
     FutureNew(CanonFutureNew<'a>),
     FutureRead(CanonFutureRead<'a>),
     FutureWrite(CanonFutureWrite<'a>),
+    FutureForward(CanonFutureForward<'a>),
     FutureCancelRead(CanonFutureCancelRead<'a>),
     FutureCancelWrite(CanonFutureCancelWrite<'a>),
     FutureDropReadable(CanonFutureDropReadable<'a>),
@@ -174,6 +175,8 @@ impl<'a> CoreFuncKind<'a> {
             Ok(CoreFuncKind::FutureRead(parser.parse()?))
         } else if l.peek::<kw::future_write>()? {
             Ok(CoreFuncKind::FutureWrite(parser.parse()?))
+        } else if l.peek::<kw::future_forward>()? {
+            Ok(CoreFuncKind::FutureForward(parser.parse()?))
         } else if l.peek::<kw::future_cancel_read>()? {
             Ok(CoreFuncKind::FutureCancelRead(parser.parse()?))
         } else if l.peek::<kw::future_cancel_write>()? {
@@ -873,6 +876,23 @@ impl<'a> Parse<'a> for CanonFutureWrite<'a> {
     }
 }
 
+/// Information relating to the `future.forward` intrinsic.
+#[derive(Debug)]
+pub struct CanonFutureForward<'a> {
+    /// The future type to forward.
+    pub ty: ItemRef<'a, kw::r#type>,
+}
+
+impl<'a> Parse<'a> for CanonFutureForward<'a> {
+    fn parse(parser: Parser<'a>) -> Result<Self> {
+        parser.parse::<kw::future_forward>()?;
+
+        Ok(Self {
+            ty: parser.parse::<IndexOrRef<'_, _>>()?.0,
+        })
+    }
+}
+
 /// Information relating to the `future.cancel-read` intrinsic.
 #[derive(Debug)]
 pub struct CanonFutureCancelRead<'a> {

crates/wast/src/component/resolve.rs

@@ -446,6 +446,9 @@ impl<'a> Resolver<'a> {
                     self.component_item_ref(&mut info.ty)?;
                     self.canon_opts(&mut info.opts)?;
                 }
+                CoreFuncKind::FutureForward(info) => {
+                    self.component_item_ref(&mut info.ty)?;
+                }
                 CoreFuncKind::FutureCancelRead(info) => {
                     self.component_item_ref(&mut info.ty)?;
                 }

crates/wast/src/lib.rs

@@ -583,6 +583,7 @@ pub mod kw {
     custom_keyword!(future_new = "future.new");
     custom_keyword!(future_read = "future.read");
     custom_keyword!(future_write = "future.write");
+    custom_keyword!(future_forward = "future.forward");
     custom_keyword!(future_cancel_read = "future.cancel-read");
     custom_keyword!(future_cancel_write = "future.cancel-write");
     custom_keyword!(future_drop_readable = "future.drop-readable");