docs: editions name serialized formats, not in-memory encodings - #9275
Open
joseph-isaacs wants to merge 2 commits into
Open
docs: editions name serialized formats, not in-memory encodings#9275joseph-isaacs wants to merge 2 commits into
joseph-isaacs wants to merge 2 commits into
Conversation
The editions spec never said what an edition member actually is, and the distinction matters as soon as an in-memory encoding outgrows the bytes it froze: the read-forever guarantee attaches to the serialized format — the ID in the file plus its metadata schema and child semantics — while the in-memory encoding is an unversioned implementation detail free to evolve underneath it. Spell out the model and the evolution rule it implies: freezing an edition freezes the meaning of each member ID, so an incompatible extension is a new serialized format with a new ID staged in a draft edition, never a mutation of the frozen one. The serialization plugin registry maps between the two worlds in both directions — reads may deserialize an old ID into a newer in-memory encoding (the ALP-with-patches precedent), and writes choose which of an encoding's serialized formats to emit. Worked example: growing decimal byte parts from one signed part to a signed MSP plus unsigned 64-bit lower parts. The reserved-but-zero lower_part_count field cannot carry the extension because frozen readers require it to be zero; instead single-part arrays keep the frozen ID byte-for-byte and multi-part arrays serialize under a new ID that old readers reject with the unknown-encoding error editions promise. Signed-off-by: Joe Isaacs <joe.isaacs@live.co.uk> Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01C5gep1Ah7rjHkDuyfrgKCD
Successive incompatible revisions of a serialized format take sequential version suffixes on the same base name — vortex.foo, vortex.foo_v2 — so each format has at most one successor and an encoding's serialized history is a list, never a tree of forked variants. Rename the example's wide id to vortex.decimal_byte_parts_v2 accordingly. Signed-off-by: Joe Isaacs <joe.isaacs@live.co.uk> Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01C5gep1Ah7rjHkDuyfrgKCD
Merging this PR will degrade performance by 12.86%
Warning Please fix the performance issues or acknowledge them on CodSpeed. Performance Changes
Tip Investigate this regression by commenting Comparing 
Footnotes
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Rationale for this change
The editions spec never says what an edition member actually is, and the distinction starts to matter the moment an in-memory encoding outgrows the bytes it froze. The concrete forcing case is
DecimalBytePartsgaining multi-part (wide decimal) support (#9119): the shipped serialized format promiseslower_part_count == 0to every reader sincecore2025.05.0, so writing lower parts under the same ID would violate the edition guarantee even though the in-memory encoding is the same one.This PR pins the model down in the spec: