opencodecs 0.3.0__tar.gz → 0.3.1__tar.gz

{opencodecs-0.3.0 → opencodecs-0.3.1}/CHANGES.rst

@@ -10,6 +10,48 @@ Versions follow the same ``YYYY.M.D`` cadence as upstream when we
 publish; the entries below cluster work by date rather than by
 release because most of it has shipped continuously to ``main``.
 
+0.3.1 (2026-09-28)
+------------------
+
+A CZI read scheduling fix, and a clear refusal for the files that cannot
+stack. Figures compare against 0.3.0 on the same machines.
+
+**CZI whole-stack reads hand out work by bytes**
+
+``read`` derived its batch size from the worker count, giving each worker
+``ceil(n/workers)`` consecutive sub-blocks. That makes the read wait on
+that many sub-blocks even when most workers have already finished: nine
+8 MiB sub-blocks over eight workers is two rounds, and measured 15.1 ms
+against 7.9 ms for nine one-sub-block tasks. Tasks are now sized by
+output bytes, about 8 MiB each, so a large sub-block gets a task to
+itself and small ones ride together. That keeps the reason batching
+existed, which is that a 0.7 MiB tile cannot pay for its own future,
+without paying the rounding. ``_READ_MAX_WORKERS`` goes 8 to 32: the old
+value was measured against the dispatch above, where extra workers could
+not help. With byte-sized tasks, 20 to 32 measured fastest on both a
+20-core arm64 Mac and a 128-core x86-64 Linux host, and past 32 the Linux
+host gives it back to memory-bandwidth contention. A semaphore keeps the
+resolved worker count a real bound when the byte sizing yields more tasks
+than that.
+
+Eight files of 2000 x 2000 uint16 ZSTDHDR sub-blocks, read back to back:
+22.1 to about 15 ms per file on macOS, which moves a whole-stack read
+from a little behind aicspylibczi to about 1.3x ahead of it.
+
+**A mixed sub-block CZI says so, instead of failing inside the codec**
+
+``read`` stacks every sub-block into one array, and sized that array from
+the first sub-block, which is wrong for any file whose sub-blocks differ:
+a pyramidal slide scan interleaves down-scaled sub-blocks with
+full-resolution ones, and a mosaic can clip its edge tiles. The decode
+destination check then failed with an element count the caller never
+chose, naming neither the file's shape mix nor a way forward. It now
+refuses up front, listing the shapes it cannot stack and the APIs that do
+work (``CziPyramidReader.read_region``, ``entries_at_level``,
+``read_tile`` and ``iter_tiles``), and the new ``CziReader.is_uniform``
+lets a caller branch before asking. Decoding was never at fault: JPEG XR
+sub-blocks are pixel-exact against aicspylibczi.
+
 0.3.0 (2026-09-27)
 ------------------
 

