Operate and evolveVersions and compatibility

Versions and compatibility

Select coherent package bundles and evolve application contracts across mixed peer versions.

Match the SDK package, binding bundle, behavior defaults, and application contracts before deploying peers. The documentation edition identifies the guidance, not a single version for all those inputs.

Select coherent inputs

IdentityWhat it identifies
SDK versionPublished component package
Binding API versionGenerated client and runtime compatibility boundary
Behavior versionSelected dated defaults for configurable behavior
Schema or Protocol ID versionApplication data or exchange interpretation
Documentation editionImmutable guide and reference output with its provenance

Platform releases use the sdk-v* train. Other components have independent release identities. Do not infer that equal-looking version numbers are a compatible combination.

A generated client and native or Wasm binary ship as a matched bundle. Do not copy new declarations onto an old library to make missing methods appear available. A binding mismatch must fail explicitly instead of calling an incompatible binary.

Choose the correct reference source

A contract edition documents its reviewed complete interface. A release reference documents the exact released package, feature profile, and target. A contract edition is not a historical release label.

The selected package reference defines executable syntax and target coverage.

Record runtime evidence with its actual package, target, features, source identity, command, and output. A schema constructor, event identifier, or callback registration alone does not establish distributed delivery.

Evolve application schemas

Keep existing schema identities immutable. Add versions with explicit predecessors and compatibility rules. Optional additions preserve old-reader behavior only when the exact contract allows them.

Plan migrations for renamed required fields, changed timestamp units, changed merge semantics, or reused type names with new meanings.

Retain unknown operation bytes and forward them as the protocol requires, even if the current application skips their materialized effect. Unknown data must not become silent data loss. Preserve the schema-pending distinction when a definition has not arrived.

Do not assume a human-readable description affects a schema's content identity. Use the selected schema version's canonical identity rules.

Migrate storage without deployment order

Use additive, offline-safe migrations. Give each migration a globally unique version. Never edit an applied migration in place. Cover each supported persistent backend before deployment.

Peers can remain offline on an older version. Design record, event, stream, and protocol changes so independent deployments do not require a synchronized upgrade. Negotiate supported Protocol IDs and reject an unsupported payload schema explicitly.

Check the integration tuple

Before deployment, record package versions, binding bundle, behavior defaults, protocol and schema revisions, storage backend, transport policy, and documentation edition. Exercise a new peer with the previous supported peer version and persisted data.

For browser deployments, memory-only storage remains a target property. For native packages, check the packaged architecture rather than assuming every generated language has a binary for every operating system.