docs: Exilis client roll-forward notes (2026-06-22 changes)

[Xof]

A short migration note for Exilis (Chisel's one current client) to roll forward to the current Chisel.

Covers the complete client-visible delta since 7daa69d and — importantly — establishes that nothing requires a code change to keep working:

• UnsupportedPageSize / UnsupportedPageSizeError — additive (the enum is #[non_exhaustive]; Python has a FatalError fallback). A forward-compat open-time guard that can't fire today.
• Behavior fixes: out-of-range handles now error instead of aliasing onto a live slot; spillway-open failure is now fatal (the one "adapt if you use the spillway" item); overflow pages are type-validated.
• New Transaction methods (Python): handles / stats / counters / defrag — additive.
• Multi-page freemap: backward-compatible format (no version bump, old DBs open unchanged); the ~512 MB reclamation ceiling is gone.
• The transaction.rs decomposition: pure refactor, zero client impact.

Ends with a 4-step roll-forward checklist (expect a clean build + passing tests; review spillway-open handling; optionally adopt the new error/methods).

Docs-only.

[github-actions]

🚦 Bench results: PR vs main

⚠️ 1 regression(s) detected across 1 scenario/mode pair(s)

Scenario	Mode	Δ throughput	Worst Δ
ycsb-b	chisel-strict	+3.5%	p50 +5.8% ⚠️
document-store	chisel-mem	-0.0%	—
document-store	chisel-strict	+5.8%	—
document-store	redb-strict	-0.2%	—
document-store	sqlite-strict	-0.4%	—
mutation-log	chisel-mem	+1.0%	—
mutation-log	chisel-strict	+1.5%	—
mutation-log	redb-strict	-0.1%	—
mutation-log	sqlite-strict	-0.8%	—
ycsb-a	chisel-mem	-1.6%	—
ycsb-a	chisel-strict	+3.8%	—
ycsb-a	redb-strict	-0.0%	—
ycsb-a	sqlite-strict	-0.5%	—
ycsb-b	chisel-mem	-0.0%	—
ycsb-b	redb-strict	-0.1%	—
ycsb-b	sqlite-strict	+0.7%	—

Per-scenario detail (4 metrics × cells)

document-store

Mode	Throughput	p50	p95	p99
chisel-mem	18228 ops/s → 18220 ops/s (-0.0%)	15.2 µs → 15.1 µs (-0.7%)	140.9 µs → 141.1 µs (+0.1%)	685.7 µs → 674.5 µs (-1.6%)
chisel-strict	2946 ops/s → 3118 ops/s (+5.8%)	24.6 µs → 23.9 µs (-2.9%)	900.9 µs → 778.7 µs (-13.6%)	3.01 ms → 2.77 ms (-8.1%)
redb-strict	4004 ops/s → 3997 ops/s (-0.2%)	14.1 µs → 13.4 µs (-4.8%)	479.5 µs → 476.3 µs (-0.7%)	1.44 ms → 1.42 ms (-1.4%)
sqlite-strict	5123 ops/s → 5104 ops/s (-0.4%)	22.3 µs → 21.9 µs (-1.8%)	374.9 µs → 347.1 µs (-7.4%)	1.41 ms → 1.37 ms (-2.5%)

mutation-log

Mode	Throughput	p50	p95	p99
chisel-mem	51768 ops/s → 52277 ops/s (+1.0%)	23.2 µs → 22.9 µs (-1.2%)	26.9 µs → 26.7 µs (-0.7%)	35.6 µs → 35.4 µs (-0.8%)
chisel-strict	1770 ops/s → 1797 ops/s (+1.5%)	294.3 µs → 293.4 µs (-0.3%)	645.8 µs → 613.8 µs (-5.0%)	18.95 ms → 19.20 ms (+1.3%)
redb-strict	1807 ops/s → 1805 ops/s (-0.1%)	141.8 µs → 145.9 µs (+3.0%)	220.5 µs → 234.2 µs (+6.2%)	35.31 ms → 34.58 ms (-2.1%)
sqlite-strict	5058 ops/s → 5017 ops/s (-0.8%)	96.5 µs → 98.1 µs (+1.6%)	264.2 µs → 272.1 µs (+3.0%)	369.4 µs → 378.2 µs (+2.4%)

ycsb-a

Mode	Throughput	p50	p95	p99
chisel-mem	38423 ops/s → 37804 ops/s (-1.6%)	40.8 µs → 41.2 µs (+1.0%)	59.5 µs → 58.6 µs (-1.5%)	79.6 µs → 79.8 µs (+0.2%)
chisel-strict	2250 ops/s → 2335 ops/s (+3.8%)	252.4 µs → 254.1 µs (+0.7%)	744.8 µs → 736.3 µs (-1.1%)	1.83 ms → 1.44 ms (-21.6%)
redb-strict	2676 ops/s → 2676 ops/s (-0.0%)	115.5 µs → 114.1 µs (-1.2%)	205.7 µs → 194.4 µs (-5.5%)	321.0 µs → 314.6 µs (-2.0%)
sqlite-strict	130561 ops/s → 129864 ops/s (-0.5%)	7.8 µs → 7.7 µs (-0.9%)	10.3 µs → 10.4 µs (+1.1%)	13.3 µs → 12.9 µs (-2.6%)

ycsb-b

Mode	Throughput	p50	p95	p99
chisel-mem	163612 ops/s → 163541 ops/s (-0.0%)	4.6 µs → 4.8 µs (+3.7%)	42.6 µs → 41.8 µs (-2.0%)	49.0 µs → 47.3 µs (-3.3%)
chisel-strict	21872 ops/s → 22632 ops/s (+3.5%)	6.9 µs → 7.3 µs (+5.8%) ⚠️	258.5 µs → 260.4 µs (+0.7%)	632.8 µs → 649.2 µs (+2.6%)
redb-strict	27181 ops/s → 27159 ops/s (-0.1%)	3.2 µs → 3.3 µs (+2.2%)	113.5 µs → 118.0 µs (+3.9%)	177.8 µs → 186.3 µs (+4.7%)
sqlite-strict	158021 ops/s → 159092 ops/s (+0.7%)	6.4 µs → 6.4 µs (-0.2%)	8.7 µs → 8.7 µs (+0.1%)	11.0 µs → 10.9 µs (-0.6%)

_{Generated by chisel-bench-diff at 2026-06-23T05:44:50Z. Compares PR HEAD against main. Never blocks merge — signal, not gate. Thresholds: throughput 5%, p50 5%, p95 10%, p99 10%.}