docs: explain versioning guarantees and format evolution

[connortsui20]

Summary

Explains backward compatibility and how newer writers can target older readers, with separate practical guidance and design documentation. Distinguishes current guarantees from planned compressor behavior.

Changes

Adds an older-reader example, Rust configuration, a writer-to-reader diagram, a full compatibility matrix with explanatory footnotes, and an edition registry. The proof remains in draft #9950. Validation was limited to source inspection.

[codspeed]

Merging this PR will degrade performance by 4.31%

⚠️ Unknown Walltime execution environment detected

Using the Walltime instrument on standard Hosted Runners will lead to inconsistent data.

For the most accurate results, we recommend using CodSpeed Macro Runners: bare-metal machines fine-tuned for performance measurement consistency.

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 4 improved benchmarks
❌ 7 regressed benchmarks
✅ 2197 untouched benchmarks
⏩ 293 skipped benchmarks¹

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Mode	Benchmark	BASE	HEAD	Efficiency
❌	Simulation	decode_primitives[f32, (1000, 512)]	42 µs	59.6 µs	-29.52%
❌	Simulation	take_fsl_u64_random[64, 10]	112.7 µs	138 µs	-18.31%
❌	WallTime	dbp_assemble_kernel_avx512[(I128, 1024)]	463 ns	555 ns	-16.58%
❌	Simulation	take_fsl_nullable_random[256, 10]	169.8 µs	197.1 µs	-13.88%
❌	WallTime	dbp_assemble_kernel_avx2[(I128, 1024)]	464 ns	534 ns	-13.11%
❌	Simulation	take_fsl_f16_random[256, 100]	204.9 µs	230.6 µs	-11.17%
❌	Simulation	allocate_drop_arrow[65536]	90.6 µs	101.9 µs	-11.05%
⚡	Simulation	take_fsl_f16_random[16, 100]	179.5 µs	119.4 µs	+50.3%
⚡	WallTime	filtered_sink_i64_avx2[OneNullInEight]	26.2 µs	23 µs	+13.6%
⚡	Simulation	take_fsl_nullable_random[16, 100]	188 µs	165.7 µs	+13.42%
⚡	WallTime	dbp_split_kernel_mixed_null_avx2[(I128, 1024)]	1.2 µs	1.1 µs	+12.03%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing ct/versioning-docs (1f81692) with develop (a542cbd)}

Footnotes

1. 293 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[mprammer]

Overall, really good! I've left a few comments; feel free to take or leave them.

[connortsui20]

I rewrote a big chunk of this

[joseph-isaacs]

can we not make this from a markdown system?

[connortsui20]

I think its a bit hard, and not sure what is wrong with an svg

[robert3005]

@connortsui20 can you follow up with maybe simpler diagrams in markdown?

[mhk197]

I think this diagram is a bit misrepresentative and the bottom text is irrelevant

[mhk197]

Would be better to have something that differentiates original encoding to revved encoding. Vertical partition in diagram maybe.

Something like

DBP array (1 child, doesn't support 128 and 256) <- serde -> decimal_byte_parts serialized

                                                                             | Encoding update

DBP array (1 - 4 children, supports 128 and 256) <- serde -> decimal_byte_parts serialized (v1) OR decimal_byte_parts serialized (v2)