Plan conflict-free write batches for mismatched chunk grids

[d-v-b]

🤖 AI text below 🤖

Incoming chunks can write disjoint array slices yet race when the destination performs read-modify-write on shared chunks or shards. This PR adds plan_rechunk to keep each source chunk as one task and schedule batches with disjoint destination write units. For chunks of 3 copied into chunks of 4 over length 12, the schedule is ((0, 2), (1, 3)).

plan_write_batches handles existing request-to-destination transforms. Its default preserves input order between conflicting tasks; explicit order="reorder" uses deterministic first-fit coloring. The scheduler tracks per-unit state without constructing a pairwise conflict graph. Plans contain task/piece metadata and perform no I/O.

This is stacked on zarr-indexing/grid-partition, independent of the separate execution-prototype PR.

Contracts and limits

• The destination grid describes independently writable units: use shards when writes replace shard objects. Finish all destination I/O in a batch before starting the next; prefetched destination snapshots invalidate the guarantee.
• Source and destination must not alias during a copy, and unrelated writers must be excluded. Task-internal duplicate assignments remain the caller's responsibility.
• Planning is eager. There is no byte-memory budget, optimal coloring guarantee, temporary-store selection, or task coalescing. Unsupported plan_chunks transform combinations remain unsupported.

Comparison and adversarial review

The guide compares the utility with Rechunker, Dask task rechunking, and Xarray alignment checks. The benchmark script was run with Dask 2026.8.0 and Rechunker 0.5.4 in an isolated environment. It distinguishes explicit schedule assignments from external planners' transfer-layout descriptions rather than presenting unlike constructor times as a throughput comparison.

The 100-task misaligned case schedules in four batches. Row-to-column copying needs 128 serial batches when source rows stay intact; Rechunker instead selects (4, 128) reads, (4, 4) intermediate blocks, and (128, 4) writes under the tested 4 KiB budget. This limitation is documented rather than hidden behind a coloring heuristic.

Independent adversarial review checked 5,000 resource-set schedules against a reference first-fit algorithm, 4,000 transform footprint cases against point enumeration (unsupported mixed transforms excluded explicitly), and 1,500 irregular-grid source-selection reconstructions. Review corrections include explicit transform limitations, complete runnable snippet imports, and correctly named Rechunker output fields.

Validation

• 1,503 package tests passed, including Hypothesis conflict/RMW checks and six concurrent Zarr copies across v2/v3/shards and both codec pipelines.
• The integration tests live in the package suite collected by CI and skip only when Zarr itself is unavailable.
• Ruff, mypy for the new module, and strict MkDocs builds passed. Pyright has zero errors and 90 warnings.
• The guide's executable snippet is included in documentation tests; 87 documentation tests passed after final review edits.