# Versioning and compatibility
This document is a promise rather than a description. A compatibility policy
written after the first release is worth very little — by then the interesting
questions have already been answered by accident — so this was written before
anything was published, and it states what a version number will mean, what
counts as a breaking change, and what deliberately does not.
Three surfaces are covered, because reef-core has three: the Rust API, the
minimum supported Rust version, and the wire format of the optional `serde`
feature.
## Semantic versioning
reef-core follows [Semantic Versioning 2.0.0](https://semver.org/), with the
usual Cargo reading of the `0.x` series.
**During `0.x`, a bump of the minor component may break you.** `0.x.y` to
`0.(x+1).0` is the breaking-change channel, which is what Cargo already assumes
for a `0.x` dependency: `0.1` and `0.2` are incompatible ranges. `0.x.y` to
`0.x.(y+1)` is compatible and is where fixes and additive changes land.
**After `1.0.0`, standard semantic versioning applies**: breaking changes only
in a major, additions in a minor, fixes in a patch.
### What counts as a breaking change
The Rust surface is not a matter of opinion here, because it is checked in.
`api/reef-core.txt` is a `cargo-public-api` snapshot of the entire public
surface, and the verification gate compares a freshly generated snapshot against
it on every run. It records the surface of the working tree rather than of any
published version — which is why its name carries no version number — so what a
release promised is the snapshot at that release's tag. That makes the rule
mechanical:
> **Any deletion from the public snapshot, or any change to a signature already
> in it, is a breaking change.**
That covers a removed item, a renamed item, a removed or reordered function
parameter, a narrowed argument type, a widened return type, a removed trait
implementation, a new required method on a public trait, a new bound on an
existing generic parameter, and an item moving between modules. It also covers
raising the minimum supported Rust version, for the reasons in the next section.
Two things that are *not* on the snapshot are breaking anyway, and they are
named because a snapshot cannot see them: changing documented runtime behaviour
that the contracts in `docs/contracts.md` describe, and changing the
serialized wire format, which has its own section below.
### What is deliberately not breaking
- **Adding a variant to a `#[non_exhaustive]` enum.**
- **Adding a field to a `#[non_exhaustive]` struct.**
- **Adding a new item** — a type, a function, a module, a trait implementation
on an existing type — that removes nothing.
- **Adding an optional, off-by-default feature.**
- **Adding a provided method with a default body to a public trait.**
The first two are the reason hard constraint ⑦ of `AGENTS.md` exists and the
reason ADR-017 spent an entire milestone classifying every public enum before the
first release. The attributes are not
decoration; they are the growth channel, and they were applied *before*
publication precisely so that this paragraph can be written.
The classification is also why the rule has an edge. Enums a *consumer*
constructs deliberately stay exhaustive, so that a missing match arm in a
provider, a codec or a plugin combinator is a compile error rather than a
silently dropped case. Adding a variant to one of those is therefore a breaking
change, and the fact that it is a breaking change is the point of leaving them
unmarked. If you want to know which category a given enum is in, the attribute
in the snapshot tells you.
### Yanking
A published version is immutable, and reef-core will not yank a release to
correct documentation, metadata or packaging. Yanking is reserved for a release
that is actively harmful — one that does not build, or one with a security
defect and no fixed successor yet available.
## Minimum supported Rust version
**The current MSRV is 1.85.0**, which is the first release supporting edition
2024. It is declared as `rust-version` in `Cargo.toml`, pinned in
`scripts/tool-versions.env`, and enforced on every gate run: the MSRV toolchain
compiles every target with `-D warnings`, links every test, runs the
compile-time authority probes and the Loom models, and separately builds and
runs the standalone public-API harness in `benchmarks/harness`. A change
that quietly requires a newer compiler cannot land.
**Raising the MSRV is a minor version change, not a patch.** This is the
convention tokio and serde use, and it is the one this project adopts: a patch
release must remain installable for anyone the previous patch release worked
for. Concretely, during `0.x` an MSRV bump goes out in a `0.(x+1).0`, and after
`1.0` in a `1.(y+1).0`.
An MSRV bump will be motivated in the release notes rather than taken for
convenience, and it will be its own entry in [`../CHANGELOG.md`](../CHANGELOG.md)
rather than a line inside a feature entry.
## Stability of the `serde` feature
The optional `serde` feature is off by default and adds `Serialize` and
`Deserialize` to the twenty-eight owned value types a session file or a
lifecycle record is made of. Enabling it changes nothing observable until you
write serialization code, and it adds one leaf crate, `serde_core`, with no
proc macro.
**The serialized form is a compatibility surface with the same status as the
Rust signature, and it is already frozen.** ADR-019 D5 fixes the entire
vocabulary — every struct field name and order, every enum tag, the external
tagging style, the transparent newtypes and the byte encoding — as string
literals that no Rust rename can reach, and `tests/serde_format.rs` pins it as a
corpus of byte-exact expected JSON in both directions, backed by a recording
serializer that asserts the serde call sequence itself. The format cannot drift
without that test failing.
The growth rule is narrow and is stated here because it is a promise to whoever
writes a session file:
> The serialized form may grow **only** by adding a field that is always written
> on output, or by adding a variant to a `#[non_exhaustive]` enum. It may never
> rename a field or a tag, change a tag, change a field's serde data type,
> change the tagging style, or begin omitting a field.
>
> **Anything that is not one of those two is a breaking change** — a major
> version after `1.0`, and a minor version during `0.x`.
Three consequences follow from the format's own design and are worth stating in
compatibility terms.
**The format is forward-readable and backward-strict.** No field is ever
omitted, no field has a default, and unknown fields and unknown enum tags are
refused rather than dropped. So a newer reef reads an older file, and an older
reef refuses a newer one by name instead of silently losing a field. Both
permitted growth moves are therefore additive for a newer reader and a named
error for an older one — which is the correct failure, given that one of the
fields that could be silently dropped is the provider-issued token that makes a
reasoning block acceptable to the provider.
**No schema version is emitted.** reef-core serializes values, not documents,
and a version belongs to a document. The crate version is the schema version,
and Cargo already records it; a composition layer that writes a file owns its
own envelope and can put whatever version it likes in it.
**Two limits are properties of the format rather than bugs to be fixed.**
`MetadataValue` carries a documented maximum nesting depth of 128 in both
directions and reports a typed error past it, rather than truncating or
overflowing the stack. And `MetadataValue::Float` admits every `f64` bit
pattern, including the non-finite ones, so it does not round-trip through
formats that cannot represent them; JSON is such a format. Neither will be
changed silently, and changing either would be a breaking change under the rule
above.
## Where the record lives
[`../CHANGELOG.md`](../CHANGELOG.md) follows
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and is the release
record. Every breaking change is called out there explicitly, with the migration
if one exists, in addition to being visible as a deletion in the diff between
two `api/` snapshots.