Migrate SDK versions

How SDK, ABI, and protocol versioning works — and how to upgrade safely.

The SDK versioning model is explicit: SDK semver, C ABI, protocol, and config schema each version independently, and mismatches fail fast.

What the versions mean

Version	Current	Value
SDK	1.0.0	SemVer of the Rust core
C ABI	1.2.0	FFI symbol surface (23 exported symbols)
Protocol	1.0	Message/event wire protocol
Config schema	1	musterbox.toml structure

Where they must agree

Integration	Constraint
Native FFI binary	ABI must equal the runtime’s expected ABI
WebAssembly core	ABI reported by sdk-wasm must match sdk-js
Config profile	schema_version must match the loader’s supported schema (1)
Adapter ↔ core	Adapter SDK version should match the packaged core

A mismatch is reported as MismatchedVersion (MBX-SDK-002) — a fast, actionable failure, not a hang.

Check everything from one place:

musterbox sdk version        # SDK 1.0.0 / protocol 1.0 / ABI 1.2.0
musterbox sdk abi-version    # 1.2.0
musterbox config inspect     # schema version + redacted values
musterbox protocol negotiate -l <local> -r <remote>

Upgrade checklist

1. Read the compatibility page and the changelog delta between your current and target versions.
2. Verify the target artifact (see Package & install).
3. Stage the upgrade in sandbox, then staging, then production — never land a version jump straight to production.
4. Run the certification gate in CI:
   musterbox validate --strict --json
   musterbox security audit --json
   musterbox certify --suite all --matrix --json
   
5. Re-run musterbox sdk smoke-test to prove the local lifecycle.
6. Update your vendored artifact pin and the SDK version reported in your own diagnostics.

Distribution status note

SDK packages are currently distributed as local tarballs in dist/; publication to npm (@musterbox/sdk-*) and crates.io is not yet live. Migrating between versions therefore means changing your vendored pin — do not mix artifacts from different dist/ snapshots.

Next: FAQ.