Versioning

Artefact	Version carrier	Compatible change (minor)	Breaking (major)
Contract repo	git tag vX.Y.Z (CHANGELOG per artefact)	any artefact minor	any artefact major
REST	path /api/v1, info.version	new endpoints, optional fields, new enum values, new error codes	removal / rename / type change / new required input
GraphQL	schema version in info.apiVersions, @deprecated	additive fields / types	as REST
WS / socket.io	sub-protocol freedome.v1 / namespace /v1	new message types / kinds / topics	envelope change
OSC	prefix /freedome/v1	new addresses / optional trailing args	arg type / order change
Schemas / formats	$id <major.minor>, file formatVersion	new optional fields	format rules (readers reject unknown major, accept newer minor, keep x-*)

• Enums are open; clients must tolerate unknown fields, enum values, event kinds and topics.
• Deprecation: OpenAPI deprecated: true + response headers Deprecation (RFC 9745) and Sunset (RFC 8594) + Link rel="deprecation"; GraphQL @deprecated(reason); AsyncAPI deprecated; OSC aliases listed in osc/legacy.yaml with sunset dates.
• Support window: the server serves the current and the previous major; a major is supported for ≥ 12 months after its successor’s GA. The legacy profile lives for the whole v1 lifetime and is removed in v2; /api/v1/info.legacyProfile and Manager warn about clients still using it.
• SDK packages follow the contract major (freedome_protocol 1.x ⇔ API v1).

Repository practice

• make breaking compares the working tree with the last v* tag of the same major (oasdiff breaking, graphql-inspector diff); it is a no-op until the first tag exists.
• Schema $ids are identifiers, not locations: once a version is published its $id never changes; a new minor gets a new <major.minor> folder.
• Every change is recorded in CHANGELOG.md under the artefact it touches.