Repository navigation
Adding a note to WIT.md about WIT interface version interop & host downgrades #609
Description
Hey all,
So thinking about interfaces in WIT it seems clear that there are two somewhat surprising eventualities that happen in hosts today (wasmtime, jco at the very least):
- Linked interfaces may be downgraded to match what is in the host (i.e.
ns:pkg/iface@0.2.1being downgraded tons:pkg/iface@0.2.0) - Partly due to (1) but in general adding functions to an existing interface (even with
@since) could become a breaking change, because guests cannot predict whether hosts will have coverage or not.
This should likely be called out more clearly in WIT.md, similar to how it is called out explicitly in wasmtime's Linker documentation -- thoughts?
The ideal is to prevent people from being surprised when building components that target the newest version of a given interface but running in an older host/embedding and experiencing an unexpected runtime failure.
Downgrading is a host-specific quirk, and is technically not promised/required by a given platform (no guest can ensure that a certain platform does a certain thing with it's imports), but it is still surprising behavior that should probably be noted somewhere.
Activity
lukewagner commentedon Feb 11, 2026
Improving the WIT.md documentation makes sense. One thing to note though is that, as of #536, the observed "downgrading" behavior is actually part of the CM semantics, as described here. In particular, because we "chop off" the non-major fields of the import/export version in import/export names, and this name is the "key" when looking up imports in the host, the desirable "new interface versions work on old hosts if you're not using the new functionality" behavior just falls out without the host having to do special semver logic (as was the case before Canonical Interface Names).
vados-cosmonic commentedon Feb 11, 2026
Ah thanks for the pointer @lukewagner -- that being already part of the CM is something I didn't find -- that sentence:
(to be clear I looked mostly at WIT.md and wasmtime::Linker docs, should have also checked the CM, but was pretty sure it was a host quirk!)
Maybe spacing out that section just a tiny bit so that the the guest-older-than-host and guest-newer-than-host examples are a bit easier to tease out. A bit of a "semantic line breaks" situation maybe.
That said, what I'm thinking is a small section in WIT.md next to the semver discussion that is already there, addressing this specifically. Maybe also a link to the CM semantics wouldn't hurt either.
@MendyBerger was instrumental in bringing up how potentially confusing/surprising this was -- Mendy do you want to take a stab at it?