Release and API Stability

Stability claims are tied to release evidence, not intent.

cxxmcp treats API compatibility, protocol support, package-smoke evidence, and release-gate artifacts as one release decision.

Canonical SDK Surface

New application code should use Peer and Service over public headers under cxxmcp/... and public CMake targets.

Stable SDK targets

cxxmcp::protocol, cxxmcp::transport, cxxmcp::handler, cxxmcp::peer, cxxmcp::service, cxxmcp::client, cxxmcp::server, and cxxmcp::sdk.

Outside the core contract

Gateway/runtime/CLI/plugin tooling is released outside this SDK repository and does not define the core contract.

The package, repository, installed include path, and CMake target prefix use cxxmcp. The C++ namespace is intentionally mcp and is part of the stable source API; changing it is a breaking rename, not a cosmetic cleanup.

Source Compatibility

Public SDK headers compile as C++17 by default. Once a stable release line is declared, source compatibility follows semantic versioning: minor releases add compatible APIs, patch releases fix behavior or packaging, and source-breaking removals wait for a major release.

Public renames are expected to be additive first: add the new spelling, keep the old spelling as an alias or forwarding wrapper, mark it deprecated where possible, document the migration, and remove it only in the next major release.

ABI Policy

cxxmcp builds and releases static libraries by default. ABI stability is not claimed for static-library releases. If shared libraries become stable release artifacts later, they need a separate ABI policy before ABI compatibility is advertised.

Protocol Compatibility

cxxmcp follows published MCP protocol snapshots. It does not mint custom MCP protocol versions or alternate wire formats. Unsupported protocol versions fail fast with protocol or transport validation errors instead of silently downgrading to an unadvertised dialect.

Release Evidence

A release may claim support only for matrix entries where the release-blocking gates passed for that exact commit. The intended public matrix covers Windows/MSVC, Linux/GCC, Linux/Clang, and macOS/AppleClang with the documented generator and runtime-library combinations.

  • Release-blocking CTest, JUnit, and log evidence for advertised matrix legs.
  • Installed-package package_smoke evidence.
  • Independent public-header compile evidence.
  • RMCP, TypeScript SDK, and Python SDK interoperability evidence where advertised.
  • Generated public API documentation, source archive, checksums, and release evidence bundle.

Ecosystem Evidence

Fact-standard or curated-registry claims require evidence beyond this repository. Project-owned examples are useful smoke tests, but they do not count as independent public downstream adoption. docs/adoption_ledger.md records the current adoption evidence and must stay conservative until real external users can be cited.

Stage Rules

Alpha and beta

Alpha may move APIs with changelog visibility. Beta APIs should be mostly settled, and breaking changes need migration text.

RC and stable

RC is for fixes and release evidence. Stable freezes public source compatibility for the minor line except for unavoidable security or protocol compliance fixes.