chunkmirage materialize: a dataset written to a store as the server serves it

[davidackerman]

The Python side of #39's Engine.materialize: a dataset, or a box of it, computed and written into a store as a frontend serves it, so it reads back as a stored dataset of its own. registration-station's use is the first: a pass computed once per round (about 5 minutes for the s3 stage on an A100), then read from disk instead of computed again.

chunkmirage materialize SOURCE OUT [--op ...] [--format zarr3|zarr|n5] [--level N ...] [--box lo:hi]

and chunkmirage.materialize(pipeline, where, format=, levels=, box=, compressor=, skip_empty=, progress=) for any pipeline, a chain of datasets through dataset:// among them (registry.get(name)).

What it writes. The frontend's own metadata and encoded chunks (resolve and encode, as the server answers a request), so a zarr v3 (OME-Zarr 0.5), zarr v2 (OME-Zarr 0.4, consolidated) or N5 store is byte for byte what a client fetches, compressed as the server compresses (blosc for zarr, gzip for N5, --compressor otherwise). Frontends gain chunk_key(level, index), the path a chunk is served at; the precomputed and mesh frontends have none, so they are not offered. The store is anything tensorstore's kvstore writes: a directory, or a file://, gs:// or s3:// URL.

In what order. Every level's metadata first, so a store whose writing stopped part way is still the dataset, zero where no chunk was written yet; then the chunks of the levels asked for (all by default), in batches of 256 computed at once through #38's demand.gather; a chunk of nothing but zeros is left out (a reader takes a missing chunk as the fill value) unless --keep-empty. --box takes level 0's voxels along the last axes, and each level writes the same region on its own voxels, rounded out to whole chunks.

Not here. The browser's background class (#39) matters only when a region is written inside a server someone is browsing; a write from the command line or a script needs none, and inside a running server this competes with clients as any work asked for from Python does (never dropped, in arrival order), its chunks passing through the server's cache. The cache on disk that browsing fills (roadmap item 2) is still to do.

Tests (tests/test_materialize.py, 4): a warp shifted past its image's edge written as zarr v3, zarr v2 and N5, every chunk counted written or skipped (the ones past the edge skipped) and each level read back with the served shape, voxel size, dtype and values; and from the command line, a box of level 1 only, one chunk written and the rest of the store zeros.

Docs: concepts/formats.md (a section beside the browser engine's), reference/cli.md (the command), reference/api.md, design.md (the core's table), contributing.md (the plugin API), roadmap.md (item 2: a first piece in both engines), CHANGELOG.md. Checks: pytest (322 passed), ruff, mkdocs build --strict; chunkmirage schema unchanged; web/ untouched.