Contracts first
Every published surface on the platform is defined by its contract before it is implemented: HTTP APIs in OpenAPI specifications, service-to-service interfaces in protocol-buffer definitions. The specification is the source of truth — SDKs are generated from it, and implementation code must prove it matches. This is the foundation every versioning rule below stands on: a version is a promise about a document, and the document exists before the promise.
Drift is a build failure
If an implementation diverges from its published contract, continuous integration fails — for the producer and for generated consumers. There is no "the docs were stale" state to discover in production: the contract, the server, and the client are checked against each other on every change. Symmetric validation means a breaking change cannot ship quietly on either side of the wire.
Additive change only
The compatibility rule for existing consumers is simple: nothing they rely on changes meaning.
- New fields, endpoints, and event types arrive as additions; existing ones keep their names, types, and semantics.
- Database migrations are additive; destructive production migrations are a forbidden pattern, not a risky one.
- New behavior ships behind feature flags and activates deliberately — multi-version preservation is the default, so a consumer can move when ready rather than when pushed.
- Errors are part of the contract: machine-readable codes in stable namespaces (authentication, authorization, tenancy, validation), safe to branch on programmatically.
Public versus internal surfaces
Published SDKs expose explicitly tiered surfaces: the stable public surface, administrative surface for operator tooling, and internal surface that may change without notice — separated at the package boundary, with deep imports past those boundaries blocked. What this means for an integrator: the public surface is the compatibility promise; anything reachable only through internal paths is not covered by it. Integration boundaries turns that into a checklist.
How packages are versioned
Platform packages release on semantic versioning with automated version bumps and changelogs, and consumers pin to registry-published versions. Upgrades arrive as reviewable pull requests on a weekly cadence — not silent, unreviewed bumps. The same discipline applies to HTTP surfaces: behavior changes arrive as new contract revisions consumers adopt explicitly.
The deprecation practice
When a surface must retire, the practice is rename, shim, retire: the outgoing contract is renamed and frozen at its last version under a deprecation marker while the canonical contract continues, so consumers migrate deliberately rather than overnight. Honest boundary: the platform does not today publish a fixed sunset-window SLA for public APIs — when one is adopted, it will be documented on this page before it binds anything. What is guaranteed today is the practice above: no silent removals, no breaking change shipped as a patch.
Boundary
This page is the public compatibility policy. Endpoint-level changelogs, contract documents, and migration tooling ship with authenticated developer access.