Compatibility model

mujoco-wasm-forge treats each MuJoCo version/ref as a separate, versioned output under dist/<ver>/.

What “compatibility” means here

When upgrading MuJoCo, you should expect changes in:

• header declarations (introspection output),

• available implementations (symbol inventory),

• wrapper surface (mjwf_* exports),

• performance/size characteristics (quality gates).

The “compatibility promise” is not that MuJoCo never changes, but that changes are:

• detectable (gates fail or report drift),

• reviewable (audit artifacts in dist/<ver>/abi/),

• actionable (you can update wrappers/exports with a clear diff).

How upgrades are validated

Recommended flow:

1. Build the new ref: python3 forge_cli.py build --version <new> --with-checks.

2. Review dist/<new>/abi/exports.lst and the reports under dist/<new>/abi/.

3. Run the checks in “enforced” mode when needed (see reference_env_vars and reference_checks_gates).

Common failure categories:

• Build/toolchain: Emscripten/Node/clang is missing or incompatible.

• ABI/export drift: a required wrapper export disappeared or changed.

• Runtime regression: smoke tests fail to compile/step a minimal model.

• Quality regressions: check/tests/gates.mjs reports size/init-time breaches.