A document declares the lowest version that can express its content, not
the version of the build that wrote it. So a recording carrying a world
configuration is a 2, and one without is still a
MINIMUM_REPLAY_FORMAT_VERSION — byte for byte the same text this
format produced before version 2 existed. A document this build wrote is
therefore somewhere in [MINIMUM…LATEST]; only a configuration-carrying
one is stamped with this constant.
That rule is what makes the bump safe in both directions:
Old documents still run. A 1 is read by this build unchanged and
re-encodes identically, so every recording on disk, and every golden that
pins one, is untouched. §34's refusal is about not running bytes you do not
understand — and this build understands a 1 completely.
New documents are refused by old builds, loudly. A version-1 reader
meeting a 2 raises SERIALIZATION_VERSION_MISMATCH naming both numbers,
which is exactly right: it would otherwise drop the configuration during
its canonical rebuild and replay into a mismatched world without noticing —
the very defect PH-6 closed.
Downgrading is a real operation, not a hack. Deleting
worldConfiguration from a 2 and re-validating yields a valid 1
(validateReplayRecording re-derives the version from the content), so a
recording can be handed to an older build deliberately, losing exactly the
guarantee it names.
The highest format version this build can write — an upper bound, not the number that ends up on any particular document.
2since 2026-08-06 (PH-6), which added ReplayRecording.worldConfiguration.The versioning rule (decision, PH-6)
A document declares the lowest version that can express its content, not the version of the build that wrote it. So a recording carrying a world configuration is a
2, and one without is still a MINIMUM_REPLAY_FORMAT_VERSION — byte for byte the same text this format produced before version 2 existed. A document this build wrote is therefore somewhere in[MINIMUM…LATEST]; only a configuration-carrying one is stamped with this constant.That rule is what makes the bump safe in both directions:
1is read by this build unchanged and re-encodes identically, so every recording on disk, and every golden that pins one, is untouched. §34's refusal is about not running bytes you do not understand — and this build understands a1completely.2raisesSERIALIZATION_VERSION_MISMATCHnaming both numbers, which is exactly right: it would otherwise drop the configuration during its canonical rebuild and replay into a mismatched world without noticing — the very defect PH-6 closed.worldConfigurationfrom a2and re-validating yields a valid1(validateReplayRecordingre-derives the version from the content), so a recording can be handed to an older build deliberately, losing exactly the guarantee it names.See SUPPORTED_REPLAY_FORMAT_VERSIONS for what this build reads.