explain the underflow motivation

Author: maxrjones

design/chunk-grid.md

@@ -88,8 +88,11 @@ class FixedDimension:
 @dataclass(frozen=True)
 class VaryingDimension:
     """Explicit per-chunk sizes. The last chunk may extend past the array
-    extent, in which case data_size clips to the valid region while
-    chunk_size returns the full edge length for codec processing."""
+    extent (extent < sum(edges)), in which case data_size clips to the
+    valid region while chunk_size returns the full edge length for codec
+    processing. This underflow is allowed to match how regular grids
+    handle boundary chunks, and to support shrinking an array without
+    rewriting chunk edges (the spec allows trailing edges beyond the extent)."""
     edges: tuple[int, ...]           # per-chunk edge lengths (all > 0)
     cumulative: tuple[int, ...]      # prefix sums for O(log n) lookup
     extent: int                      # array dimension length (may be < sum(edges))

src/zarr/core/chunk_grids.py

@@ -125,8 +125,11 @@ def _size_repr(self) -> str:
 @dataclass(frozen=True)
 class VaryingDimension:
     """Explicit per-chunk sizes. The last chunk may extend past the array
-    extent, in which case ``data_size`` clips to the valid region while
-    ``chunk_size`` returns the full edge length for codec processing."""
+    extent (``extent < sum(edges)``), in which case ``data_size`` clips to
+    the valid region while ``chunk_size`` returns the full edge length for
+    codec processing. This underflow is allowed to match how regular grids
+    handle boundary chunks, and to support shrinking an array without
+    rewriting chunk edges (the spec allows trailing edges beyond the extent)."""
 
     edges: tuple[int, ...]  # per-chunk edge lengths (all > 0)
     cumulative: tuple[int, ...]  # prefix sums for O(log n) lookup