Add `(implements "I")` to plainname imports to allow multiple imports by ricochet · Pull Request #613 · WebAssembly/component-model

ricochet · 2026-02-25T15:06:05Z

Add (implements "I") annotation to be added to plainname imports which enables multiple imports of the same interface

Extend the WIT extern-type grammar to allow use-path as a third case,
enabling import id: use-path and export id: use-path to create
plain-named imports/exports whose instance type matches a named interface.

This allows importing the same interface multiple times under different
plain names (e.g., import primary: store; import secondary: store;),
encoded using the (implements "...") annotation pattern.

Fixes #287

lukewagner

Awesome, thanks for writing this up! The PR looks great; just minor nits. I think what'll be important for this change is seeing how it "plays out" in the producer and consumer tooling, so I think we'll want to keep this PR open until we get some experience from tool implementations, but so far so good from my perspective.

Add parsing, validation, and uniqueness rules for the new `[implements=<interface>]label` extern name form from the component model `implements` proposal. An implements name labels an instance import/export that implements a named interface. Uniqueness: `[implements=]L` conflicts with bare label `L` and with `[method]L.L` / `[static]L.L` (the existing l.l edge case), but is strongly unique from interface names, constructors, and normal method/static names. See implements feature: WebAssembly/component-model#613

Extend the WIT `extern-type` grammar to allow `use-path` as a third case, enabling `import id: use-path` and `export id: use-path` to create plain-named imports/exports whose instance type matches a named interface. This allows importing the same interface multiple times under different plain names (e.g., `import primary: store; import secondary: store;`), encoded using the `[implements=<interfacename>]label` annotation pattern. Fixes #287 Co-authored-by: Luke Wagner <mail@lukewagner.name>

DO NOT MERGE until wasm-tools release with bytecodealliance/wasm-tools#2453 Points wasm-tools to PR branch `wasmparser-implements` Add support for the component model `[implements=]L` (spec PR [bytecodealliance#613](WebAssembly/component-model#613)), which allows components to import/export the same interface multiple times under different plain names. A component can import the same interface twice under different labels, each bound to a distinct host implementation: ```wit import primary: wasi:keyvalue/store; import secondary: wasi:keyvalue/store; ``` Guest code sees two separate namespaces with identical shapes: ```rust let val = primary::get("my-key"); // calls the primary store let val = secondary::get("my-key"); // calls the secondary store ``` From the host, wit-bindgen generates a separate Host trait per label: ```rust impl primary::Host for MyState { fn get(&mut self, key: String) -> String { self.primary_db.get(&key).cloned().unwrap_or_default() } } impl secondary::Host for MyState { fn get(&mut self, key: String) -> String { self.secondary_db.get(&key).cloned().unwrap_or_default() } } primary::add_to_linker(&mut linker, |state| state)?; secondary::add_to_linker(&mut linker, |state| state)?; ``` The linker also supports registering by plain label without knowing the annotation: ```rust // Component imports [implements=<wasi:keyvalue/store>]primary // but the host just registers "primary" — label fallback handles it linker.root().instance("primary")?.func_wrap("get", /* ... */)?; ``` Users can also register to the linker with the full encoded `implements` name ```rust let mut linker = Linker::<()>::new(engine); linker .root() .instance("[implements=<wasi:keyvalue/store>]primary")? .func_wrap("get", |_, (key,): (String,)| Ok((String::new(),)))?; ``` Semver matching works inside the implements annotation, just like regular interface imports: ```rust // Host provides v1.0.1 linker .root() .instance("[implements=<wasi:keyvalue/store@1.0.1>]primary")? .func_wrap("get", |_, (key,): (String,)| Ok((String::new(),)))?; // Component requests v1.0.0, matches via semver let component = Component::new(&engine, r#"(component (type $store (instance (export "get" (func (param "key" string) (result string))) )) (import "[implements=<wasi:keyvalue/store@1.0.0>]primary" (instance (type $store))) )"#)?; linker.instantiate(&mut store, &component)?; // works, 1.0.1 is semver-compatible with 1.0.0 ``` ## Changes ### Runtime name resolution - Add three-tier lookup in NameMap::get: exact → semver → label fallback - Add implements_label_key() helper for extracting plain labels from `[implements=]L` - Add unit tests for all lookup tiers ### Code generation for multi-import/export - Track first-seen implements imports/exports per `InterfaceId` - Duplicate imports: re-export types via `pub use super::{first}::*`, generate fresh Host trait + add_to_linker - Duplicate exports: same pattern with fresh Guest/GuestIndices, plus regenerate resource wrapper structs to reference the local Guest type - Use `name_world_key_with_item` for export instance name lookups - Guard `populate_world_and_interface_options` with `entry()` to avoid overwriting link options for duplicate interfaces

