Expand description
randomize-range — shuffles the row order within a bounded range into
an unpredictable, server-chosen order (issue #1845).
Split out of #1830, unblocked by #1831’s ADR-0083.
sort_range.rs’s near-exact template, minus the sort-key machinery.
ADR-0083 §3 initially placed randomizeRange under SheetsWrite alone,
on a values-only reading — a permutation of the range’s own cells is a
strict special case of what a sheets-write grant already permits via
clear+write. §5 made that provisional on live verification: whether
the server carries a row’s formatting, notes and data-validation rules
along with it when reordering, and what happens to an in-range formula.
Live-verified 2026-09-22 against a probe sheet in omni-dev-test
(issue #1845’s plan comments): formatting, notes and data-validation
rules move with the row, and an in-range formula moves with its row
with its relative references rewritten to keep pointing at its own
row. Formatting is SheetsStructure’s own subject matter, so §5’s
fixed consequence applies and the gate is the union of SheetsWrite
and SheetsStructure — [target_gate::resolve_all], the same shape
text_to_columns.rs took. The same live run also confirmed §3’s
record-decoupling caveat: cells in the same rows but outside the
selected columns do not move, so a range narrower than its rows can
silently detach a record’s other columns.
The resulting order can never be previewed, and this crate never sees
it even after a real run. randomizeRange carries no response
object, and which order the server settles on is entirely its own
choice — --dry-run (and the real run) instead report the range being
reordered, leading with the range-width-vs-sheet-width record-integrity
caveat before the smaller “references outside the range may see a
different row’s value” caveat, and stating plainly that the resulting
order is not knowable — never a cell’s contents (ADR-0083 §6).