feat: add Array.with_shape and Array.with_chunk_grid

[kylebarron]

Adds two metadata-only reshaping methods to Array and AsyncArray, wrapping
zarrs' Array::set_shape and Array::set_shape_and_chunk_grid.

Closes #111.

API

# change the shape, keep the chunking
array = array.with_shape([8, 8])
array.store_metadata()

# change the chunking (and, optionally, the shape with it)
array = array.with_chunk_grid(ChunkGrid.regular([8, 8], [4, 4]))
array.store_metadata()

Both return a new array reference and leave the receiver untouched. Neither
performs any I/O; store_metadata() persists. On AsyncArray both are sync
methods, since there is nothing to await.

Why a new reference rather than in-place mutation

zarr-python's Array.resize() mutates in place, so this diverges deliberately.

An Array is a cached snapshot of zarr.json plus the objects derived from it,
and rebinding (array = array.with_shape(...)) leaves no stale reference
behind. Mutating in place would instead require interior mutability
(RwLock<Arc<Array<…>>>) across all 57 self.inner sites, force shape(),
chunk_grid_shape(), and dimension_names() to return owned values rather than
borrowed, and open a window where a Python-level sequence such as
(array.shape, array.chunk_grid_shape) could straddle a mutation and observe a
mix of before and after. An immutable reference is internally consistent for its
whole lifetime.

It also matches read_only(), which already derives a new Array from an
existing one.

with_chunk_grid takes one argument, not two

zarrs' signature is set_shape_and_chunk_grid(array_shape, chunk_grid_metadata),
because its chunk-grid metadata is a shape-free chunking scheme. zarrista's
ChunkGrid is not: every constructor takes array_shape first
(ChunkGrid.regular(array_shape, chunk_shape)). A literal port would state the
shape twice and let the two contradict each other:

array.with_shape_and_chunk_grid([8, 8], ChunkGrid.regular([4, 4], [2, 2]))
#                                ^^^^^^                   ^^^^^^

Taking the ChunkGrid alone and reading the shape off it makes that
unrepresentable — and removes an error class, since the grid and shape now agree
by construction.

Safety

set_shape_and_chunk_grid is unsafe upstream: it does not check that chunks
already in the store match the new grid. Changing the chunk shape leaves existing
chunks at keys that no longer describe the same region, so later reads may fail
to decode or return wrong data.

Python has no unsafe, so this is documented on the stub rather than encoded in
the name — following the convention store_encoded_chunk already uses for a
caller-beware API. The docs point at with_shape when only the shape is
changing, since that preserves the chunking and keeps existing chunks valid.

Implementation

Both methods perform no I/O and are byte-identical across the sync and async
classes, so they live in the shared_array_methods! macro rather than in
sync.rs / async.rs. zarrs' Array is not Clone, so
with_storage(self.inner.storage()) supplies the copy while keeping the storage
type parameter unchanged.

Shape and grid validation is left entirely to zarrs; because ? runs before
Self::new, a rejected input never yields an object.

Not included

Shrinking, or regridding, leaves chunks outside the new bounds in the store.
zarr-python folds that cleanup into resize(); here it cannot live in these
methods, which do no I/O at all, so it will be a separate vacuum call built
on zarrs' erase_chunks. test_shrink_leaves_out_of_bounds_chunks and
test_existing_chunks_are_not_migrated pin the current behavior so that change
has something to flip.

Two further follow-ups came out of the design discussion, each worth its own
issue: a pull sync point (reopen()) for when the store has moved ahead of a
local reference, and optimistic concurrency for store_metadata via conditional
PUT.

Testing

15 new tests across tests/array/test_with_shape.py (8) and
tests/array/test_with_chunk_grid.py (7): the new-reference/original split,
that nothing is written before store_metadata, grow/shrink/regrid round-trips
through reopen, data surviving a grow, wrong dimensionality raising, rectilinear
grids, orphaned chunks after a shrink, chunks left unmigrated after a regrid, and
async round-trips for both methods.

Full suite: 125 passed. cargo fmt, cargo clippy --all-targets --all-features -D warnings, and ruff check / format --check over tests/ and python/ all
clean.

🤖 Generated with Claude Code

[kylebarron]

with_shape is immutable and creates a new array reference. The old array reference has the old shape

[kylebarron]

@d-v-b you can ignore reading the specs; they're verbose history only for future agent context

[kylebarron]

Perhaps we should have a vacuum call that removes any now-unaccessible chunks?

[kylebarron]

Suggested change

	"""Return a new array reference with `chunk_grid`, leaving this one unchanged.
	"""Return a new array reference with `chunk_grid`.
	This does not mutate the existing `array`.

[kylebarron]

Ok this PR LGTM now.

I'll wait till tomorrow to merge so @d-v-b can take a look if he wants