DO NOT MERGE until wasm-tools release with bytecodealliance/wasm-tools#2453 Points wasm-tools to PR branch `wasmparser-implements` Add support for the component model `[implements=]L` (spec PR [bytecodealliance#613](WebAssembly/component-model#613)), which allows components to import/export the same interface multiple times under different plain names. A component can import the same interface twice under different labels, each bound to a distinct host implementation: ```wit import primary: wasi:keyvalue/store; import secondary: wasi:keyvalue/store; ``` Guest code sees two separate namespaces with identical shapes: ```rust let val = primary::get("my-key"); // calls the primary store let val = secondary::get("my-key"); // calls the secondary store ``` Host Import-side codegen: shared trait + label-parameterized add_to_linker For imports, wit-bindgen generates one Host trait per interface (not per label). The add_to_linker function takes a name: &str parameter so the same trait implementation can be registered under different instance labels. Duplicate implements imports don't generate separate modules — only the first import produces bindings. ```rust struct PrimaryBackend; impl primary::Host for PrimaryBackend { fn get(&mut self, key: String) -> String { self.primary_db.get(&key).cloned().unwrap_or_default() } } struct SecondaryBackend; impl primary::Host for SecondaryBackend { fn get(&mut self, key: String) -> String { self.secondary_db.get(&key).cloned().unwrap_or_default() } } // Same add_to_linker, different labels and host_getter closures primary::add_to_linker(&mut linker, "primary", |s| &mut s.primary)?; primary::add_to_linker(&mut linker, "secondary", |s| &mut s.secondary)?; ``` Export-side codegen: per-label modules with shared types For exports, each label gets its own module with fresh Guest/GuestIndices types but re-exports shared interface types from the first module via `pub use super::{first}::*`. Runtime name resolution The linker supports registering by plain label without knowing the annotation: ```rust // Component imports [implements=<wasi:keyvalue/store>]primary // but the host just registers "primary" — label fallback handles it linker.root().instance("primary")?.func_wrap("get", /* ... */)?; Users can also register to the linker with the full encoded implements name: linker .root() .instance("[implements=<wasi:keyvalue/store>]primary")? .func_wrap("get", |_, (key,): (String,)| Ok((String::new(),)))?; ``` Semver matching works inside the implements annotation, just like regular interface imports: ```rust // Host provides v1.0.1 linker .root() .instance("[implements=<wasi:keyvalue/store@1.0.1>]primary")? .func_wrap("get", |_, (key,): (String,)| Ok((String::new(),)))?; // Component requests v1.0.0, matches via semver let component = Component::new(&engine, r#"(component (type $store (instance (export "get" (func (param "key" string) (result string))) )) (import "[implements=<wasi:keyvalue/store@1.0.0>]primary" (instance (type $store))) )"#)?; linker.instantiate(&mut store, &component)?; // works, 1.0.1 is semver-compatible with 1.0.0 ``` - Add three-tier lookup in NameMap::get: exact → semver → label fallback - Add implements_label_key() helper for extracting plain labels from `[implements=]L` - Add unit tests for all lookup tiers - Track first-seen implements imports per `InterfaceId` - One `Host` trait per interface; `generate_add_to_linker` takes `named: bool` — when true, emits `name: &str` parameter instead of hardcoding the instance name - Duplicate `implements` imports: just record the label in `implements_labels`, no module generation - `world_add_to_linker`: iterate over `implements_labels` to emit one `add_to_linker` call per label, passing label as name argument - Guard `populate_world_and_interface_options` with `entry()` to avoid overwriting link options for duplicate interfaces - Duplicate exports: re-export types via `pub use super::{first}::*`, generate fresh `Guest`/`GuestIndices`, plus regenerate resource wrapper structs to reference the local `Guest` type - Use `name_world_key_with_item` for export instance name lookups

lukewagner

Thanks!

lukewagner · 2026-03-02T16:36:42Z

Oh, I forgot: we probably should have an emoji-gate for this associated with the new rules in the grammar in Explainer.md and the descriptions in WIT.md.

ricochet · 2026-03-03T16:50:50Z

Oh, I forgot: we probably should have an emoji-gate for this associated with the new rules in the grammar in Explainer.md and the descriptions in WIT.md.

Since this is about adding labels, let's use 🏷️ aka the :label: emoji

lukewagner · 2026-03-05T17:16:04Z

