Found while promoting the record-field rules into DESIGN.md (#368). Documentation only; nothing
in the code is wrong.
The state
DESIGN.md's "### Binary Format (v11)" section documents index format version 11. The
current INDEX_VERSION is 22.
The diagram is not merely old, it is contradicted by a change the same document now cites:
So a reader who trusts the diagram gets both the wrong widths and the wrong version, in exactly the
place they went looking for authoritative layout.
Why it was left alone
The #368 promotion pass placed new rules in a new section beside it, and refreshing the diagram
plus the v12–v22 history is its own task with its own verification: each version bump needs its
actual layout change identified from the commit that made it, not reconstructed. Doing that inside
a documentation-placement change would have mixed a large unverified rewrite into a small verified
one.
What that pass did do is stop the new text from vouching for the stale diagram: the new "What a
record claims" section opens with "The binary layout says how the bytes are arranged (the diagram
above predates v22)" rather than a deictic endorsement.
What the fix involves
- Regenerate the layout diagram from the current structs in
include/pup/index/format.hpp.
- Retitle the section to the current version, or better, to no version at all — a section titled
with a version number is a promise to update it on every bump, and this is the second time that
promise has gone unkept. Naming the header field that carries the version, and pointing at
format.hpp as the authority, is a shape that cannot rot the same way.
- Decide what version history the document should carry, if any. A per-version changelog in
DESIGN.md duplicates git history; the bump criterion (already documented on INDEX_VERSION)
is the part that has lasting value.
Point 2 is the substantive question — the rest is mechanical once it is answered.
Found while promoting the record-field rules into
DESIGN.md(#368). Documentation only; nothingin the code is wrong.
The state
DESIGN.md's "### Binary Format (v11)" section documents index format version 11. Thecurrent
INDEX_VERSIONis 22.The diagram is not merely old, it is contradicted by a change the same document now cites:
u8 in_count, u8 out_countfor operand counts.u32(INDEX_VERSION 21 → 22), because a command with more than 255operands had its counts silently clamped, and those vectors feed change detection.
So a reader who trusts the diagram gets both the wrong widths and the wrong version, in exactly the
place they went looking for authoritative layout.
Why it was left alone
The #368 promotion pass placed new rules in a new section beside it, and refreshing the diagram
plus the v12–v22 history is its own task with its own verification: each version bump needs its
actual layout change identified from the commit that made it, not reconstructed. Doing that inside
a documentation-placement change would have mixed a large unverified rewrite into a small verified
one.
What that pass did do is stop the new text from vouching for the stale diagram: the new "What a
record claims" section opens with "The binary layout says how the bytes are arranged (the diagram
above predates v22)" rather than a deictic endorsement.
What the fix involves
include/pup/index/format.hpp.with a version number is a promise to update it on every bump, and this is the second time that
promise has gone unkept. Naming the header field that carries the version, and pointing at
format.hppas the authority, is a shape that cannot rot the same way.DESIGN.mdduplicates git history; the bump criterion (already documented onINDEX_VERSION)is the part that has lasting value.
Point 2 is the substantive question — the rest is mechanical once it is answered.