> ## Documentation Index
> Fetch the complete documentation index at: https://docs.musterbox.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={"dark"}
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](/resources/compatibility) page and the
   [changelog](/resources/compatibility#changelog) delta between your current
   and target versions.
2. Verify the target artifact (see [Package & install](/guides/package-and-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:
   ```bash theme={"dark"}
   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](/guides/faq).