Versioning
Dynoxide has two version numbers, and they are different on purpose.
The product version covers everything you install: the dynoxide CLI and its platform binaries, the npm packages, the browser engine, the container images, the GitHub Action and the Homebrew formula. dynoxide --version reports it, and so do the x-dynoxide-version and Server headers and the MCP server info.
The crate version covers dynoxide-rs on crates.io, and nothing else.
They were one number until 1.1.0. The split happened because a change to a public Rust type would otherwise have forced a major version on every artefact whose users never touch the Rust API, and moving everyone to ^2.x and dynoxide:2 to report a change they cannot observe is a poor trade.
Right now that means product 1.3.0, crate 3.0.0.
Which number do I want?
| If you are | Use |
|---|---|
Running npx dynoxide, Docker, Homebrew or the GitHub Action |
Product version |
Reading dynoxide --version output, or filing a bug report |
Product version |
Adding dynoxide-rs to a Cargo.toml |
Crate version |
Running cargo install dynoxide-rs --version X |
Crate version |
cargo install dynoxide-rs --version 1.3.0 will not find anything, because 1.3.0 is a product version. The Embedded SDK page renders its pin from crates.io, so copy it from there.
What moves which
A release can move one stream and leave the other alone. A Rust-only break publishes a new crate against an unchanged product; a CLI-only change publishes a new product against an unchanged crate.
| Change | Stream | Bump |
|---|---|---|
| Breaking change to a public Rust type or signature | Crate | major |
| Public Rust type or function added | Crate | minor |
| New feature flag, or an MSRV raise | Crate | minor |
| CLI flag removed or renamed | Product | major |
| HTTP response shape or error string change | Product | major |
| Container entrypoint or exposed port change | Product | major |
| Startup line text, or the stream it goes to | Product | major |
| Engine behaviour change | Both | major, unless it is a capture-backed conformance fix |
| Capture-backed conformance fix | Both | minor |
| Browser client API or Worker protocol change | Product | major |
| New DynamoDB operation | Both | minor |
The MCP surface carries no version promise of its own. The data model is context for an agent rather than something the engine enforces, so serverInfo.version reports the product version, which is what you installed.
Upgrading to product 1.3.0 and crate 3.0.0
The crate takes a major because public Rust parsers become private and request types and a capacity signature change. The product takes a minor under the capture-backed conformance rule. A test that relied on an older divergence can still fail after a minor update; semver doesn't freeze the emulator's answers.
Read the crate migration guide before updating a Rust dependency. Product 1.3.0 upgrades files to schema 11. Keep a copy before upgrading if your file has a multi-attribute GSI or a vector index and you may return to 1.2.x. Files without either still read correctly in 1.2.x. The storage guide covers native, encrypted and browser databases.
To hold behaviour across minor releases, use a patch-only npm range such as ~1.3.0, a container minor tag such as dynoxide:1.3, or an exact crate version and your Cargo lockfile. These are pinning examples for the 1.3.0 release, rather than the site's current registry versions.
Prereleases
Prereleases reach only the channels that name them. npm publishes them to next; GitHub flags the release as a prerelease; containers get the exact tag. The GitHub Action's default latest, Homebrew and the MCP registry stay on the stable release. A stable crate version waits for the stable product release before it is published.
This site reads npm's latest and crates.io's stable version. A prerelease should not move the install pins or be presented as the latest stable release.
For the full rules, including how each contract is defined, see docs/versioning.md in the engine repository.