+package local:demo;
+
+interface store {
+    get: func(key: string) -> option<string>;


I just realized that there's a pretty nuanced technical design point (that iiuc the current impl is getting getting right atm) that this example should explicate via the generated WAT:

Could you expand this example to include a bucket resource type (returned by an open function, like in the current wasi-keyvalue draft) inside the existing store interface. That should end up with two resource types being imported in the WAT.

Next, after the WAT, could you add a second variation of this example which factors out the bucket type into a types interface (like we do in wasi-http) that is used by the store interface. And this should result in one resource type import that is aliased into the two store imports.

Done now, if you'd like to review

* Use a dedicated `(implements "...")` annotation in the text format and dedicated bytes in the binary format. * Update tests/docs/etc to use the new syntax.

alexcrichton · 2026-05-12T21:48:38Z

Ok I've gone through this PR and updated everything to the best of my ability. This update notably takes into account Luke's previous comment which overhauls how this is encoded in the binary format. I've additionally updated the sibling wasm-tools PR through which I've validated and verified some of the wat and tests here. I've additionally implemented all the various bits of wasm-tools such that fuzzing is now clean and such.

My hope/expectation is that integrating this into bindings generators will be pretty easy, assuming the generate_nominal_type_ids method is used. One of the major features that this exposes, which never came up prior, is importing the same interface multiple times and exporting multiple times. I realize that sounds obvious but for any bindings generator which has been using TypeId or InterfaceId as keys in maps this can wreak havoc without the "nominal" form of a graph. Effectively this, in my opinion at least, really puts a nail in the coffin of bindings generators taking a WIT AST as-is and generating bindings from it. Essentially it's required to post-process into a format more akin to the actual wasm representation (e.g. interfaces are duplicated, as well as types defined in those interfaces). This is all the purpose of generate_nominal_type_ids, which notably got an update for this feature as well.

lukewagner

Looks great, thanks! One minor suggestion:

* [wasmparser] Add `[implements=]L` component name support Add parsing, validation, and uniqueness rules for the new `[implements=<interface>]label` extern name form from the component model `implements` proposal. An implements name labels an instance import/export that implements a named interface. Uniqueness: `[implements=]L` conflicts with bare label `L` and with `[method]L.L` / `[static]L.L` (the existing l.l edge case), but is strongly unique from interface names, constructors, and normal method/static names. See implements feature: WebAssembly/component-model#613 * [wit-parser] Add `implements` syntax for named interface imports/exports Support the `import label: iface;` and `export label: iface;` WIT syntax, which encodes as `[implements=]label` in the binary format. This allows importing or exporting the same interface multiple times under different names. Changes include: - Add `implements: Option<InterfaceId>` field to `WorldItem::Interface` - Parse `NamedPath` variant in the WIT AST with disambiguation against fully-qualified `namespace:package/interface` paths - Decode `[implements=]label` names in all binary decoding paths via a new `decode_world_instance` helper - Thread `implements` through world elaboration and ID remapping - Add `name_world_key_with_item` for binary encoding On the API change for `name_world_key_with_item`, I opted to introduce this new fn that is used only at the few call sites that need it vs updating the ~50 sites for name_world_key. * [wit-component] Add implements encoding support to wit-component Update component encoding to use `name_world_key_with_item` at sites that produce component-level extern names, so that `implements` imports and exports are encoded as `[implements=]L` in the binary format. Five call sites are changed from `name_world_key` to the implements-aware variant: import_map key construction, component export names, ImportedResourceDrop lookups, and both direct and indirect InterfaceFunc lookups. * [wit-dylib] add implements to WorldItem::Interface * [wit-smith] Add implements interface generation Teach wit-smith to generate `ImplementsInterface` items in worlds, producing `%label: path;` WIT syntax which encodes as `[implements=]L` in the component binary. This enables fuzzing of the implements feature through the existing roundtrip_wit fuzzer. * Generate nominal interface/type ids in `wit-component` This commit is a long-overdue change in the componentization process in `wit-component` to ensure that when a component is generated there are unique `TypeId` and `InterfaceId` entries corresponding to all types/interfaces which map to the final component. This is distinct from the structure of WIT where the same `InterfaceId`, for example, can be both imported and exported. When generating a component this means that two distinct interfaces are imported/exported. Previously `wit-component` has had a lot of very carefully filled out and handled maps and such to ensure everything works, and this should make things significantly easier because the possibility over overlap is now nonexistent. * Leverage nominal types/interfaces in encoding This commit builds on the previous commit to simplify internal structures within the encoding process of a component. Notably there's no longer any need to have separate maps for imports/exports and instead everything is located in a single set of maps. Not major changes, but this is hoped to unlock future changes and additionally pave the way to simplifying some internals in the future. * Add `cm-implements` feature Gate the new parsing behind this feature. * Shift where `implements` is in the AST Use a new `WorldKey` instead of `WorldItem`. * Remove hand-rolled parsing * Only write blessed files if they change Helps run-on-file-change tools not infinite loop * Reimplement how `implements` is represented In the component model binary format this is no longer packed into import/export names but is instead an auxiliary piece of metadata on imports/exports. This required quite a few updates to parsing, AST structures, etc, throughout. Additionally within `wit-parser` this is now represented with no AST changes from before. Instead `WorldKey::Name` is used with a `WorldItem::Interface`, and the only difference from the previous "anonymous interfaces" is that the interface pointed to has a name. This is what's used to indicate an `implements` value is desired. Initial plumbing within `wit-component` is done, but tests are not fully passing yet. * Handle `import a: b` in `generate_nominal_type_ids` This commit updates the `generate_nominal_type_ids` to handle the new form of imports that are showing up with the `implements` form. This is going to be necessary for bindings generators to handle this neatly and this is also required for wit-component after bytecodealliance#2516 * Fix recording stability of named interfaces * Fix the order nominalization happens in * Use the 2024 edition for rustfmt in this workspace Possible now that MSRV is high enough * Fix configured build * Reduce the diff with `main` * Improve ergonomics of wasm-encoder * Undo another interim change * More diff minimizing * Add failing test * Don't permute imports/exports Add a test case that broke in Wasmtime, and add a lot of words for why things are the way they are. * Update binary encoding * Review comments --------- Co-authored-by: Alex Crichton <alex@alexcrichton.com>

lukewagner reviewed Feb 26, 2026

View reviewed changes

ricochet mentioned this pull request Feb 27, 2026

Add (implements "...") component name support bytecodealliance/wasm-tools#2453

Merged

ricochet force-pushed the implements branch from 6a391e4 to b6beda9 Compare February 27, 2026 21:37

This was referenced Feb 28, 2026

feat: Add support for implements syntax bytecodealliance/wasmtime#12698

Draft

Add implements clause support to wac bytecodealliance/wac#200

Draft

lukewagner approved these changes Mar 2, 2026

View reviewed changes

Comment thread test/wasm-tools/implements.wast Outdated

Comment thread test/wasm-tools/implements.wast Outdated

lukewagner reviewed Mar 2, 2026

View reviewed changes

Comment thread design/mvp/WIT.md

Add emoji and expand wast for implements

6cddcf6

lukewagner reviewed Mar 5, 2026

View reviewed changes

lukewagner reviewed Mar 9, 2026

View reviewed changes

Comment thread design/mvp/WIT.md

lukewagner reviewed Mar 26, 2026

View reviewed changes

Comment thread design/mvp/Explainer.md Outdated

lukewagner mentioned this pull request Apr 9, 2026

Importing console_log should not break the WebAssembly Compoenent Model #634

Open

vados-cosmonic mentioned this pull request Apr 16, 2026

feat(transpile): support implements bytecodealliance/jco#1290

Closed

Felix-El mentioned this pull request May 4, 2026

Support multiple imports of the same interface with different names #287

Open

alexcrichton added 5 commits May 12, 2026 14:05

Merge remote-tracking branch 'origin/main' into implements

e3fc63f

Update to the latest version of the design

fd4c67b

* Use a dedicated `(implements "...")` annotation in the text format and dedicated bytes in the binary format. * Update tests/docs/etc to use the new syntax.

Clarify disambiguation

7ada4ae

Add more WIT examples

e54f2a5

Add an ambiguity note

b4564cb

alexcrichton changed the title ~~Add [implements=]L plainname for multiple imports~~ Add (implement "I") plainname for multiple imports May 12, 2026

alexcrichton changed the title ~~Add (implement "I") plainname for multiple imports~~ Add (implement "I") to plainname imports to allow multiple imports May 12, 2026

alexcrichton changed the title ~~Add (implement "I") to plainname imports to allow multiple imports~~ Add (implements "I") to plainname imports to allow multiple imports May 12, 2026

lukewagner approved these changes May 13, 2026

View reviewed changes

Comment thread design/mvp/Binary.md Outdated

Adjust binary encoding

3cdb1f7

Conversation

ricochet commented Feb 25, 2026 • edited by alexcrichton Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lukewagner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lukewagner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

lukewagner commented Mar 2, 2026

Uh oh!

Uh oh!

ricochet commented Mar 3, 2026

Uh oh!

lukewagner Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

alexcrichton May 12, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

alexcrichton commented May 12, 2026

Uh oh!

lukewagner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ricochet commented Feb 25, 2026 •

edited by alexcrichton

Loading