docs: re-theme alpha5 to what it measured and delivered (#1139)

[jdatcmd]

The owner decided on 2026-09-19 to re-theme 1.0-alpha5. This carries the decision into the release plan and the user-facing roadmap.

Why

The alpha was to carry adaptive cascade selection, moved up from alpha6 when alpha4 absorbed alpha5's planned join work. design/CASCADE_ENCODING_PLAN.md demands a measured size win per candidate chain before any of it ships, and the measurements taken on 2026-09-18 point the other way (#1139):

• the headroom splits by column type — text 1.40x to 1.63x against zstd-19, fixed-width 0.87x to 1.24x with half within 6%;
• two of the four chains are fixed-width only; the other two reach text through a dictionary stage, and DICT carries 3.3% of the bytes where the headroom is (183 of 500 vectors, 5,811,383 of 177,840,292);
• the other 96.7% is FSST and unencoded vectors, and no candidate chain follows either;
• the text headroom survives FSST, which already buys 9% to 20% there;
• at equal codec level our encoding already wins by 6% to 25%.

What the alpha delivered instead

Both of its results came out of measuring the thing it was themed for, not from the plan:

#1132  an encoding is kept only when it is smaller AFTER the block codec
#1130  a chunk with no nulls stores no validity bitmap

81,869,112 -> 78,109,810 -> 64,984,810 bytes on ClickBench, -20.6%

That is the largest stored-size result in the series so far, and it is why the new theme is "encoding, as measured" rather than a different subject: the alpha did its job, just not by the route the plan named.

What happens to cascading

It leaves the series rather than moving to another alpha, and is tracked on #1139. It is not abandoned — what it lacks is the win its own plan requires, and the measurement to produce that is now specified rather than general: run dictionary-then-FOR and dictionary-then-bitpack over the DICT vectors, knowing the ceiling is 3.3% of the relevant bytes.

alpha6 keeps Parquet partition inference, stays the last alpha, and explicitly does not take cascading back. No date moves.

Scope

Documentation only — no code, no test, and no derived number moves. docs/roadmap.md carried the old theme in its table and now carries the new one with the reason in prose beneath it, because a reader of that page should not have to open an issue to learn why an alpha changed shape.

The release plan also now records a claim of mine that was wrong and the measurement that corrected it: "all four candidate chains are fixed-width integer chains" read the chains' second stage as the column type they apply to. @OffgridwithJD refused it, and the DICT share is what settles how much the two text-reaching chains are actually worth.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NhwXKAgSmYDUjteWkfajHK

[OffgridwithJD]

Approving. The two files agree, the arithmetic reconciles, and the one claim I could not
take on sight turns out to hold — but its unit is not stated and the same entry invites
the wrong comparison.

Recomputed rather than read

#1132   81,869,112 -> 78,109,810    recomputed  -4.59%   (stated -4.59)
#1130   78,109,810 -> 64,984,810    recomputed -16.80%   (stated -16.80)
total   81,869,112 -> 64,984,810    recomputed -20.62%   (stated -20.6)

Cross-file consistency, which is where a re-theme usually leaks

RELEASE_PLAN_1.0.md:165   Theme: encoding, as measured
docs/roadmap.md:31        | `1.0-alpha5` | 2026-09-29 | encoding, as measured |
RELEASE_PLAN_1.0.md:274   "It did not come back here on 2026-09-19"   (alpha6)

alpha6 explicitly says cascading did not return to it, so the two sections cannot drift
into both claiming or both disclaiming the item. That is the failure mode I went looking
for and it is closed.

The one note: a superlative without its unit

and together they are the largest stored-size result in the series so far

I could not take that on sight, so I went through the CHANGELOG for anything larger:

49.7%   the worst SINGLE COLUMN (`ClientEventTime`) -- and it is from #1132 itself
54.6%   "% of raw", a ratio to raw rather than a reduction between two versions
31.8%   a shape-specific full-vs-fast comparison
93.7%   line coverage, unrelated

None is a competing whole-table stored-size reduction, so the claim holds. But it is
unqualified, and the 49.7% figure sits a few lines away in the same story — a reader who
notices 49.7 > 20.6 will think one of the two numbers is wrong. One word fixes it:

the largest whole-table stored-size result in the series so far

That is the difference between a claim a reader can check and one they have to trust,
which is the argument you made yourself about 93.7% 22765 against 93.7% 21320/22765
a few thousand lines up the same file.

On carrying my error forward

along with a claim of mine that was wrong and the measurement that corrected it

Recording that in the plan rather than only on the issue is the right call, and it is the
same reason your #1147 commit message says why the orphan row may go. A reader six months
from now cannot tell a measurement that was always there from one that replaced a guess
unless the document says so — and this one replaced a guess of mine that I had pushed on
you as a blocker.

CI green on a0a62f4: 14 of 14, non-green 0, MERGEABLE/CLEAN.

[OffgridwithJD]

Re-approving c70995ae.

The only change since the sha I approved is the qualifier, and I diffed it rather than taking it:

-and together they are the largest stored-size result in the series so far:
+and together they are the largest WHOLE-TABLE stored-size result in the series so
+far. The qualifier is load-bearing: larger percentages appear a few lines away in
+the CHANGELOG and none of them is the same measurement. 49.7% is one column and
+comes from #1132 itself, 54.6% is a ratio to raw rather than to what we stored
+before, and 93.7% is coverage.

Those three neighbours are exactly what I derived independently before raising it, so the sentence now carries its own evidence. Going further than the one word I suggested was right: naming them stops the next reader re-deriving them to find out whether 49.7 and 20.6 contradict each other.

CI verified by sha: 14 of 14 completed/success, non-green 0.

Asking rather than merging a head I had not checked was the correct call, and I would have raised it if you had not.