Versioning & deprecation policy¶

TOVIO is more than a piece of software: it is a documented, versioned format, and the tools, integrations, and data you build on top of it depend on those contracts staying stable. This page explains how TOVIO versions its formats and protocols, what counts as a breaking change, and how long a contract you depend on keeps working.

The one-sentence version

The software follows Semantic Versioning; the format, wire, and token contracts are versioned independently of it, and a breaking change to any of them ships with a migration path and keeps the previous version readable for one major version.

Four contracts, versioned independently¶

The version on the tovio binary is not the version of the things other tools build against. There are four independently-versioned surfaces:

Surface	What it guarantees	Current
Storage format	The on-disk bytes, framing, and addressing --- what makes a hash reproduce	Format version 1
Wire protocol	The sync handshake and frames between client, relay, and peer	v1.0 (Stable, frozen)
Policy & capability tokens	The policy grammar and the capability-token schema	`tovio-capability-v1`
MCP / agent API	The tool surface AI agents call	`tovio-mcp-v1.3`

Today the wire protocol is the only one of the four whose specification is Stable (frozen 2026-07-08); the storage-format, policy/token, and MCP specifications are in Review (see the lifecycle below).

Why split them? A change to the agent API shouldn't force a storage-format bump, and a new on-disk field shouldn't invalidate every existing token. Versioning each surface on its own keeps changes small and migrations narrow.

How specs mature: Draft → Review → Stable¶

Every spec document carries a Status that moves through three stages:

Status	What it means for you
Draft	Under active development. May change without notice. Most specs are here today.
Review	Feature-complete and under formal review. Breaking changes are discouraged and must be justified.
Stable	A frozen contract. Breaking changes follow the deprecation policy below and bump a version.

A spec is promoted only deliberately, and two hard preconditions gate Stable:

No Stable storage format or crypto until an independent third-party cryptographic audit has reviewed the envelope, the Key Authority flow, and the secret-at-rest path. (That audit is a final- phase deliverable --- see the roadmap.)
No Stable surface without a conformance corpus that the reference implementation passes 100% on every change.

So when a contract says "Stable," it has been audited (for crypto) and is independently verifiable --- not merely declared finished.

What is --- and isn't --- a breaking change¶

For the storage format, the rule is precise, because the format's whole job is to make hashes reproduce:

Not breaking (no version bump)

A backward-compatible addition --- a new optional field that doesn't change the bytes of existing objects, or a brand-new object type tag. Existing objects still hash to the same address.

Breaking (version bump + migration)

Any change that alters how an existing object encodes --- and therefore its address. There is no such thing as a "small" address-changing change. It bumps the format version and ships a documented, tested migration.

For the other surfaces:

Wire protocol --- a single integer major plus an additive minor capability set. A minor bump adds capabilities without breaking older peers (negotiated in the handshake); a major bump is breaking and follows this policy.
Tokens --- the schema rejects unknown version strings, so a new schema is a new version string (tovio-capability-v2, and so on). Old tokens stay verifiable through the compatibility window below.

The backward-compatibility window: N−1¶

When a surface makes a breaking jump from version N to N+1:

Readers keep accepting the previous version, N−1. An implementation that supports N+1 must still read --- and offer to migrate --- repositories at version N. At any time, the current major and the one before it are supported. We commit to a one-major-version backward window.
A migration path ships with the breaking change. For the storage format that means a documented, tested migration that rewrites an N repository to N+1, with conformance vectors for both. No such migration exists yet, because the storage format has never had a breaking bump. Old conformance corpora are frozen, never deleted, so coverage for the old format never regresses.
Unknown objects are preserved verbatim, never reinterpreted during sync --- so a mixed-version fleet can't corrupt history.
The 1.0 line gets a floor. Once 1.0 ships, its storage format, wire protocol, and capability-token schema are supported for at least 24 months from the release date, independent of later majors.

How a breaking change is announced¶

A breaking version bump is never silent. Every one is:

Proposed as an ADR (an Architecture Decision Record) with the rationale and the migration design.
Recorded in the changelog under an explicit Breaking changes heading --- the version it lands in, the version it deprecates, and the date the N−1 window closes.
Given a deprecation period before the old version is dropped --- at minimum one release cycle, longer for the storage format --- during which both versions work and the tools emit a migration notice.

We won't break a Stable contract faster than this policy allows, even to fix a wart. Warts on Stable surfaces wait for the next major.

How software releases are numbered¶

Semantic Versioning for the tovio software. Pre-1.0, minor versions may carry breaking changes (as is conventional for 0.x), but the format/wire/token policy above governs those contracts independently of the software number.
The 1.0 line is gated on the final-phase deliverables: the third-party security audit, the published Stable specification set, and a second, independent implementation passing the conformance corpus.
No release has been published yet. The tree is versioned 0.1.0 (pre-alpha). When releases ship, each one ships static single-file CLI binaries (Linux, macOS, Windows; x86_64 and aarch64), the Forge container image and Kubernetes manifest, the per-platform Node native-binding prebuilds, and the npm packages for the TypeScript edges --- built reproducibly from the committed lockfile and a pinned toolchain.

The binding, authoritative policy is the project repository's GOVERNANCE.md. It defers the engineering detail to docs/specs/compatibility-and-deprecation.md, the complete register of every versioned surface --- thirteen today, the four above among them --- which is itself still a Draft document and moves with the specifications it tracks. The release history itself is on the changelog page; how versioning maps onto the build phases is on the roadmap.

Last reviewed September 9, 2026

Suggest an improvement to this page Not for security reports — see disclosure