SDK versioning and pinning

The SDK and the wire protocol share one version, exported as SDK_VERSION and matched by the package version. Your app sends it on every handshake, so the shell can reason about compatibility with the app it just loaded.

The compatibility guarantee

The SDK follows semantic versioning, with one protocol-specific promise:

The wire protocol is backwards-compatible within a major version.

So any 1.x app speaks to any 1.y shell. Minor releases add capabilities; patch releases fix behavior. Neither breaks the handshake. A major bump is where the protocol can change, and that is the only upgrade you should treat as a migration.

How to pin

Pin to a caret range within a major:

{ "dependencies": { "@platform/sdk": "^1.0.0" } }

You get compatible minors and patches automatically, and a major bump is an explicit, deliberate change to your package.json. Run your typecheck after any bump: because the SDK is strict TypeScript, a removed or renamed API becomes a compile error at the call site.

Why there are no per-version docs

This site documents the latest SDK only. Rather than freezing a copy of the docs per version — which means maintaining, and back-patching, several frozen sites — breaking changes are communicated two ways:

• the CHANGELOG.md shipped with the package, and
• the upgrade guide, which walks the changes that need real work.

That pairing does the job a versioned docs site would, without the cost. When a future release removes or changes public API, start with the upgrade guide.

Keeping the two versions honest

Because the package version and SDK_VERSION are both surfaced to you (one in npm info, the other in the handshake and anywhere your app shows it), they must agree. The SDK’s own CI fails if they ever drift, so “you are on version x” is always a true statement.