# 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 API promise covers every public item, signature, trait implementation,
variant, and field that a dependent can name. The rule is:
> **Removing a public item or trait implementation, or changing an existing
> public signature, is a breaking change.**
That covers a removed or renamed item, a removed or reordered function
parameter, a narrowed argument type, a widened return type, 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.
A source-compatible signature is not the whole compatibility promise. Changing
documented runtime behaviour on which callers rely is breaking, as is changing
the serialized form described below. Release tooling may check these surfaces,
but this promise does not depend on access to that tooling or its repository.
### 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 attributes are not decoration: they reserve an explicit additive
growth channel. Without the attribute, adding a variant or field is breaking.
Consumer construction alone does not determine exhaustiveness. Such an enum
stays exhaustive when consumers must classify or translate its vocabulary
faithfully, or when adding a variant would break an external construction duty;
a missing match arm then remains a compile error rather than a silently dropped
case. A unit classification that consumers only select or carry may instead be
`#[non_exhaustive]` when adding a variant breaks no external construction duty.
`CompletionReason` and `SettledDisposition` are the current examples. The enum's
declaration in rustdoc shows which compatibility rule applies.
### 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. The packaged `Cargo.toml` declares it in `rust-version`; consumers may rely
on that value for this release line.
**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 have its own entry in the packaged
[`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 enables the feature-gated
`Serialize` and `Deserialize` implementations attached to owned value types in
the source; those implementations are the authoritative inventory. Enabling it
changes nothing observable until a caller invokes serialization, and it adds
`serde_core` with no proc macro.
**The serialized form is a compatibility surface with the same status as a Rust
signature.** The promise covers every struct field name and order, every enum
tag, the external tagging style, transparent newtypes, and byte encoding. A Rust
rename does not rename its frozen wire spelling.
Every current field is always written and required on input: no field is omitted,
no field has a default, and unknown fields and enum tags are rejected rather than
silently discarded. Those rules determine the compatible growth boundary:
- Adding, removing, renaming, reordering, or changing the data type of a field in
an existing serialized struct is **breaking**. In particular, adding a required
field cannot be called additive: a newer reader could not read an older value
without a default, and this format deliberately has none.
- Adding a variant to a serialized `#[non_exhaustive]` enum is compatible. A
newer reader accepts older values; an older reader rejects a value using the
new tag by name instead of losing it.
- Adding a variant to an exhaustive enum is breaking. Renaming or changing any
existing tag, changing the tagging style, or beginning to omit a field is also
breaking.
- Adding a new serializable type without changing the representation of an
existing type is additive.
Thus newer reef versions read older values throughout a compatible release line.
Older versions are not promised to read data that uses a newly added enum
variant, but they fail explicitly rather than accepting an incomplete value.
These rules matter especially for the provider-issued token that makes a
reasoning block acceptable to its provider: silently dropping an unknown field
would corrupt resumability.
**No schema version is emitted.** reef-core serializes values, not documents,
and a version belongs to a document. The crate version identifies the schema a
caller compiled against; a composition layer that writes a file owns its envelope
and may record its own schema or crate-version marker there.
**Two limits are properties of the format rather than bugs to be fixed.**
`MetadataValue` carries a maximum nesting depth of 128 in both directions and
reports a typed error past it rather than truncating or overflowing the stack.
`MetadataValue::Float` admits every `f64` bit pattern, including non-finite ones,
so it does not round-trip through formats such as JSON that cannot represent
them. Changing either property is breaking.
## Where the record lives
The packaged [`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 migration
guidance when one exists. This document supplies the complete rule used to make
that classification; access to repository-only design records or verification
artifacts is not required.