{opencodecs-0.3.0/src/opencodecs.egg-info → opencodecs-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opencodecs
-Version: 0.3.0
+Version: 0.3.1
 Summary: Streaming, network-aware image codecs for scientific imaging (prototype: JPEG XL)
 Author: Kevin Cutler
 License-Expression: BSD-3-Clause

{opencodecs-0.3.0 → opencodecs-0.3.1}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "opencodecs"
-version = "0.3.0"
+version = "0.3.1"
 description = "Streaming, network-aware image codecs for scientific imaging (prototype: JPEG XL)"
 readme = "README.md"
 requires-python = ">=3.10"

{opencodecs-0.3.0 → opencodecs-0.3.1}/src/opencodecs/__init__.py

@@ -342,4 +342,4 @@ __all__ = [
     "CziWriter", "CziPyramidWriter",
 ]
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"

{opencodecs-0.3.0 → opencodecs-0.3.1}/src/opencodecs/_czi_reader.py

@@ -60,12 +60,46 @@ _DEFAULT_POOL_SIZE = max(2 * (os.cpu_count() or 4), 8)
 _POOL: ThreadPoolExecutor | None = None
 
 #: Most concurrent workers a whole-stack read() will use when the caller
-#: gives no count. Measured on a 20-core arm64 Mac and a 128-core x86-64 Linux host with
-#: the batched persistent-pool dispatch below and a FRESH output each read
-#: (a sweep that recycled the output favored 16, which does not survive
-#: contact with real page faults): 8 and 12 tie on both machines, 16 doubles
-#: the time on Linux.
-_READ_MAX_WORKERS = 8
+#: gives no count, on top of the per-machine cap of one worker per core.
+#: An earlier sweep set this to 8, but it was measured against a dispatch
+#: that derived the batch size from the worker count, where extra workers
+#: could not help (see the task sizing in ``read``). With tasks sized by
+#: bytes, a fresh output each read, and 8 MB sub-blocks, 20-32 measured
+#: fastest on both a 20-core arm64 Mac and a 128-core x86-64 Linux host,
+#: and past 32 the Linux host gives it back to memory-bandwidth contention.
+_READ_MAX_WORKERS = 32
+
+#: How much decoded output one scheduled task should carry. A sub-block at
+#: or above this size gets a task to itself; smaller ones ride together up
+#: to roughly this much. Below it the pool's own scheduling and the
+#: first-touch faults on a fresh output cost more than the extra
+#: concurrency buys, and above it the read waits on the tail of a long
+#: task. 8 MB was the best common value across 0.7 MB and 8 MB sub-blocks
+#: on both machines.
+_READ_TASK_BYTES = 8 << 20
+
+
+def _read_tasks(n_entries: int, tile_bytes: int,
+                budget: int | None = None) -> list[range]:
+    """Partition sub-block indices into tasks of roughly ``budget`` bytes.
+
+    A sub-block at or above the budget gets a task to itself; smaller ones
+    ride together up to it. Kept out of ``read`` so the partition can be
+    asserted on its own: it is the part of this with an off-by-one to get
+    wrong, and comparing decoded pixels cannot see such a bug, because
+    every partition of the same sub-blocks decodes to the same array.
+
+    ``budget`` defaults to ``_READ_TASK_BYTES`` read at call time, not as a
+    default argument value: a default would bind the number at import and
+    leave the module constant looking tunable while changing nothing.
+    """
+    if n_entries <= 0:  # pragma: no cover - empty CZI defense
+        return []
+    if budget is None:
+        budget = _READ_TASK_BYTES
+    per_task = max(1, budget // tile_bytes) if tile_bytes > 0 else n_entries
+    return [range(i, min(i + per_task, n_entries))
+            for i in range(0, n_entries, per_task)]
 
 
 def _get_pool() -> ThreadPoolExecutor:
@@ -512,11 +546,16 @@ class CziReader(Reader):
         # Lazy caches for metadata accessors.
         self._metadata_bytes_cache: bytes | None = None
         self._metadata_xml_cache: str | None = None
+        self._uniform_cache: bool | None = None
 
         self._parse_header()
 
         # Reader-ABC contract: populate shape/dtype/n_frames eagerly so
-        # callers can inspect a file without decoding it.
+        # callers can inspect a file without decoding it. This describes the
+        # stack ``read`` returns, which only exists when every sub-block
+        # stores the same number of pixels - see ``is_uniform``. A pyramidal
+        # or otherwise mixed CZI has no such stack, and ``read`` says so
+        # rather than sizing one from the first sub-block.
         if self.entries:
             first = self.entries[0]
             self.dtype = first.dtype
@@ -1279,6 +1318,8 @@ class CziReader(Reader):
         """
         if not self.entries:  # pragma: no cover - empty CZI defense
             return np.empty((0,))
+        if not self.is_uniform:
+            raise self._nonuniform_error("read()")
 
         first = self.entries[0]
         tile_shape = first.stored_shape
@@ -1338,34 +1379,50 @@ class CziReader(Reader):
             # call: creating one costs 1-2 ms on macOS and several on a
             # 128-core Linux host, which is more than the read itself.
             #
-            # And never one task per tile: with decode writing straight
-            # into the fresh output, too many threads first-touching one
-            # large allocation measured 44% slower on macOS than a cap of
-            # eight; Linux prefers more. A thread count is a budget:
-            # resolve it from the output size under the platform's
-            # measured cap, and give each worker a contiguous run.
+            # Work is handed out by BYTES, not by worker count. Deriving
+            # the batch size from the worker count -- ceil(n/workers)
+            # sub-blocks each -- makes the read wait on that many
+            # sub-blocks even when most workers have already finished:
+            # nine 8 MB sub-blocks over eight workers is two rounds, and
+            # measured 15.1 ms against 7.9 ms for nine one-sub-block
+            # tasks on the same machine. Sizing a task by output bytes
+            # gives a big sub-block its own task and groups small ones,
+            # which keeps the original reason for batching (a 0.7 MB tile
+            # cannot pay for its own future) without paying the rounding.
             from .core.parallel import resolve_workers
 
             n = len(self.entries)
+            tasks = _read_tasks(n, out.nbytes // n)
             if n_workers is not None:
-                workers = max(1, min(int(n_workers), n))
+                workers = max(1, min(int(n_workers), len(tasks)))
             else:
                 workers = resolve_workers(
-                    None, n, output_bytes=out.nbytes,
+                    None, len(tasks), output_bytes=out.nbytes,
                     has_decode_work=any(e.compression != 0 for e in self.entries),
                     max_workers=_READ_MAX_WORKERS)
-            if workers <= 1:
-                for i in range(n):
+
+            def _run_task(batch):
+                for i in batch:
                     _worker(i)
+
+            if workers <= 1 or len(tasks) == 1:
+                for batch in tasks:
+                    _run_task(batch)
+            elif workers >= len(tasks):
+                list(_get_pool().map(_run_task, tasks))
             else:
-                step = (n + workers - 1) // workers
-                batches = [range(i, min(i + step, n)) for i in range(0, n, step)]
+                # More tasks than the resolved budget: the pool is shared
+                # and larger than that budget, so map alone would run
+                # every task at once. A semaphore keeps the budget a
+                # budget while still letting a worker pick up the next
+                # task the moment it finishes one.
+                gate = threading.Semaphore(workers)
 
-                def _run_batch(batch):
-                    for i in batch:
-                        _worker(i)
+                def _gated(batch):
+                    with gate:
+                        _run_task(batch)
 
-                list(_get_pool().map(_run_batch, batches))
+                list(_get_pool().map(_gated, tasks))
 
         if as_rgb:
             out = _bgr_to_rgb(out, first.pixel_type)
@@ -1398,6 +1455,50 @@ class CziReader(Reader):
                 f"{full} or {squeezed}")
         return out
 
+    # ----- Sub-block uniformity -----
+
+    @property
+    def is_uniform(self) -> bool:
+        """True when every sub-block decodes to the same pixel count and type.
+
+        This is exactly the condition under which the sub-blocks stack into
+        one rectangular array, so it is what ``read``, ``__getitem__`` with a
+        slice and ``self.shape`` depend on. Pyramidal CZIs interleave
+        down-scaled sub-blocks with the full-resolution ones and are not
+        uniform; neither is a mosaic whose edge tiles are clipped.
+
+        Compares pixel counts rather than shapes because CZI sizes a decode
+        destination by element count, so sub-blocks differing only in
+        singleton axes stack fine.
+        """
+        if self._uniform_cache is None:
+            self._uniform_cache = len({
+                (math.prod(e.stored_shape), e.pixel_type)
+                for e in self.entries}) <= 1
+        return self._uniform_cache
+
+    def _nonuniform_error(self, call: str) -> "CziError":
+        """The error for asking a mixed-sub-block CZI for a single stack.
+
+        Sizing the stack from the first sub-block and letting the decode
+        destination check fail deep in the codec reports an element count the
+        caller never chose, which says nothing about the file or the way out.
+        """
+        shapes = sorted({tuple(s for s in e.stored_shape if s != 1)
+                         for e in self.entries})
+        preview = ", ".join(str(sh) for sh in shapes[:4])
+        if len(shapes) > 4:
+            preview += ", ..."
+        return CziError(
+            f"{call} stacks sub-blocks into one array, but this CZI stores "
+            f"{len(shapes)} different sub-block shapes ({preview}), so no "
+            f"such array exists"
+            + (" - the file is pyramidal" if self.is_pyramidal else "")
+            + ". Use CziPyramidReader(reader).read_region(level, y=..., x=...)"
+            " for one resolution level, entries_at_level(n) to select a "
+            "level's sub-blocks, or read_tile(i) / iter_tiles() for "
+            "tile-at-a-time access.")
+
     # ----- Pyramid support -----
 
     @property

{opencodecs-0.3.0 → opencodecs-0.3.1/src/opencodecs.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opencodecs
-Version: 0.3.0
+Version: 0.3.1
 Summary: Streaming, network-aware image codecs for scientific imaging (prototype: JPEG XL)
 Author: Kevin Cutler
 License-Expression: BSD-3-Clause

{opencodecs-0.3.0 → opencodecs-0.3.1}/src/opencodecs.egg-info/SOURCES.txt

@@ -297,8 +297,10 @@ tests/test_coverage_push.py
 tests/test_czi_bounded_iteration.py
 tests/test_czi_direct_decode.py
 tests/test_czi_fixture.py
+tests/test_czi_mixed_subblocks.py
 tests/test_czi_parallel_write.py
 tests/test_czi_pyramid.py
+tests/test_czi_read_dispatch.py
 tests/test_czi_read_out.py
 tests/test_czi_region_index.py
 tests/test_czi_region_windows.py

opencodecs-0.3.1/tests/test_czi_mixed_subblocks.py

@@ -0,0 +1,82 @@
+"""A CZI whose sub-blocks are not all the same size, and how ``read`` says so.
+
+``read`` stacks every sub-block into one rectangular array, which only exists
+when they all hold the same number of pixels. A pyramid CZI interleaves
+down-scaled sub-blocks with the full-resolution ones, and a mosaic can clip
+its edge tiles, so both break that assumption. Sizing the stack from the
+first sub-block and letting the decode destination check fail reported an
+element count the caller never chose -- on a real AxioScan slide,
+``destination holds 3080192 elements, expected 1048576`` -- which named
+neither the file's shape mix nor the API that does work. These pin the
+up-front refusal and the fact that a uniform file is untouched by it.
+
+The dispatch that read uses to fill that stack is covered separately, in
+test_czi_read_dispatch.py.
+"""
+from __future__ import annotations
+
+import pathlib
+import sys
+
+import numpy as np
+import pytest
+
+sys.path.insert(0, str(pathlib.Path(__file__).parent))
+
+from _czi_fixture import mosaic_czi_bytes, pyramid_czi_bytes  # noqa: E402
+
+from opencodecs._czi_reader import CziError, CziReader  # noqa: E402
+
+
+def _tile(h, w, seed):
+    return np.random.RandomState(seed).randint(0, 4096, (h, w)).astype(np.uint16)
+
+
+def test_mixed_tile_sizes_are_not_uniform():
+    data = mosaic_czi_bytes([(_tile(64, 64, 1), (0, 0)),
+                             (_tile(64, 48, 2), (0, 64))])
+    with CziReader(buffer=data) as r:
+        assert r.is_uniform is False
+
+
+def test_uniform_tiles_are_uniform_and_read():
+    data = mosaic_czi_bytes([(_tile(64, 64, 1), (0, 0)),
+                             (_tile(64, 64, 2), (0, 64))])
+    with CziReader(buffer=data) as r:
+        assert r.is_uniform is True
+        assert r.read().shape == (2, 64, 64)
+
+
+def test_read_refuses_a_mixed_file_and_names_the_way_out():
+    data = mosaic_czi_bytes([(_tile(64, 64, 1), (0, 0)),
+                             (_tile(64, 48, 2), (0, 64))])
+    with CziReader(buffer=data) as r:
+        with pytest.raises(CziError) as exc:
+            r.read()
+    message = str(exc.value)
+    # The shapes it could not stack, and every API that does work.
+    assert "(64, 64)" in message and "(64, 48)" in message
+    assert "read_region" in message
+    assert "entries_at_level" in message
+    assert "read_tile" in message
+    # Not the element-count error from deep inside the codec.
+    assert "elements" not in message
+
+
+def test_read_refuses_a_pyramid_and_says_it_is_pyramidal():
+    base = _tile(64, 64, 3)
+    data = pyramid_czi_bytes([base, base[::2, ::2], base[::4, ::4]])
+    with CziReader(buffer=data) as r:
+        assert r.is_pyramidal is True
+        assert r.is_uniform is False
+        with pytest.raises(CziError, match="pyramidal"):
+            r.read()
+
+
+def test_mixed_file_still_reads_one_tile_at_a_time():
+    """The refusal is about the stack, not about the sub-blocks."""
+    tiles = [_tile(64, 64, 4), _tile(64, 48, 5)]
+    data = mosaic_czi_bytes([(tiles[0], (0, 0)), (tiles[1], (0, 64))])
+    with CziReader(buffer=data) as r:
+        for i, expected in enumerate(tiles):
+            assert np.array_equal(r.read_tile(i), expected)

opencodecs-0.3.1/tests/test_czi_read_dispatch.py

@@ -0,0 +1,199 @@
+"""How ``CziReader.read`` hands sub-blocks to threads.
+
+``read`` sizes each scheduled task by output bytes rather than by worker
+count, because deriving the batch size from the worker count made the read
+wait on ``ceil(n/workers)`` sub-blocks even when most workers had already
+finished. Two properties of that need holding down, and neither is visible
+in the decoded pixels:
+
+**The partition.** Every partition of the same sub-blocks decodes to the
+same array, so an output comparison passes whatever the task boundaries
+are. That is not hypothetical: the first version of these tests only
+compared arrays, and every case in it happened to fall into the serial
+branch, so the parallel dispatch it was named after went untested.
+``_read_tasks`` is asserted directly instead.
+
+**The worker bound.** When the byte sizing yields more tasks than the
+resolved worker count, a shared pool bigger than that count would run all
+of them at once. Too many threads first-touching one fresh output measured
+slower, which is the whole reason there is a bound. An unbounded pool still
+returns correct pixels, so these watch peak concurrency.
+"""
+from __future__ import annotations
+
+import pathlib
+import sys
+import threading
+import time
+
+import numpy as np
+import pytest
+
+sys.path.insert(0, str(pathlib.Path(__file__).parent))
+
+from _czi_fixture import mosaic_czi_bytes  # noqa: E402
+
+from opencodecs import _czi_reader as cz  # noqa: E402
+from opencodecs._czi_reader import CziReader, _read_tasks  # noqa: E402
+
+MIB = 1 << 20
+
+
+def _tiles(n, size, seed=0):
+    rs = np.random.RandomState(seed)
+    return [rs.randint(0, 4096, (size, size)).astype(np.uint16) for _ in range(n)]
+
+
+def _mosaic(tiles):
+    return mosaic_czi_bytes(
+        [(t, (0, i * t.shape[1])) for i, t in enumerate(tiles)],
+        compression=6, hilo=True)
+
+
+# ---------------------------------------------------------------- partition
+
+@pytest.mark.parametrize("n,tile_bytes,budget,expected", [
+    # A sub-block at or over the budget gets a task to itself.
+    (4, 8 * MIB, 8 * MIB, [range(0, 1), range(1, 2), range(2, 3), range(3, 4)]),
+    (2, 32 * MIB, 8 * MIB, [range(0, 1), range(1, 2)]),
+    # Smaller ones ride together, and the last task is short.
+    (10, 2 * MIB, 8 * MIB, [range(0, 4), range(4, 8), range(8, 10)]),
+    (63, 1 * MIB, 8 * MIB, [range(0, 8), range(8, 16), range(16, 24),
+                            range(24, 32), range(32, 40), range(40, 48),
+                            range(48, 56), range(56, 63)]),
+    # Everything fits in one task: the caller takes the serial path.
+    (5, 1024, 8 * MIB, [range(0, 5)]),
+    (1, 8 * MIB, 8 * MIB, [range(0, 1)]),
+    # A zero-byte tile must not divide by zero.
+    (3, 0, 8 * MIB, [range(0, 3)]),
+])
+def test_read_tasks_partition(n, tile_bytes, budget, expected):
+    assert _read_tasks(n, tile_bytes, budget) == expected
+
+
+@pytest.mark.parametrize("n,tile_bytes", [(1, 512), (7, 3 * MIB), (64, 9 * MIB)])
+def test_read_tasks_covers_every_index_exactly_once(n, tile_bytes):
+    seen = [i for task in _read_tasks(n, tile_bytes) for i in task]
+    assert seen == list(range(n))
+
+
+# ------------------------------------------------------------- worker bound
+
+class _ConcurrencyWatch:
+    """Record peak overlap of the decode calls a read makes."""
+
+    def __init__(self, hold=0.05):
+        self.hold = hold
+        self.peak = 0
+        self.calls = 0
+        self._live = 0
+        self._lock = threading.Lock()
+
+    def wrap(self, real):
+        def decode(*args, **kwargs):
+            with self._lock:
+                self._live += 1
+                self.calls += 1
+                self.peak = max(self.peak, self._live)
+            try:
+                # Hold the slot open so genuinely concurrent workers overlap;
+                # without it fast tiles can finish before the next one starts
+                # and a parallel run would look serial.
+                time.sleep(self.hold)
+                return real(*args, **kwargs)
+            finally:
+                with self._lock:
+                    self._live -= 1
+        return decode
+
+
+@pytest.fixture
+def small_budget(monkeypatch):
+    """One task per sub-block for cheap test-sized tiles."""
+    monkeypatch.setattr(cz, "_READ_TASK_BYTES", 1024)
+
+
+def _watched_read(monkeypatch, data, **kw):
+    watch = _ConcurrencyWatch()
+    monkeypatch.setattr(CziReader, "_decode_one",
+                        watch.wrap(CziReader._decode_one), raising=True)
+    with CziReader(buffer=data) as r:
+        n = len(r.entries)
+        tile_bytes = r.entries[0].dtype.itemsize * int(
+            np.prod(r.entries[0].stored_shape))
+        tasks = _read_tasks(n, tile_bytes, cz._READ_TASK_BYTES)
+        out = r.read(**kw)
+    return out, watch, len(tasks), n
+
+
+def test_read_runs_tasks_concurrently(monkeypatch, small_budget):
+    """One task per sub-block, enough workers for all of them: they overlap.
+
+    The worker count is explicit because the automatic one is also bounded by
+    output bytes, and a test-sized read is far under that floor (see
+    ``test_a_tiny_read_stays_serial``).
+    """
+    tiles = _tiles(8, 32, seed=1)
+    out, watch, n_tasks, n = _watched_read(
+        monkeypatch, _mosaic(tiles), n_workers=8)
+    assert n_tasks == n == 8, "budget should give one task per sub-block"
+    assert watch.calls == 8
+    assert watch.peak > 1, "tasks ran one after another; dispatch is not parallel"
+    assert np.array_equal(out, np.stack(tiles, axis=0))
+
+
+def test_a_tiny_read_stays_serial(monkeypatch, small_budget):
+    """Byte-sized tasks do not override the "too little to thread" floor.
+
+    ``resolve_workers`` caps the count by output bytes as well, so a read
+    this small resolves to one worker however many tasks the byte sizing
+    produced. Pinned because it surprised me while writing these: the
+    partition is per-sub-block here, and the read is still serial.
+    """
+    tiles = _tiles(8, 32, seed=5)
+    out, watch, n_tasks, _ = _watched_read(monkeypatch, _mosaic(tiles))
+    assert n_tasks == 8
+    assert watch.peak == 1
+    assert np.array_equal(out, np.stack(tiles, axis=0))
+
+
+def test_worker_count_bounds_concurrency(monkeypatch, small_budget):
+    """More tasks than workers must not all run at once.
+
+    This is the semaphore's job. The shared pool is far larger than the
+    budget, so without it every task starts immediately and the decoded
+    pixels are still perfectly correct.
+    """
+    tiles = _tiles(8, 32, seed=2)
+    out, watch, n_tasks, _ = _watched_read(
+        monkeypatch, _mosaic(tiles), n_workers=2)
+    assert n_tasks == 8, "need more tasks than workers to exercise the bound"
+    assert watch.calls == 8
+    assert watch.peak > 1, "the gated branch did not run anything in parallel"
+    assert watch.peak <= 2, f"worker budget of 2 was exceeded (peak {watch.peak})"
+    assert np.array_equal(out, np.stack(tiles, axis=0))
+
+
+def test_serial_read_never_overlaps(monkeypatch, small_budget):
+    tiles = _tiles(4, 32, seed=3)
+    out, watch, _, _ = _watched_read(monkeypatch, _mosaic(tiles), n_workers=1)
+    assert watch.peak == 1
+    assert np.array_equal(out, np.stack(tiles, axis=0))
+
+
+# ---------------------------------------------------------------- integrity
+
+@pytest.mark.parametrize("n,size", [(8, 32), (3, 64), (17, 16)])
+def test_parallel_read_matches_serial(monkeypatch, n, size):
+    """Same pixels whatever the partition, across every dispatch branch."""
+    tiles = _tiles(n, size, seed=4)
+    data = _mosaic(tiles)
+    expected = np.stack(tiles, axis=0)
+    with CziReader(buffer=data) as r:
+        assert np.array_equal(r.read(n_workers=1), expected)
+    for budget in (1024, 4096, 1 << 30):   # per-tile, grouped, single task
+        monkeypatch.setattr(cz, "_READ_TASK_BYTES", budget)
+        with CziReader(buffer=data) as r:
+            assert np.array_equal(r.read(), expected), f"budget={budget}"
+            # An explicit count is a budget, not an instruction to spend it.
+            assert np.array_equal(r.read(n_workers=64), expected)