Support irregular chunking

[asinghvi17]

Summary

• add Zarr v3 rectilinear chunk-grid metadata support
• read and write arrays across irregular chunk boundaries
• validate, encode, and decode inline chunk shapes, including run-length encoding
• document irregular chunking and add Julia/Python interoperability coverage

Stacked on #342, which fixes resize! on read-only arrays and consolidated stores; this PR's changes to resize! build on it.

Relation to #326

Same strategy and user-facing API as #326 (chunks=DiskArrays.GridChunks(...) for zcreate, zzeros, and ZArray(data; chunks)), brought to parity with it:

Behaviour	#326	this PR
Regular axis inside a rectilinear grid stores a full-size final chunk (what zarr-python writes)	yes	yes (was clipped before this update)
resize! / append! along regular axes of a rectilinear array	grow only	grow and shrink
Growing an irregular axis	shape changes but the grid does not, so the metadata no longer validates	appends one chunk covering the added extent, as zarr-python does
Shrinking an irregular axis	throws after mutating the shape	throws before mutating
Declared edges that overflow the array extent (allowed by the spec)	rejected	rejected with an explicit error
Julia → zarr-python data round trip	@test_broken	passes
Irregular grid with zarr_format=2	silently persists the max chunk size, so reopened data is wrong	ArgumentError
metadata.chunks	Ref{GridChunks} in v2 and v3	v3 only: Ref holding an NTuple (regular) or GridChunks (rectilinear); v2 unchanged

Stored chunk extents were checked against zarr-python 3.3.0: it stores the final chunk of an integer axis at the full chunk size.

Known limitation

The spec lets a list of edge lengths overflow the array extent, and zarr-python leaves such a list behind when it shrinks a rectilinear array (it changes shape and keeps chunk_shapes). DiskArrays.IrregularChunks cannot describe a chunk that extends past the array, so Zarr.jl throws an ArgumentError when opening one. For the same reason Zarr.jl cannot shrink an irregular axis itself. Supporting both is left for a follow-up.

Validation

On Julia 1.12 after the rebase:

• full Julia test suite: 2,903 passed
• Python interoperability in both directions, including a non-divisible regular axis and growing an irregular axis from either side
• documentation build and doctests passed

🤖 Generated with Claude Code

https://claude.ai/code/session_01YY277jAB9XVg9KqrBuxL38

[coveralls]

Coverage Report for CI Build 35620748692

Warning

No base build found for commit eef5469 on fix/resize-guards.
Coverage changes can't be calculated without a base build.
If a base build is processing, this comment will update automatically when it completes.

Coverage: 89.279%

Details

• Patch coverage: 7 uncovered changes across 3 files (173 of 180 lines covered, 96.11%).

Uncovered Changes

File	Changed	Covered	%
ZarrCore/src/ZArray.jl	97	93	95.88%
ZarrCore/src/metadata3.jl	69	67	97.1%
ZarrCore/src/metadata.jl	14	13	92.86%

Coverage Regressions

Requires a base build to compare against. How to fix this →

---

Coverage Stats

Relevant Lines:	2080
Covered Lines:	1857
Line Coverage:	89.28%
Coverage Strength:	2974.38 hits per line

---

💛 - Coveralls

[felixcremer]

How is this related to #326?

[meggart]

Was asking myself the same thing. #326 is written by a human, tests pass except that I am constantly rebasing against main as a moving target.

[meggart]

Ok, I think your bot was definitely looking at my PR. strategy is the same as in my implementation, some names were cleaned up and code got a bit more verbose but looks ok IMO. Even the test example in the interop test is the same.

[asinghvi17]

I hadn't seen 326 when I had the bot make this, it was mostly for my own testing to make sure irregular chunks would fit my usecase. Can close once the subpackage PR lands and we rebase #326