Format and protocol stability

Two contracts get discussed together and are in genuinely different states. Conflating them is the most common error in third-party write-ups about TOVIO, so this article separates them first and explains the mechanics second.

The wire protocol is frozen

The wire protocol specification carries Stable status at version 1.0.0, frozen by an explicit owner decision. The frame set and the canonical encodings are settled; changes now follow the project's deprecation policy, and only additive, byte-compatible optional fields and messages may be introduced under the negotiated-capability rules. Clients and servers of different versions interoperate at the highest capability set both support.

The storage format is not

The storage format is at format version 1, and its specification still carries Review status — feature-complete and under formal review, with breaking changes discouraged and requiring justification, but not Stable.

That is not a technicality. Promotion to Stable has stated preconditions, and they are unmet: the independent third-party cryptographic audit of the envelope, the Key Authority flow, and the secret-at-rest path has not completed; the compatibility and deprecation policy that must cover a surface before promotion is itself still a Draft; and "specification v1.0 published" remains an open item on the roadmap. Anyone telling you the object format is frozen alongside the wire protocol is describing a state the project has not reached.

What actually protects data you have already written

The format carries a version-bump discipline that is narrower than a freeze and considerably better than nothing:

• Any change that alters how an existing object encodes — and therefore its content address — is a breaking format-version bump, and must ship a documented, tested migration under the deprecation policy. The specification is explicit that there is no such thing as a small address-changing change.
• A backward-compatible addition — a new optional field, a new object type tag — that does not alter the bytes of existing objects is not a version bump.
• The version is carried in two places that must agree: the repository's format marker and each structured object's own version key. Every object states, in its own bytes, the format it was written under.
• A reader that supports the next version must still accept the previous one, and offer to migrate.

The consequence that matters to you: bytes you have already written cannot be silently reinterpreted. A future reader either reads them as format 1, or refuses and says so. What is not promised is that the format will never move — only that it cannot move underneath you without a version bump, a migration, and an announcement.

Canonical serialisation, which makes all of this checkable

Structured objects use a deterministic encoding: shortest-form integers and lengths, definite lengths only, map keys sorted with no duplicates, one top-level value, no trailing bytes. The same logical content always produces the same bytes, and therefore the same content address, on every platform and in every implementation.

A non-deterministic encoding would be a correctness bug, not a style issue — it would break content addressing itself. This is enforced by a versioned conformance corpus: a fixed set of objects with known encodings, replayed on every change. Format behaviour is a test that runs, not a promise in a document. Old corpora are frozen and never deleted, so coverage for older formats only accumulates.

Content addressing and corruption

Objects are addressed by BLAKE3 hash and re-hashed on read and on receipt. A payload that does not match its address is surfaced as a corruption event rather than quietly accepted. Objects a replica relays but does not recognise are preserved byte-for-byte and never reinterpreted, so a mixed-version fleet cannot corrupt history in transit.

Someone other than the project checks the bytes

A dependency-free independent implementation, sharing no encoder with the reference one, re-hashes the addressed version-1 fixtures, validates the deterministic encoding, and reconstructs object families from the specification alone in continuous integration. That is the difference between "our code agrees with itself" and "the specification is sufficient to reimplement" — and it is a stated precondition for ever declaring a surface Stable.

What this means for you

A complete clone is a complete copy, not a view onto a service you need permission to keep using. The bytes are documented, the documentation is Apache-2.0, the corpus that pins the documentation is Apache-2.0, and an independent implementation demonstrably reads them. That is what makes leaving a copy rather than a migration.

If the format did change

It would be a deliberate, announced, corpus-regenerating version bump with a migration shipping in the same release, a full deprecation period, and both versions readable throughout. The specifications are published, so you can verify that rather than trust it.