Rec group builder

[somdoron]

Implements the embedder API requested in issue #10176.

Embedders can currently only build one-off struct/array/func types, so types that reference
themselves or each other can't be constructed directly. This adds RecGroupBuilder: declare
kind-typed labels, use them as forward references, and build() the whole recursion group at
once. It lowers to module-canonical WasmSubTypes and reuses the existing rec-group
registration path.

Also fixes an unrelated pre-existing bug in StorageType::is_val_type (matched I16 instead of
ValType), in its own commit.

[fitzgen]

@somdoron given that you just posted an AI plan verbatim in this PR's associated issue, I am assuming you also used AI to implement this PR. Can you confirm that you have already reviewed the AI tool's work in detail before posting it here and asking reviewers to spend their time on it? And are you taking full responsibility for the code in this PR?

https://github.com/bytecodealliance/governance/blob/main/AI_TOOL_POLICY.md

[somdoron]

@fitzgen I confirmed that I reviewed the AI tool. I reviewed the code, and I'm taking full responsibility for the code in this PR. The PR is for a real problem I'm suffering from, and is focused and small.

[github-actions]

Subscribe to Label Action

cc @fitzgen

Details

This issue or pull request has been labeled: "wasm-proposal:gc", "wasmtime:api", "wasmtime:docs"

Thus the following users have been cc'd because of the following labels:

• fitzgen: wasm-proposal:gc

To subscribe or unsubscribe from this label, edit the .github/subscribe-to-label.json configuration file.

Learn more.

[fitzgen]

First of all, I want to say that this feature is going to involve a lot of API design, and probably won't land super quickly because of that. If you really need to be able to define rec groups in the host now, you can do that via building Modules (either via WAT strings or via wasm_encoder) that define the rec groups you need and export a global of each of the rec groups types so you can exfiltrate the GlobalType and the global type's ValType on the host via Module::exports. So that should unblock you for the time being, if necessary.

Some high-level thoughts on the design:

• I don't think we need to distinguish between pending structs versus pending arrays at the type level. I don't think it is buying us much in terms of correctness by construction or whatever, but it makes ramping up on the API that much harder.

• I don't love adding FieldTemplate/HeapTypeTemplate/etc... types to Wasmtime's public API. I think we could avoid that (and also not force callers to construct slices of them, potentially allocating when they otherwise wouldn't) by having a struct type builder that borrows the rec group builder and exposes a method to define fields one at a time, something like this:

  impl RecGroupBuilder<'_> {
      pub fn define_struct(&mut self, ty: PendingType) -> StructTypeBuilder<'_> { ... }
  }
  
  pub struct StructTypeBuilder<'a> {
      rec_group: &'a mut RecGroupBuilder,
      // ...
  }
  
  impl StructTypeBuilder<'_> {
      /// Define a normal, non-forward-reference field.
      pub fn field(&mut self, ty: FieldType) { ... }
  
      /// Define a field that is a forward reference to another type defined in this rec group.
      pub fn forward_ref_field(&mut self, ty: PendingType) -> ForwardRefFieldBuilder<'_> { ... }
  }
  
  pub struct ForwardRefFieldBuilder<'a> {
      parent: StructOrArrayTypeBuilder<'a>,
      // ...
  }
  
  impl ForwardRefFieldBuilder<'_> {
      pub fn nullable(&mut self, nullable: bool) -> &mut Self { ... }
  
      pub fn shared(&mut self, shared: bool) -> &mut Self { ... }
  
      pub fn finish(self) -> &mut StructTypeBuilder<'_> { ... }
  }