From eb9b2dd5ad179b23c70640dbf0c262afe0608cd9 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 2 Nov 2026 07:37:58 +0000
Subject: [PATCH 01/23] CP-2b: remove code no file or in-memory run reaches
 since CP-2a

Pure removal, no behaviour change: pipeline.check_source_identities,
ids.object_set_from_label_path, io.read_ngff_mask, io.refuse_mask_channel_axis
and planes.iter_file_planes have had no caller since file runs read through
the preprocessing run's RunInputs (CP-2a).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G3qp9AxjpGPw9xfWAUJNqc
---
 src/cellpatcher/ids.py      |  6 ---
 src/cellpatcher/io.py       | 82 -------------------------------------
 src/cellpatcher/pipeline.py | 17 --------
 src/cellpatcher/planes.py   | 47 ++-------------------
 tests/test_file_runs.py     |  2 +-
 5 files changed, 4 insertions(+), 150 deletions(-)

diff --git a/src/cellpatcher/ids.py b/src/cellpatcher/ids.py
index f76dada..2f49e42 100644
--- a/src/cellpatcher/ids.py
+++ b/src/cellpatcher/ids.py
@@ -100,12 +100,6 @@ def object_set_from_mask_type(mask_type) -> str | None:
     return re.sub(r"[^A-Za-z0-9._-]", "_", str(mask_type)).strip("_") or None
 
 
-def object_set_from_label_path(mask_file) -> str:
-    """The label image name of an OME-NGFF mask ``<image>/labels/<name>`` (``io.read_ngff_mask``)."""
-    name = str(mask_file).rsplit("/", 1)[-1]
-    return re.sub(r"[^A-Za-z0-9._-]", "_", name).strip("_") or DEFAULT_OBJECT_SET
-
-
 def resolve_object_set(meta, common) -> str:
     """The ``object_set`` of a cell-mode image.
 
diff --git a/src/cellpatcher/io.py b/src/cellpatcher/io.py
index 70aeffa..e6736d5 100644
--- a/src/cellpatcher/io.py
+++ b/src/cellpatcher/io.py
@@ -499,72 +499,6 @@ def read_ome_zarr(path) -> tuple[np.ndarray, str]:
     return pixels, image.axes
 
 
-def read_ngff_mask(path, label_name: str | None, axes: str) -> tuple[np.ndarray, str]:
-    """Read an OME-Zarr image's label image as its mask, put into *axes* by role.
-
-    Follows ``docs/normalization_contract.md`` §4: the label image comes from
-    the image's ``labels`` group (*label_name* may be None when it has exactly
-    one), level 0 is read, its values must be integers, and each of its
-    dimensions must equal the image's or have length 1 (a channel axis, length
-    1). A label Z or T axis with the image's length then follows the image's
-    planes, and one of length 1 is shared (``common.z_policy``/``t_policy``).
-
-    Returns
-    -------
-    tuple
-        The mask in *axes*, and its ``mask_file`` name,
-        ``<image folder name>/labels/<label name>``.
-
-    Raises
-    ------
-    cellpatcher.statistics.PreprocessingUnavailableError
-        If the ``zarr`` extra is not installed.
-    ValueError
-        If the image has no such label image, the name is ambiguous, or the
-        label image does not fit the image.
-    """
-    from cellpatcher.statistics import INSTALL_COMMAND, PreprocessingUnavailableError, _preprocessing
-
-    mbp = _preprocessing()
-    path = Path(path).expanduser()
-    try:
-        image = mbp.open_ngff(path)
-        labels = mbp.open_ngff_labels(path, label_name)
-    except mbp.ZarrUnavailableError as exc:
-        raise PreprocessingUnavailableError(
-            f"Reading the OME-Zarr image {path.name} needs the zarr package. Install it with: {INSTALL_COMMAND}"
-        ) from exc
-    except mbp.NgffError as exc:
-        raise ValueError(
-            f"The mask of {path.name} cannot be read from its OME-Zarr labels: {exc}. Set "
-            "common.mask_label_name to one of its label images, or use common.mask_source='tiff_tree'."
-        ) from exc
-    # dataset_path is "[<image prefix>]labels/<name>/<level-0 array>".
-    name = labels.dataset_path.split("/")[-2]
-    if not np.issubdtype(labels.dtype, np.integer):
-        raise ValueError(
-            f"The label image {name!r} of {path.name} holds {labels.dtype} values; OME-NGFF label images "
-            "hold integers."
-        )
-    image_lengths = dict(zip(image.axes, image.shape))
-    problems = []
-    for axis, length in zip(labels.axes, labels.shape):
-        if axis == "C" and length != 1:
-            problems.append(f"its channel axis has length {length} (must be 1)")
-        elif axis in "YX" and length != image_lengths.get(axis):
-            problems.append(f"its {axis} axis has length {length}, the image's {image_lengths.get(axis)}")
-        elif length not in (1, image_lengths.get(axis)):
-            problems.append(f"its {axis} axis has length {length}, neither 1 nor the image's {image_lengths.get(axis)}")
-    if problems:
-        raise ValueError(
-            f"The label image {name!r} of {path.name} (axes {labels.axes!r}, shape {labels.shape}) does not fit "
-            f"the image (axes {image.axes!r}, shape {image.shape}): {'; '.join(problems)}."
-        )
-    pixels = mbp.zarr_input.read_selection(labels.array, (slice(None),) * len(labels.shape))
-    mask = conform_axes(pixels, labels.axes, axes, name=f"The label image {name!r} of {path.name}")
-    return mask, f"{path.name}/labels/{name}"
-
-
 def conform_axes(array, array_axes: str, target_axes: str, *, name="the image") -> np.ndarray:
     """Rearrange *array* (with axes *array_axes*) into *target_axes*, matching axes by role.
 
@@ -740,22 +674,6 @@ def refuse_transposed_mask_axes(mask_axes) -> None:
         )
 
 
-def refuse_mask_channel_axis(mask_axes) -> None:
-    """Refuse ``common.mask_axes`` with a C axis for masks read from a mask folder.
-
-    The preprocessing brick's ``find_masks`` refuses mask files with a channel
-    axis (``mask_not_2d``), so a C in *mask_axes* could only re-read a Z or T
-    axis the mask's metadata names, or an axis it does not name, as channels:
-    a guessed axis. Refused, never overridden (owner decision of 2026-10-30).
-    """
-    if mask_axes is not None and "C" in normalize_axes(mask_axes):
-        raise ValueError(
-            f"common.mask_axes={mask_axes!r} has a channel (C) axis, which mask files from a mask folder "
-            f"cannot have; it would read the mask's other axes as label channels. {MASK_CHANNEL_HELP} "
-            "Then set common.mask_axes to the mask's own axes (for example 'YX' or 'ZYX')."
-        )
-
-
 def header_axes_disagreement(path: str | os.PathLike, declared_axes: str) -> tuple[str | None, bool]:
     """Check *declared_axes* against a TIFF file's header with the preprocessing brick's rule.
 
diff --git a/src/cellpatcher/pipeline.py b/src/cellpatcher/pipeline.py
index 0cd6b76..b33f963 100644
--- a/src/cellpatcher/pipeline.py
+++ b/src/cellpatcher/pipeline.py
@@ -81,23 +81,6 @@ def check_config_identity(config: CellPatcherConfig) -> None:
         validate_object_set(config.common.object_set)
 
 
-def check_source_identities(config: CellPatcherConfig, image_files) -> None:
-    """Refuse the D85 identity of a folder's images from their names alone, before any read.
-
-    Each image file is one source: its labels, its ``position_id`` (the image name) and the
-    uniqueness of ``position_id`` within the technical repeat, ignoring case, are checked
-    exactly as ``run_patching`` checks them later, so two images ``Img.tif`` and ``img.tiff``
-    are refused before either (or a mask) is read.
-    """
-    seen: dict = {}
-    for index, path in enumerate(image_files):
-        meta = {"image_file": Path(path).name}
-        labels = _image_labels(config, meta)
-        meta["position_id"] = resolve_position_id(labels, meta, image_index=index)
-        check_unique_position(seen, labels, meta, index)
-    check_run_identity_case(seen)
-
-
 def _stamp_run_context(config: CellPatcherConfig, patches: list[PatchRegion]) -> None:
     condition, biological_repeat, technical_repeat = _run_labels(config)
     for patch in patches:
diff --git a/src/cellpatcher/planes.py b/src/cellpatcher/planes.py
index 2262d20..fa62d88 100644
--- a/src/cellpatcher/planes.py
+++ b/src/cellpatcher/planes.py
@@ -13,8 +13,8 @@
 of ``docs/normalization_contract.md`` §4 for OME-NGFF labels, applied to every
 mask).
 
-Images in memory are split with :func:`iter_image_planes`; image files with
-:func:`iter_file_planes`, which reads only the chosen planes when it can.
+Images in memory are split with :func:`iter_image_planes`; the images of a file run are read
+plane by plane through the preprocessing run (:mod:`cellpatcher.run_reading`).
 """
 
 from __future__ import annotations
@@ -194,7 +194,7 @@ def read_file_plane(path, image_axes, choice: PlaneChoice, common):
     """Read the plane *choice* of an image file: ``(pixels, axes)``.
 
     A TIFF or OME-Zarr plane is read on its
-    own (as :func:`iter_file_planes` does); any other image is read whole
+    own; any other image is read whole
     and the plane taken from it.
     """
     from cellpatcher.io import read_image
@@ -224,47 +224,6 @@ def select_mask_plane(mask, mask_axes, choice: PlaneChoice):
     return mask, mask_axes
 
 
-def iter_file_planes(path, image_axes, mask, mask_axes, common, *, single_planes=False) -> Iterator[ImagePlane]:
-    """Yield the planes of an image file chosen by the policies, reading only those planes when possible.
-
-    A TIFF or OME-Zarr image whose planes
-    are split or selected (``"all"``, ``"first"``, ``"select"``) is read one
-    2D plane at a time with the preprocessing brick's ``read_plane``
-    (``docs/normalization_contract.md`` §3): only the chosen planes are
-    decoded, and a plane that cannot be read whole within the brick's memory
-    limit is an error. Other images, ``"keep"`` and projections are read
-    whole with :func:`cellpatcher.io.read_image`, as before. Either way the
-    planes equal those of :func:`iter_image_planes` on the whole image.
-
-    Raises
-    ------
-    ValueError
-        As :func:`plane_choices`, or if a plane needs more memory than the limit.
-    """
-    from cellpatcher.io import read_image
-
-    mbp = _plane_reader(path, common)
-    if mbp is None:
-        image = read_image(path, image_axes)
-        yield from iter_image_planes(image, image_axes, mask, mask_axes, common, single_planes=single_planes)
-        return
-
-    path = Path(path).expanduser()
-    target = normalize_axes(image_axes)
-    mapping, shape, dtype = _file_layout(mbp, path, target)
-    if mask is not None:
-        mask = np.asarray(mask)
-        mask_axes = normalize_axes(mask_axes, mask.ndim)
-    mask_shape = None if mask is None else mask.shape
-    for choice in plane_choices(shape, target, mask_shape, mask_axes, common, single_planes=single_planes):
-        plane_axes = "".join(axis for axis in target if choice.value(axis) is None)
-        pixels = _read_choice(mbp, path, mapping, shape, dtype, target, choice)
-        plane_mask, plane_mask_axes = select_mask_plane(mask, mask_axes, choice)
-        yield ImagePlane(
-            pixels, plane_axes, plane_mask, plane_mask_axes, choice.index("Z"), choice.index("T"), choice.suffix
-        )
-
-
 def _read_choice(mbp, path: Path, mapping, shape, dtype, target: str, choice: PlaneChoice) -> np.ndarray:
     """Read the plane *choice* of a file, one 2D plane at a time, in *target* order minus resolved axes."""
     plane_axes = "".join(axis for axis in target if choice.value(axis) is None)
diff --git a/tests/test_file_runs.py b/tests/test_file_runs.py
index ede8b39..e258abb 100644
--- a/tests/test_file_runs.py
+++ b/tests/test_file_runs.py
@@ -145,7 +145,7 @@ def refused(*args, **kwargs):
 
     for module, name in ((cellpatcher.io, "pair_masks"), (cellpatcher.io, "read_image"), (cellpatcher.io, "read_array"),
                          (cellpatcher.io, "refuse_image_header_axes"), (cellpatcher.io, "discover_images"),
-                         (cellpatcher.planes, "iter_file_planes"), (cellpatcher.planes, "read_file_plane")):
+                         (cellpatcher.planes, "read_file_plane")):
         monkeypatch.setattr(module, name, refused)
     run = _clean_run(tmp_path, axes="ZCYX", shape=(3, 2, 16, 20), mask_types=())
     config = CellPatcherConfig(mode="grid")

From 54fb8e0d322ec7a3832c1cd16a515bac43bf61cc Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 2 Nov 2026 07:43:53 +0000
Subject: [PATCH 02/23] CP-2b: validate_image_and_mask_folders returns the
 preprocessing run's pairing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Design v0.4 §6: CellPatcher pairs no file itself. The function moves to
cellpatcher.file_runs (still cellpatcher.validate_image_and_mask_folders) and
takes preprocessing_run=: the run is opened with RunInputs.open with the image
and mask folders as where they are now, and each image's recorded mask of the
type is returned. Without a run it is refused (no_preprocessing_run, with the
preprocessing command); an image without a recorded mask of the type, a type
the run did not record, and a changed mask are refused.

The tests of CellPatcher's own pairing (find_masks through pair_masks:
ambiguous names, formats, header problems, a masks folder inside the images)
are removed: those checks are the preprocessing run's.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G3qp9AxjpGPw9xfWAUJNqc
---
 src/cellpatcher/__init__.py        |   2 +-
 src/cellpatcher/file_runs.py       |  75 ++++++--
 src/cellpatcher/io.py              |  33 ----
 tests/test_end_to_end_workflows.py |   8 +-
 tests/test_io.py                   | 297 ++++++-----------------------
 tests/test_ome_zarr_images.py      |   8 +-
 6 files changed, 134 insertions(+), 289 deletions(-)

diff --git a/src/cellpatcher/__init__.py b/src/cellpatcher/__init__.py
index 505a194..6cb8037 100644
--- a/src/cellpatcher/__init__.py
+++ b/src/cellpatcher/__init__.py
@@ -25,6 +25,7 @@
 )
 from cellpatcher.delivery import iter_exported_patches, iter_patch_arrays, load_exported_patch, patch_array
 from cellpatcher.errors import CellPatcherRefusal, LabelRangeError, SamplingExhaustedError
+from cellpatcher.file_runs import validate_image_and_mask_folders
 from cellpatcher.export import (
     PatchTableError,
     export_patches,
@@ -45,7 +46,6 @@
     list_supported_files,
     read_array,
     read_array_shape,
-    validate_image_and_mask_folders,
     write_array,
     run_patching_from_folders,
 )
diff --git a/src/cellpatcher/file_runs.py b/src/cellpatcher/file_runs.py
index ad51c03..c1bc178 100644
--- a/src/cellpatcher/file_runs.py
+++ b/src/cellpatcher/file_runs.py
@@ -26,7 +26,7 @@
 from typing import TYPE_CHECKING
 
 from cellpatcher.ids import object_set_from_mask_type, validate_object_set
-from cellpatcher.io import SINGLE_CONDITION_LABEL, ConditionRepeatFolder
+from cellpatcher.io import SINGLE_CONDITION_LABEL, ConditionRepeatFolder, refuse_removed_matching
 from cellpatcher.normalization import (
     CSV_SCOPES,
     check_image_type,
@@ -145,18 +145,17 @@ def refuse_file_run_settings(config: CellPatcherConfig, where: str) -> None:
         _refuse_without_run(where)
 
 
-def _refuse_without_run(where: str) -> None:
-    """Raise ``no_preprocessing_run``, with the preprocessing command."""
+def _refuse_without_run(where: str, setting: str = "common.preprocessing_run") -> None:
+    """Raise ``no_preprocessing_run`` (*setting* not set), with the preprocessing command."""
     from morphobricks_preprocessing.validation import error
 
     raise PreprocessingCheckError([
         error(
             "no_preprocessing_run",
-            f"{where} reads files only through a clean preprocessing run (v0.4), and "
-            "common.preprocessing_run is not set.",
+            f"{where} reads files only through a clean preprocessing run (v0.4), and {setting} is not set.",
             [],
             f"Run preprocessing on the experiment first: {PREPROCESSING_COMMAND}. Then set "
-            "common.preprocessing_run to its output folder (by default <experiment>_MorphoBricks_Preprocessing, "
+            f"{setting} to its output folder (by default <experiment>_MorphoBricks_Preprocessing, "
             "beside the experiment).",
         )
     ])
@@ -212,7 +211,7 @@ def open_file_run(
     if not fovs:
         raise ValueError(f"The preprocessing run in {inputs.output_folder} has no images.")
     layout = run_layout(fovs)
-    mask_type = _mask_type(config, inputs) if use_masks else None
+    mask_type = _mask_type(config.matching.mask_type, inputs, f"mode={config.mode!r}") if use_masks else None
     mask_axes = _DEFAULT_AXES
     if mask_type is not None:
         mask_axes = run_mask_layout([_record(inputs, fov, mask_type) for fov in fovs])
@@ -221,13 +220,12 @@ def open_file_run(
     return FileRun(inputs, layout, mask_type, mask_axes, statistics)
 
 
-def _mask_type(config: CellPatcherConfig, inputs: RunInputs) -> str:
-    """Return the mask type the run reads: ``matching.mask_type``, or the run's only type."""
+def _mask_type(wanted: str | None, inputs: RunInputs, reader: str) -> str:
+    """Return the mask type *reader* reads: *wanted* (``matching.mask_type``), or the run's only type."""
     types = inputs.mask_types()
-    wanted = config.matching.mask_type
     if not types:
         raise ValueError(
-            f"mode={config.mode!r} reads masks, but the preprocessing run in {inputs.output_folder} recorded none. "
+            f"{reader} reads masks, but the preprocessing run in {inputs.output_folder} recorded none. "
             f"Run preprocessing with the masks folder ({PREPROCESSING_COMMAND})."
         )
     if wanted is None and len(types) > 1:
@@ -386,3 +384,58 @@ def fov_metadata(run: FileRun, fov: Fov, config: CellPatcherConfig) -> dict:
         if config.mode == "cell" and config.common.object_set is None:
             meta["object_set"] = object_set_from_mask_type(run.mask_type)
     return meta
+
+
+def validate_image_and_mask_folders(
+    image_folder_path: str | os.PathLike,
+    mask_folder_path: str | os.PathLike,
+    *,
+    preprocessing_run: str | os.PathLike | None = None,
+    mask_type: str | None = None,
+    **removed_options: object,
+) -> dict[Path, Path]:
+    """Return the mask of every image of a clean preprocessing run, as the run paired them.
+
+    Since v0.2.0 (design v0.4 §6) CellPatcher pairs no file itself: the run is opened with
+    ``RunInputs.open`` with *image_folder_path* as the experiment root and *mask_folder_path* as
+    its masks folder (where they are now), so every image and mask is checked against the run.
+
+    Parameters
+    ----------
+    image_folder_path
+        The experiment root, where the preprocessed experiment is now.
+    mask_folder_path
+        Where the run's masks folder is now.
+    preprocessing_run
+        The run's output folder (``common.preprocessing_run`` of a file run).
+    mask_type
+        The mask type (``matching.mask_type``); None: the run's only type.
+    **removed_options
+        The matching options removed in v0.1.1, refused by name.
+
+    Returns
+    -------
+    dict
+        Each image's path mapped to its mask's path (a label image's is inside its OME-Zarr image).
+
+    Raises
+    ------
+    PreprocessingCheckError
+        ``no_preprocessing_run`` without *preprocessing_run*, or when ``RunInputs`` refuses the run.
+    ValueError
+        For a mask type the run did not record, several types without *mask_type*, or an image
+        the run recorded no mask of the type for.
+    """
+    from morphobricks_preprocessing.masks import FOLDER
+
+    refuse_removed_matching("validate_image_and_mask_folders", removed_options)
+    if preprocessing_run is None:
+        _refuse_without_run("validate_image_and_mask_folders", "preprocessing_run=")
+    inputs = open_run(preprocessing_run, experiment_root=image_folder_path, masks_root=mask_folder_path)
+    chosen = _mask_type(mask_type, inputs, "validate_image_and_mask_folders")
+    pairs = {}
+    for fov in inputs.fovs():
+        record = _record(inputs, fov, chosen)
+        root = inputs.masks_root if record["source"] == FOLDER else inputs.experiment_root
+        pairs[inputs.experiment_root / fov.relative_path] = root / str(record["path"])
+    return pairs
diff --git a/src/cellpatcher/io.py b/src/cellpatcher/io.py
index e6736d5..a8fda9d 100644
--- a/src/cellpatcher/io.py
+++ b/src/cellpatcher/io.py
@@ -954,39 +954,6 @@ def _refuse_header_problems(inventory, mask_type: str) -> None:
         raise ValueError(f"The {mask_type!r} masks cannot be used: {'; '.join(problems)}")
 
 
-def validate_image_and_mask_folders(
-    image_folder_path,
-    mask_folder_path,
-    *,
-    mask_type=None,
-    **removed_options,
-) -> dict[Path, Path]:
-    """Pair every image of a folder with exactly one mask, or raise listing every problem.
-
-    The pairing is the preprocessing brick's (:func:`pair_masks`, issue #45):
-    masks are TIFF files named ``<image name>_<mask type>.tif`` or
-    ``<mask type>/<image name>.tif`` in *mask_folder_path*. With several mask
-    types in the folder, *mask_type* says which to use.
-
-    The former matching options (``strategy``, ``mask_suffixes``,
-    ``case_sensitive``, ``ignore_unrequested_masks``) were removed in
-    v0.1.1 and are refused by name (:func:`refuse_removed_matching`).
-
-    Returns
-    -------
-    dict
-        Each image path mapped to its mask path.
-    """
-    refuse_removed_matching("validate_image_and_mask_folders", removed_options)
-    mask_folder = Path(mask_folder_path).expanduser()
-    if not mask_folder.is_dir():
-        raise ValueError(f"Folder does not exist or is not a directory: {mask_folder}")
-    image_files = discover_folder_images(image_folder_path, mask_folder_path=mask_folder)
-    if len(image_files) == 0:
-        raise ValueError("No supported image files found in image folder.")
-    return pair_masks(image_folder_path, image_files, mask_folder_path, mask_type=mask_type).masks
-
-
 def run_patching_from_folders(
     image_folder_path,
     *,
diff --git a/tests/test_end_to_end_workflows.py b/tests/test_end_to_end_workflows.py
index 9fc6cc2..6faa7dc 100644
--- a/tests/test_end_to_end_workflows.py
+++ b/tests/test_end_to_end_workflows.py
@@ -4,9 +4,10 @@
 
 from cellpatcher.cell_scan import scan_cell_patch_size
 from cellpatcher.config import CellPatcherConfig, GridConfig, RandomConfig
-from cellpatcher.io import read_array, validate_image_and_mask_folders, write_array
+from cellpatcher import validate_image_and_mask_folders
+from cellpatcher.io import read_array, write_array
 from cellpatcher.pipeline import run_patching
-from tests.helpers import make_synthetic_cell_image_and_labels
+from tests.helpers import make_synthetic_cell_image_and_labels, preprocess
 from tests.helpers import named
 
 
@@ -149,7 +150,8 @@ def test_e2e_folder_matching_to_cell_pipeline(tmp_path):
     write_array(img_path, image)
     write_array(mask_path, labels)
 
-    matched = validate_image_and_mask_folders(img_dir, mask_dir)
+    run = preprocess(img_dir, masks=mask_dir)
+    matched = validate_image_and_mask_folders(img_dir, mask_dir, preprocessing_run=run)
     assert len(matched) == 1
 
     image_arr = read_array(next(iter(matched.keys())))
diff --git a/tests/test_io.py b/tests/test_io.py
index 3cde6e1..88748c0 100644
--- a/tests/test_io.py
+++ b/tests/test_io.py
@@ -6,10 +6,10 @@
 from cellpatcher.io import (
     list_supported_files,
     read_array,
-    validate_image_and_mask_folders,
     write_array,
 )
-from tests.helpers import file_run_config, write_tiff
+from cellpatcher.file_runs import validate_image_and_mask_folders
+from tests.helpers import file_run_config, preprocess, write_tiff
 
 
 def test_list_supported_files_sorted_and_filtered(tmp_path):
@@ -55,26 +55,6 @@ def test_write_array_rejects_unsupported_extension(tmp_path):
         write_array(tmp_path / "arr.xyz", np.zeros((2, 2)))
 
 
-def test_validate_image_and_mask_folders_empty_image_folder_raises(tmp_path):
-    img_dir = tmp_path / "images"
-    mask_dir = tmp_path / "masks"
-    img_dir.mkdir()
-    mask_dir.mkdir()
-    write_array(mask_dir / "a_mask.tif", np.ones((4, 4), np.uint8))
-    with pytest.raises(ValueError, match="image folder"):
-        validate_image_and_mask_folders(img_dir, mask_dir)
-
-
-def test_validate_image_and_mask_folders_empty_mask_folder_raises(tmp_path):
-    img_dir = tmp_path / "images"
-    mask_dir = tmp_path / "masks"
-    img_dir.mkdir()
-    mask_dir.mkdir()
-    (img_dir / "a.tif").write_bytes(b"x")
-    with pytest.raises(ValueError, match="No mask in .* pairs with an image"):
-        validate_image_and_mask_folders(img_dir, mask_dir)
-
-
 # ---------------------------------------------------------------------------
 # Additional IO edge cases
 # ---------------------------------------------------------------------------
@@ -305,118 +285,78 @@ def _folders(tmp_path, images, masks):
     return img_dir, mask_dir
 
 
-def _preprocessing_pairs(img_dir, mask_dir):
-    """The preprocessing brick's own pairing of the same folders, run as the brick runs it.
+# ---------------------------------------------------------------------------
+# validate_image_and_mask_folders reads the preprocessing run's pairing (v0.2.0,
+# CP-2b): CellPatcher pairs no file itself. Its former checks (ambiguous names,
+# formats, header problems, masks inside the images) are the preprocessing run's.
+# ---------------------------------------------------------------------------
 
-    ``discover_experiment`` + ``inspect_images`` + ``find_masks`` on TIFF
-    images: ``{image name: (mask type, mask path)}``, or the error codes.
-    """
-    import morphobricks_preprocessing as mbp
-    from morphobricks_preprocessing.metadata import inspect_images
 
-    discovery = mbp.discover_experiment(img_dir)
-    images = inspect_images(img_dir, discovery.images).files
-    inventory = mbp.find_masks(mask_dir, discovery, images)
-    errors = sorted(issue.code for issue in inventory.issues if issue.is_error)
-    if errors:
-        return errors
-    return {f.image: (f.mask_type, f.path) for f in inventory.files}
+def _validated(tmp_path, images, masks):
+    """Preprocess an image folder with its masks folder; return both folders and the run."""
+    img_dir, mask_dir = _folders(tmp_path, images, masks)
+    return img_dir, mask_dir, preprocess(img_dir, masks=mask_dir)
 
 
-# ---------------------------------------------------------------------------
-# Issue #45: CellPatcher pairs images and masks with the preprocessing brick's
-# rule (find_masks), so both bricks pair the same files. Each case below was
-# paired differently by CellPatcher's former rule (exact_or_suffix with the
-# suffixes _mask/_labels/_label/_seg/_segmentation), shown in the comment.
-# ---------------------------------------------------------------------------
+def test_validate_needs_a_preprocessing_run(tmp_path):
+    from cellpatcher.statistics import PreprocessingCheckError
+
+    img_dir, mask_dir = _folders(tmp_path, ["a.tif"], ["a_cells.tif"])
+    # Old main paired the folders itself (find_masks) and returned {a.tif: a_cells.tif}.
+    with pytest.raises(PreprocessingCheckError, match=r"(?s)validate_image_and_mask_folders reads files only through a clean preprocessing run.*preprocessing_run= is not set.*morphobricks-preprocessing check"):
+        validate_image_and_mask_folders(img_dir, mask_dir)
 
 
 @pytest.mark.parametrize(
     ("masks", "mask_type", "expected"),
     [
-        # Any mask type after "<image>_": former rule: "Images with no mask match".
-        (["a_cells.tif"], None, {"a.tif": ("cells", "a_cells.tif")}),
-        # The <mask type>/ folder layout: former rule: no mask files found (no recursion).
-        (["nuclei/a.tif"], None, {"a.tif": ("nuclei", "nuclei/a.tif")}),
-        # Several types, one chosen: former rule: refused unless ignore_unrequested_masks.
-        (["a_cells.tif", "a_nuclei.tif"], "nuclei", {"a.tif": ("nuclei", "a_nuclei.tif")}),
+        (["a_cells.tif"], None, "a_cells.tif"),
+        (["nuclei/a.tif"], None, "nuclei/a.tif"),
+        (["a_cells.tif", "a_nuclei.tif"], "nuclei", "a_nuclei.tif"),
     ],
 )
-def test_pairing_is_the_preprocessing_bricks(tmp_path, masks, mask_type, expected):
-    img_dir, mask_dir = _folders(tmp_path, ["a.tif"], masks)
-    preprocessing = _preprocessing_pairs(img_dir, mask_dir)
-    assert {image: pair for image, pair in preprocessing.items() if mask_type in (None, pair[0])} == expected
-    options = {} if mask_type is None else {"mask_type": mask_type}
-    out = validate_image_and_mask_folders(img_dir, mask_dir, **options)
-    assert {image.name: mask.relative_to(mask_dir).as_posix() for image, mask in out.items()} == {
-        image: path for image, (_, path) in expected.items()
-    }
-
-
-def test_a_mask_name_starting_with_another_images_name_is_refused_like_preprocessing(tmp_path):
-    # a_seg_mask.tif is "a" + "_seg_mask" and "a_seg" + "_mask": the pairing finds it ambiguous.
-    # Since preprocessing v0.4 the image a_seg.tif ("a" + "_seg") is named as a mask of a.tif, a
-    # discovery error (image_named_as_mask), so CellPatcher refuses the folder before pairing.
-    img_dir, mask_dir = _folders(tmp_path, ["a.tif", "a_seg.tif"], ["a_mask.tif", "a_seg_mask.tif"])
-    assert _preprocessing_pairs(img_dir, mask_dir) == ["ambiguous_mask"]
-    with pytest.raises(ValueError, match=r"\[image_named_as_mask\].*a_seg.tif"):
-        validate_image_and_mask_folders(img_dir, mask_dir)
+def test_validate_returns_the_runs_pairing(tmp_path, masks, mask_type, expected):
+    img_dir, mask_dir, run = _validated(tmp_path, ["a.tif"], masks)
+    out = validate_image_and_mask_folders(img_dir, mask_dir, preprocessing_run=run, mask_type=mask_type)
+    assert out == {img_dir.resolve() / "a.tif": mask_dir.resolve() / expected}
 
 
-def test_a_mask_named_exactly_like_its_image_no_longer_pairs(tmp_path):
-    # Former rule ("exact" and the default "exact_or_suffix"): masks/a.tif paired with a.tif.
-    # Preprocessing reads it as no image's mask (a mask has a type), so it is refused, never dropped.
-    img_dir, mask_dir = _folders(tmp_path, ["a.tif"], ["a.tif"])
-    assert _preprocessing_pairs(img_dir, mask_dir) == {}
-    with pytest.raises(ValueError, match=r"\[mask_without_image\].*\(a.tif\)"):
-        validate_image_and_mask_folders(img_dir, mask_dir)
+def test_validate_reads_a_moved_experiment_where_it_is_now_and_refuses_a_changed_mask(tmp_path):
+    import shutil
 
+    from cellpatcher.statistics import PreprocessingCheckError
 
-def test_masks_that_are_not_tiff_files_are_refused_not_dropped(tmp_path):
-    # Former rule: a_mask.npy paired with a.tif. Preprocessing pairs TIFF masks only.
-    img_dir, mask_dir = tmp_path / "images", tmp_path / "masks"
-    img_dir.mkdir()
-    mask_dir.mkdir()
-    write_array(img_dir / "a.tif", np.zeros((4, 4), np.float32))
-    write_array(mask_dir / "a_mask.npy", np.ones((4, 4), np.uint16))
-    with pytest.raises(ValueError, match=r"\[mask_outside_type_folder\].*a_mask.npy"):
-        validate_image_and_mask_folders(img_dir, mask_dir)
+    img_dir, mask_dir, run = _validated(tmp_path, ["a.tif"], ["a_cells.tif"])
+    moved = tmp_path / "moved"
+    for folder in (img_dir, mask_dir):
+        shutil.copytree(folder, moved / folder.name, copy_function=shutil.copy2)
+        shutil.rmtree(folder)
+    out = validate_image_and_mask_folders(moved / "images", moved / "masks", preprocessing_run=run)
+    assert out == {(moved / "images").resolve() / "a.tif": (moved / "masks").resolve() / "a_cells.tif"}
+    write_array(moved / "masks" / "a_cells.tif", np.full((4, 4), 2, np.uint16))
+    with pytest.raises(PreprocessingCheckError, match=r"cannot be used: 1 mask changed or missing since the run: a_cells.tif"):
+        validate_image_and_mask_folders(moved / "images", moved / "masks", preprocessing_run=run)
+
+
+def test_validate_needs_a_mask_type_choice_and_a_mask_for_every_image(tmp_path):
+    img_dir, mask_dir, run = _validated(tmp_path, ["a.tif", "b.tif"], ["a_cells.tif", "b_cells.tif", "a_nuclei.tif"])
+    with pytest.raises(ValueError, match=r"recorded 2 mask types \(cells, nuclei\); set matching.mask_type"):
+        validate_image_and_mask_folders(img_dir, mask_dir, preprocessing_run=run)
+    out = validate_image_and_mask_folders(img_dir, mask_dir, preprocessing_run=run, mask_type="cells")
+    assert {image.name: mask.name for image, mask in out.items()} == {"a.tif": "a_cells.tif", "b.tif": "b_cells.tif"}
+    # An image without a mask of the chosen type is refused, not left out.
+    with pytest.raises(ValueError, match=r"recorded no 'nuclei' mask for b.tif; every image needs one"):
+        validate_image_and_mask_folders(img_dir, mask_dir, preprocessing_run=run, mask_type="nuclei")
+    with pytest.raises(ValueError, match=r"'Cells' is not a mask type of the preprocessing run"):
+        validate_image_and_mask_folders(img_dir, mask_dir, preprocessing_run=run, mask_type="Cells")
 
 
-@pytest.mark.parametrize("name", ["b.png", "b.jpg", "b.jpeg", "b.bmp", "b.gif", "b.npy", "B.PNG"])
-def test_images_in_formats_other_than_tiff_and_ome_zarr_are_refused_by_name(tmp_path, name):
-    # Owner decision of 2026-10-30 (#45): CellPatcher finds images with the preprocessing
-    # brick's discover_experiment, which reads TIFF and OME-Zarr only. The former formats
-    # (read before as images) are refused, naming the files; never skipped. Former code:
-    # paired b.<ext> with b_cells.tif and patched it.
-    img_dir, mask_dir = _folders(tmp_path, ["a.tif"], ["a_cells.tif", "b_cells.tif"])
-    write_array(img_dir / name, np.zeros((4, 4), np.uint8))
-    refusal = rf"1 image\(s\) in a format CellPatcher no longer reads: {name}\..*TIFF files .* OME-Zarr"
-    with pytest.raises(ValueError, match=refusal):
-        validate_image_and_mask_folders(img_dir, mask_dir)  # file runs read the preprocessing run's images (CP-2a)
-
-
-@pytest.mark.parametrize("name", ["b.czi", "b.nd2", "b.lif", "b.LSM", "b.webp"])
-def test_microscope_and_other_image_formats_are_refused_by_name_not_skipped(tmp_path, name):
-    # Owner decision of 2026-10-30: only TIFF and OME-Zarr images are found; other image
-    # formats are refused by file name, never skipped. Former code (this branch before the
-    # review): a .czi beside the TIFF images was silently left out of the run.
-    img_dir, mask_dir = _folders(tmp_path, ["a.tif"], ["a_cells.tif"])
-    (img_dir / name).write_bytes(b"not decoded")
-    refusal = rf"1 image\(s\) in a format CellPatcher no longer reads: {name}\..*Convert them to TIFF or OME-Zarr"
-    with pytest.raises(ValueError, match=refusal):
-        validate_image_and_mask_folders(img_dir, mask_dir)  # file runs read the preprocessing run's images (CP-2a)
-    (img_dir / name).unlink()
-    (img_dir / "notes.txt").write_text("not an image")  # other files stay ignored
-    assert validate_image_and_mask_folders(img_dir, mask_dir)
-
-def test_a_folder_run_refuses_images_beside_subfolders(tmp_path):
-    # Owner decision of 2026-10-30: a folder holding images and subfolders is refused in
-    # every brick (the preprocessing brick's "tiff_outside_leaf"). Former code: a folder run
-    # patched a.tif and ignored the subfolder.
-    img_dir, mask_dir = _folders(tmp_path, ["a.tif", "more/b.tif"], ["a_cells.tif"])
-    with pytest.raises(ValueError, match=r"\[tiff_outside_leaf\].*\(a.tif\)"):
-        validate_image_and_mask_folders(img_dir, mask_dir)  # file runs read the preprocessing run's images (CP-2a)
+def test_a_mask_the_run_did_not_pair_is_refused_not_dropped(tmp_path):
+    # masks/a.tif is no image's mask for the preprocessing run (a mask has a type): its run
+    # records no mask, so validation refuses instead of returning an empty pairing.
+    img_dir, mask_dir, run = _validated(tmp_path, ["a.tif"], ["a.tif"])
+    with pytest.raises(ValueError, match="reads masks, but the preprocessing run .* recorded none"):
+        validate_image_and_mask_folders(img_dir, mask_dir, preprocessing_run=run)
 
 
 def test_a_folder_run_refuses_a_folder_of_image_subfolders(tmp_path):
@@ -426,28 +366,6 @@ def test_a_folder_run_refuses_a_folder_of_image_subfolders(tmp_path):
         run_patching_pipeline(img_dir, config=config)
 
 
-def test_several_mask_types_need_a_choice(tmp_path):
-    img_dir, mask_dir = _folders(tmp_path, ["a.tif", "b.tif"], ["a_cells.tif", "b_cells.tif", "a_nuclei.tif"])
-    with pytest.raises(ValueError, match=r"2 mask types \(cells, nuclei\); set matching.mask_type"):
-        validate_image_and_mask_folders(img_dir, mask_dir)
-    out = validate_image_and_mask_folders(img_dir, mask_dir, mask_type="cells")
-    assert {image.name: mask.name for image, mask in out.items()} == {"a.tif": "a_cells.tif", "b.tif": "b_cells.tif"}
-    # An image without a mask of the chosen type is refused, not left out.
-    with pytest.raises(ValueError, match=r"Images with no 'nuclei' mask: b.tif"):
-        validate_image_and_mask_folders(img_dir, mask_dir, mask_type="nuclei")
-    with pytest.raises(ValueError, match=r"No mask of type 'Cells'.*cells, nuclei"):
-        validate_image_and_mask_folders(img_dir, mask_dir, mask_type="Cells")
-
-
-def test_a_mask_folder_inside_the_image_folder_is_refused_like_preprocessing(tmp_path):
-    # Former rule: accepted (the image folder listing skips subfolders).
-    img_dir = tmp_path / "images"
-    write_array(img_dir / "a.tif", np.zeros((4, 4), np.float32))
-    write_array(img_dir / "masks" / "a_mask.tif", np.ones((4, 4), np.uint16))
-    with pytest.raises(ValueError, match=r"\[masks_inside_experiment\]"):
-        validate_image_and_mask_folders(img_dir, img_dir / "masks")
-
-
 def test_the_former_matching_options_are_refused_by_name(tmp_path):
     # Removed in v0.1.1 (D86, owner decision): refused whatever their value, old defaults included.
     img_dir, mask_dir = _folders(tmp_path, ["a.tif"], ["a_mask.tif"])
@@ -461,7 +379,6 @@ def test_the_former_matching_options_are_refused_by_name(tmp_path):
         run_patching_condition_repeat_tree(img_dir, mask_root_path=mask_dir, mask_suffixes=("_mask",))
     with pytest.raises(TypeError, match=r"unknown option\(s\) \['colour'\]"):
         validate_image_and_mask_folders(img_dir, mask_dir, colour="red")
-    assert [mask.name for mask in validate_image_and_mask_folders(img_dir, mask_dir).values()] == ["a_mask.tif"]
 
 
 def test_the_former_matchers_are_gone():
@@ -472,104 +389,11 @@ def test_the_former_matchers_are_gone():
                  "LEGACY_MATCHING_DEFAULTS", "check_legacy_matching", "warn_legacy_matching_removed"):
         assert not hasattr(io, name), name
         assert name not in cellpatcher.__all__
+    # CellPatcher's own pairing, removed in v0.2.0 (CP-2b): validation reads the run's pairing.
+    for name in ("validate_image_and_mask_folders",):
+        assert not hasattr(io, name), name
 
 
-def test_validate_ignores_macos_resource_forks_in_both_folders(tmp_path):
-    img_dir, mask_dir = _folders(tmp_path, ["a.tif"], ["a_cells.tif"])
-    for folder in (img_dir, mask_dir):
-        (folder / "._a.tif").write_bytes(b"x")
-        (folder / "._a_cells.tif").write_bytes(b"x")
-    (mask_dir / "__MACOSX").mkdir()
-    (mask_dir / "__MACOSX" / "._a_cells.tif").write_bytes(b"x")
-    out = validate_image_and_mask_folders(img_dir, mask_dir)
-    assert {image.name: mask.name for image, mask in out.items()} == {"a.tif": "a_cells.tif"}
-
-
-# ---------------------------------------------------------------------------
-# find_masks' header checks (preprocessing v0.3.2): refused for the mask type
-# the run uses, ignored for the types it does not use (owner decision).
-# ---------------------------------------------------------------------------
-
-
-def _header_codes(img_dir, mask_dir):
-    import morphobricks_preprocessing as mbp
-    from morphobricks_preprocessing.metadata import inspect_images
-
-    discovery = mbp.discover_experiment(img_dir)
-    images = inspect_images(img_dir, discovery.images).files
-    inventory = mbp.find_masks(mask_dir, discovery, images)
-    return {issue.code for issue in inventory.issues if issue.is_error}
-
-
-def test_differing_planes_of_an_unused_mask_type_do_not_block_the_type_used(tmp_path):
-    # a.tif has a 2D cells mask and a nuclei mask of 3 depth slices (named Z axis):
-    # find_masks reports mask_planes_differ for a.tif, which concerns nuclei only.
-    img_dir, mask_dir = _folders(tmp_path, ["a.tif"], ["a_cells.tif"])
-    write_tiff(mask_dir / "a_nuclei.tif", np.ones((3, 4, 4), np.uint16), "ZYX")
-    assert _header_codes(img_dir, mask_dir) == {"mask_planes_differ"}
-    out = validate_image_and_mask_folders(img_dir, mask_dir, mask_type="cells")
-    assert [mask.name for mask in out.values()] == ["a_cells.tif"]
-    out = validate_image_and_mask_folders(img_dir, mask_dir, mask_type="nuclei")
-    assert [mask.name for mask in out.values()] == ["a_nuclei.tif"]
-
-
-def test_a_header_problem_is_refused_for_the_type_used_only(tmp_path):
-    # The nuclei mask has the wrong size and the mito mask is not integer: refused when
-    # used, ignored when another type is used. Former code (v0.3.1 pairing): never refused.
-    img_dir, mask_dir = _folders(tmp_path, ["a.tif"], ["a_cells.tif"])
-    write_array(mask_dir / "a_nuclei.tif", np.ones((5, 5), np.uint16))
-    write_array(mask_dir / "a_mito.tif", np.ones((4, 4), np.float32))
-    assert _header_codes(img_dir, mask_dir) == {"mask_size_mismatch", "mask_pixel_type"}
-    out = validate_image_and_mask_folders(img_dir, mask_dir, mask_type="cells")
-    assert [mask.name for mask in out.values()] == ["a_cells.tif"]
-    with pytest.raises(ValueError, match=r"'nuclei' masks cannot be used: \[mask_size_mismatch\].*\(a_nuclei.tif\)"):
-        validate_image_and_mask_folders(img_dir, mask_dir, mask_type="nuclei")
-    with pytest.raises(ValueError, match=r"'mito' masks cannot be used: \[mask_pixel_type\].*\(a_mito.tif\)"):
-        validate_image_and_mask_folders(img_dir, mask_dir, mask_type="mito")
-
-
-def test_a_mask_with_unnamed_extra_axes_is_refused_when_used(tmp_path):
-    # Three planes with no axes in the header: find_masks' mask_not_2d. Former code: read with
-    # common.mask_axes. Owner decision (v0.3.2): refused for the type used.
-    img_dir, mask_dir = _folders(tmp_path, ["a.tif"], ["a_cells.tif"])
-    write_array(mask_dir / "a_stack.tif", np.ones((3, 4, 4), np.uint16))
-    assert _header_codes(img_dir, mask_dir) == {"mask_not_2d"}
-    assert validate_image_and_mask_folders(img_dir, mask_dir, mask_type="cells")
-    with pytest.raises(ValueError, match=r"'stack' masks cannot be used: \[mask_not_2d\].*\(a_stack.tif\)"):
-        validate_image_and_mask_folders(img_dir, mask_dir, mask_type="stack")
-
-
-
-def test_pairing_uses_no_deprecated_preprocessing_name(tmp_path):
-    # preprocessing v0.3.2 deprecates morphobricks_preprocessing.SINGLE (moved to the
-    # normalization brick) and will remove it in its next version.
-    import warnings
-
-    img_dir, mask_dir = _folders(tmp_path, ["a.tif"], ["a_cells.tif"])
-    with warnings.catch_warnings():
-        warnings.filterwarnings("error", message=".*morphobricks_preprocessing", category=DeprecationWarning)
-        assert validate_image_and_mask_folders(img_dir, mask_dir)
-
-_MASK_CHANNEL_ADVICE = r"Save each label channel as its own mask type, for example <image>_cells\.tif and <image>_nuclei\.tif"
-
-
-@pytest.mark.parametrize("axes", ["CYX", None], ids=["channel_axis", "no_axes"])
-def test_a_refused_multi_axis_mask_says_how_to_save_it(tmp_path, axes):
-    # Owner decision (2026-10-30): masks with a C axis or without axis metadata are refused,
-    # and the refusal says what to do: one mask type per file, or named Z/T axes.
-    img_dir, mask_dir = _folders(tmp_path, ["a.tif"], [])
-    data = np.ones((2, 4, 4), np.uint16)
-    if axes is None:
-        write_array(mask_dir / "a_cells.tif", data)
-    else:
-        write_tiff(mask_dir / "a_cells.tif", data, axes)
-    assert _header_codes(img_dir, mask_dir) == {"mask_not_2d"}
-    with pytest.raises(ValueError, match=r"\[mask_not_2d\]") as refused:
-        validate_image_and_mask_folders(img_dir, mask_dir)
-    message = str(refused.value)
-    assert re.search(_MASK_CHANNEL_ADVICE, message)
-    assert "Z/T axes named" in message
-
 
 @pytest.mark.parametrize("mask_axes", ["CYX", "YXC"])
 def test_mask_axes_cannot_read_a_named_z_stack_as_label_channels(tmp_path, mask_axes):
@@ -583,7 +407,6 @@ def test_mask_axes_cannot_read_a_named_z_stack_as_label_channels(tmp_path, mask_
     labels = np.zeros((4, 4), np.uint16)
     labels[1:3, 1:3] = 1
     write_tiff(mask_dir / "a_cells.tif", np.stack([labels, labels]), "ZYX")
-    assert _header_codes(img_dir, mask_dir) == set()
     config = CellPatcherConfig(mode="cell")
     config.common.mask_axes = mask_axes
     config.cell.mask_channel = 0
diff --git a/tests/test_ome_zarr_images.py b/tests/test_ome_zarr_images.py
index eac3191..af77308 100644
--- a/tests/test_ome_zarr_images.py
+++ b/tests/test_ome_zarr_images.py
@@ -17,9 +17,9 @@
     list_supported_files,
     read_array,
     read_image,
-    validate_image_and_mask_folders,
     write_array,
 )
+from cellpatcher.file_runs import validate_image_and_mask_folders
 from cellpatcher.orchestration import run_patching_condition_repeat_tree
 from cellpatcher.statistics import PreprocessingUnavailableError
 from tests.helpers import (
@@ -77,11 +77,11 @@ def test_a_store_next_to_subfolders_is_a_mixed_folder(tmp_path):
 
 @needs_zarr
 def test_store_stems_match_tiff_masks(tmp_path):
-    # A real store: the mask's header is checked against the image's Y and X sizes
-    # (find_masks' mask_size_mismatch, refused for the mask type used).
+    # A real store pairs with a TIFF mask named after its stem, as the preprocessing run paired it.
     write_ngff(tmp_path / "images" / "a.ome.zarr", np.zeros((4, 4), dtype=np.uint16), "yx")
     write_array(tmp_path / "masks" / "a_mask.tif", np.zeros((4, 4), dtype=np.uint8))
-    selected = validate_image_and_mask_folders(tmp_path / "images", tmp_path / "masks")
+    run = preprocess(tmp_path / "images", masks=tmp_path / "masks")
+    selected = validate_image_and_mask_folders(tmp_path / "images", tmp_path / "masks", preprocessing_run=run)
     assert {k.name: v.name for k, v in selected.items()} == {"a.ome.zarr": "a_mask.tif"}
 
 

From 470b58eefffaa304aaa85ce5ca2ef63600004cc9 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 2 Nov 2026 07:45:00 +0000
Subject: [PATCH 03/23] CP-2b: remove CellPatcher's own pairing (pair_masks),
 now unused

Pure removal: io.pair_masks, MaskPairing, the find_masks header-issue
filtering (_refuse_header_problems and its codes), MASK_CHANNEL_HELP,
io.source_relative_path and io.discover_folder_images had no caller left once
validate_image_and_mask_folders read the preprocessing run's pairing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G3qp9AxjpGPw9xfWAUJNqc
---
 src/cellpatcher/config.py |  13 +--
 src/cellpatcher/io.py     | 239 --------------------------------------
 tests/test_file_runs.py   |   2 +-
 tests/test_io.py          |   2 +-
 4 files changed, 8 insertions(+), 248 deletions(-)

diff --git a/src/cellpatcher/config.py b/src/cellpatcher/config.py
index dfb0f39..56b8255 100644
--- a/src/cellpatcher/config.py
+++ b/src/cellpatcher/config.py
@@ -500,16 +500,15 @@ def __post_init__(self) -> None:
 class MatchConfig:
     """Which masks to pair with the images.
 
-    Images and masks are paired with the MorphoBricks preprocessing brick's
-    rule (``morphobricks_preprocessing.find_masks``, issue #45), so every
-    brick pairs the same files: a mask is a TIFF file
+    Images and masks are paired by the preprocessing run (its ``find_masks``,
+    design v0.4 §6), so every brick reads the same pairs: a mask is a TIFF file
     ``<mask type>/<image's folders>/<image name>.tif`` or
-    ``<image's folders>/<image name>_<mask type>.tif`` in the mask folder
-    (:func:`~cellpatcher.io.pair_masks`).
+    ``<image's folders>/<image name>_<mask type>.tif`` in the mask folder, or
+    an OME-Zarr image's label image (its type is its name).
 
     ``mask_type`` names the mask type to use (``"cells"`` for
-    ``img_cells.tif`` or ``cells/img.tif``). None (default) uses the only
-    type in the mask folder, and refuses a folder holding several.
+    ``img_cells.tif`` or ``cells/img.tif``). None (default) uses the run's only
+    type, and refuses a run holding several.
 
     The former options ``strategy``, ``mask_suffixes``, ``case_sensitive``
     and ``ignore_unrequested_masks`` were removed in v0.1.1: given here, set
diff --git a/src/cellpatcher/io.py b/src/cellpatcher/io.py
index a8fda9d..294a9a9 100644
--- a/src/cellpatcher/io.py
+++ b/src/cellpatcher/io.py
@@ -271,26 +271,6 @@ def discover_images(root_path, *, mask_folder_path=None):
     return result
 
 
-def discover_folder_images(image_folder_path, *, mask_folder_path=None) -> list[Path]:
-    """The images of a single image folder (a folder run), found by :func:`discover_images`.
-
-    The folder must hold its images directly. A folder holding subfolders
-    of images is a tree: run it with
-    :func:`~cellpatcher.orchestration.run_patching_condition_repeat_tree`.
-    Returns an empty list when the folder holds no image.
-    """
-    folder = Path(image_folder_path).expanduser()
-    result = discover_images(folder, mask_folder_path=mask_folder_path)
-    nested = [leaf.relative_path for leaf in result.leaves if leaf.relative_path != "."]
-    if nested:
-        raise ValueError(
-            f"The image folder '{folder}' holds its images in subfolders ({', '.join(nested[:10])}"
-            f"{', ...' if len(nested) > 10 else ''}). A folder run reads the images directly in one "
-            "folder; run a tree of condition and repeat folders with run_patching_condition_repeat_tree."
-        )
-    return sorted(folder / path for path in result.images)
-
-
 def discover_condition_repeat_folders(
     root_path,
     *,
@@ -326,7 +306,6 @@ def discover_condition_repeat_folders(
 
     When *mask_root_path* is given, the same leaf path is mirrored under it
     for each leaf's ``mask_folder``; its existence is not checked here.
-    The pairing itself reads the whole mask root (:func:`pair_masks`).
 
     *supported_extensions* is no longer supported: the images are the
     brick's (TIFF and OME-Zarr). Any value other than None is refused.
@@ -602,48 +581,6 @@ def refuse_removed_matching(where: str, options) -> None:
     )
 
 
-@dataclass(frozen=True)
-class MaskPairing:
-    """The mask of every image, from the preprocessing brick's pairing (:func:`pair_masks`).
-
-    Attributes
-    ----------
-    mask_type
-        The mask type used: its folder name, or the part of the mask's name
-        after ``<image name>_``.
-    masks
-        Each image path (as given) mapped to its mask file.
-    """
-
-    mask_type: str
-    masks: dict
-
-
-# find_masks issue codes about a mask's header (axes, shape, pixel type, planes),
-# not about which image it belongs to. They are refused for the masks of the
-# type the run uses and ignored for the other types, which are never read
-# (owner decision, preprocessing v0.3.2). CellPatcher still checks each mask
-# against its image when it reads it.
-_MASK_HEADER_CODES = frozenset(
-    {"unreadable_mask", "mask_not_2d", "mask_size_mismatch", "mask_pixel_type", "mask_planes_differ"}
-)
-_MASK_PLANES_CODE = "mask_planes_differ"
-
-# Reported per mask type; CellPatcher checks the type it uses itself.
-_MASK_MISSING_CODE = "mask_missing"
-_MASK_NOT_2D_CODE = "mask_not_2d"
-
-# What to do with a mask file that has a channel (C) axis or unnamed extra
-# axes, both refused (owner decision of 2026-10-30): no axis is guessed, and
-# common.mask_axes cannot declare a C axis for mask files. One mask type per file.
-MASK_CHANNEL_HELP = (
-    "Mask files may hold only Y and X, plus the Z/T axes their metadata names; a channel (C) axis "
-    "or an axis without a name is never guessed. Save each label channel as its own mask type, for "
-    "example <image>_cells.tif and <image>_nuclei.tif (or cells/<image>.tif and nuclei/<image>.tif), "
-    "and choose one with matching.mask_type; save a stack of Z slices or time points with its Z/T "
-    "axes named (an ImageJ hyperstack or an OME-TIFF)."
-)
-
 MASK_TRANSPOSE_HELP = (
     "To fix the masks, save each one with Y before X, as its image is read: transpose its last "
     "two axes, for example tifffile.imwrite(path, numpy.swapaxes(mask, -1, -2), "
@@ -771,51 +708,6 @@ def refuse_mask_header_axes(mask_paths: Iterable[str | os.PathLike], mask_axes:
     refuse_transposed_mask_axes(mask_axes)  # a header naming X before Y, declared as named
 
 
-def source_relative_path(image_path, experiment_root) -> str:
-    """Path of *image_path* relative to *experiment_root*, with ``/`` separators.
-
-    Built from where the image sits in the folder tree, so it matches the
-    preprocessing brick's ``source_relative_path`` (``control/img.tif`` for an
-    image directly in ``control/``). Like the brick, which walks the tree
-    following links, a linked image or folder keeps its path under the root
-    (the link's, not its target's). A path that is not under the root as
-    written is compared by real locations.
-    """
-    root = Path(experiment_root).expanduser()
-    image = Path(image_path).expanduser()
-    try:
-        # Discovery builds every image path from the root, so this holds for
-        # folder and tree runs; resolving would follow links out of the tree.
-        return image.absolute().relative_to(root.absolute()).as_posix()
-    except ValueError:  # e.g. the same folder written through a link
-        pass
-    try:
-        return image.resolve().relative_to(root.resolve()).as_posix()
-    except ValueError as exc:
-        raise ValueError(f"Image '{image_path}' is not inside the experiment root '{root}'.") from exc
-
-
-def _discovery_of(experiment_root, relative_paths):
-    """The preprocessing ``DiscoveryResult`` of images CellPatcher has already discovered.
-
-    One leaf per image folder, holding its images' relative paths. The labels
-    are the folder names, ``single`` for missing levels; ``find_masks`` reads
-    only the folders and image names.
-    """
-    from morphobricks_preprocessing import DiscoveryResult, LeafFolder
-
-    by_folder: dict[str, list[str]] = {}
-    for relative in relative_paths:
-        folder = relative.rsplit("/", 1)[0] if "/" in relative else "."
-        by_folder.setdefault(folder, []).append(relative)
-    leaves = []
-    for folder, images in sorted(by_folder.items()):
-        names = () if folder == "." else tuple(folder.split("/"))
-        labels = (names + (SINGLE,) * 3)[:3]
-        leaves.append(LeafFolder(folder, *labels, tuple(sorted(images))))
-    return DiscoveryResult(root=Path(experiment_root).expanduser().resolve(), leaves=tuple(leaves))
-
-
 def _issue_text(issue) -> str:
     paths = list(issue.paths)
     listed = f" ({', '.join(paths[:10])}{', ...' if len(paths) > 10 else ''})" if paths else ""
@@ -823,137 +715,6 @@ def _issue_text(issue) -> str:
     return f"[{issue.code}] {issue.message.rstrip('.')}{listed}.{action}"
 
 
-def pair_masks(experiment_root, image_files, mask_folder_path, *, mask_type=None) -> MaskPairing:
-    """Pair every image with its mask using the preprocessing brick's pairing, or raise.
-
-    CellPatcher does not pair images and masks itself: the mask folder is
-    read by ``morphobricks_preprocessing.find_masks`` (decision of
-    2026-10-30, issue #45), so CellPatcher, the preprocessing brick and the
-    bricks that use its discovery pair the same files. A mask is a TIFF file
-    named ``<mask type>/<image's folders>/<image name>.tif`` or
-    ``<image's folders>/<image name>_<mask type>.tif``, where the image's
-    folders are its path below *experiment_root* and the image name is its
-    ``position_id`` (D85); names are compared ignoring case.
-
-    Refused, never resolved by a guess:
-
-    - every problem ``find_masks`` reports about the pairing, including a
-      mask that could belong to two images or two types (``ambiguous_mask``),
-      a file in the mask folder that pairs with no image
-      (``mask_without_image``, ``mask_outside_type_folder``: never silently
-      left out) and a mask folder inside the image root;
-    - several mask types when *mask_type* is None, and a *mask_type* that was
-      not found;
-    - an image without a mask of the type used.
-
-    - a header problem ``find_masks`` reports about a mask of the type used
-      (``_MASK_HEADER_CODES``: ``unreadable_mask``, ``mask_not_2d``,
-      ``mask_size_mismatch``, ``mask_pixel_type``; ``mask_planes_differ``
-      between masks of the type used). The same problems of masks of other
-      types are ignored: those masks are never read.
-
-    Each mask is also checked against its image when it is read.
-
-    Parameters
-    ----------
-    experiment_root
-        The folder the images' paths are relative to: the image folder of a
-        folder run, the image root of a tree run.
-    image_files
-        The images to pair, all under *experiment_root*.
-    mask_folder_path
-        The mask folder, mirroring *experiment_root*'s folders; it may not be
-        inside *experiment_root*.
-    mask_type
-        The mask type to use (``config.matching.mask_type``), or None when the
-        mask folder holds exactly one type.
-    """
-    from morphobricks_preprocessing import find_masks
-    from morphobricks_preprocessing.masks import FOLDER
-    from morphobricks_preprocessing.metadata import inspect_images
-
-    if mask_type is not None and (not isinstance(mask_type, str) or not mask_type.strip()):
-        raise ValueError(f"mask_type must be None or a non-empty name; got {mask_type!r}.")
-    image_files = [Path(image) for image in image_files]
-    relative = {image: source_relative_path(image, experiment_root) for image in image_files}
-    discovery = _discovery_of(experiment_root, relative.values())
-    # The images' headers give the Y and X sizes each mask's header is checked against.
-    images = inspect_images(Path(experiment_root).expanduser(), list(relative.values())).files
-    inventory = find_masks(Path(mask_folder_path).expanduser(), discovery, images)
-
-    problems = [
-        _issue_text(issue)
-        for issue in inventory.issues
-        if issue.code not in _MASK_HEADER_CODES and issue.code != _MASK_MISSING_CODE
-    ]
-    if problems:
-        raise ValueError(f"Images and masks cannot be paired: {'; '.join(problems)}. {MASK_LAYOUT_HELP}")
-    # The mask folder's files only: label images (design v0.4 §2) need mask_source="ngff_labels".
-    folder_files = [f for f in inventory.files if f.source == FOLDER]
-    types = sorted({f.mask_type for f in folder_files})
-    if not types:
-        raise ValueError(f"No mask in '{mask_folder_path}' pairs with an image. {MASK_LAYOUT_HELP}")
-    if mask_type is None:
-        if len(types) > 1:
-            raise ValueError(
-                f"The mask folder holds {len(types)} mask types ({', '.join(types)}); set "
-                "matching.mask_type (or mask_type=) to the one to use. A type is never chosen for you."
-            )
-        mask_type = types[0]
-    elif mask_type not in types:
-        raise ValueError(
-            f"No mask of type {mask_type!r} pairs with an image; the mask folder holds the types "
-            f"{', '.join(types)} (names are compared exactly; an OME-Zarr image's own label image is read "
-            f"with common.mask_source='ngff_labels'). {MASK_LAYOUT_HELP}"
-        )
-    _refuse_header_problems(inventory, mask_type)
-    by_image = {f.image: f for f in folder_files if f.mask_type == mask_type}
-    missing = [relative[image] for image in image_files if relative[image] not in by_image]
-    if missing:
-        raise ValueError(
-            f"Images with no {mask_type!r} mask: {', '.join(missing[:10])}"
-            f"{', ...' if len(missing) > 10 else ''} ({len(missing)} of {len(image_files)}). {MASK_LAYOUT_HELP}"
-        )
-    folder = Path(mask_folder_path).expanduser()
-    return MaskPairing(mask_type, {image: folder / by_image[relative[image]].path for image in image_files})
-
-
-def _refuse_header_problems(inventory, mask_type: str) -> None:
-    """Refuse the header problems ``find_masks`` reports about masks of *mask_type*, the type used.
-
-    Its ``mask_planes_differ`` compares every mask of an image, whatever its
-    type; it is recomputed between the masks of *mask_type* only, so a mask
-    type the run does not use never blocks it.
-    """
-    used = [f for f in inventory.files if f.mask_type == mask_type]
-    used_paths = {f.path for f in used}
-    problems = []
-    for issue in inventory.issues:
-        if issue.code not in _MASK_HEADER_CODES or issue.code == _MASK_PLANES_CODE:
-            continue
-        paths = sorted(path for path in issue.paths if path in used_paths)
-        if paths:
-            text = f"[{issue.code}] {issue.message.rstrip('.')} ({', '.join(paths[:10])}). {issue.action}"
-            if issue.code == _MASK_NOT_2D_CODE:
-                text = f"{text.rstrip()} {MASK_CHANNEL_HELP}"
-            problems.append(text)
-    by_image: dict[str, list] = {}
-    for mask in used:
-        if mask.axes:
-            by_image.setdefault(mask.image, []).append(mask)
-    differ = sorted(
-        mask.path
-        for masks in by_image.values()
-        if len({tuple(m.planes.items()) for m in masks}) > 1
-        for mask in masks
-    )
-    if differ:
-        planes = next(issue for issue in inventory.issues if issue.code == _MASK_PLANES_CODE)
-        problems.append(f"[{_MASK_PLANES_CODE}] {planes.message.rstrip('.')} ({', '.join(differ[:10])}). {planes.action}")
-    if problems:
-        raise ValueError(f"The {mask_type!r} masks cannot be used: {'; '.join(problems)}")
-
-
 def run_patching_from_folders(
     image_folder_path,
     *,
diff --git a/tests/test_file_runs.py b/tests/test_file_runs.py
index e258abb..fb20bce 100644
--- a/tests/test_file_runs.py
+++ b/tests/test_file_runs.py
@@ -143,7 +143,7 @@ def test_file_runs_read_through_run_inputs_only(tmp_path, monkeypatch):
     def refused(*args, **kwargs):
         raise AssertionError("CellPatcher read or paired a file itself")
 
-    for module, name in ((cellpatcher.io, "pair_masks"), (cellpatcher.io, "read_image"), (cellpatcher.io, "read_array"),
+    for module, name in ((cellpatcher.io, "read_image"), (cellpatcher.io, "read_array"),
                          (cellpatcher.io, "refuse_image_header_axes"), (cellpatcher.io, "discover_images"),
                          (cellpatcher.planes, "read_file_plane")):
         monkeypatch.setattr(module, name, refused)
diff --git a/tests/test_io.py b/tests/test_io.py
index 88748c0..5264780 100644
--- a/tests/test_io.py
+++ b/tests/test_io.py
@@ -390,7 +390,7 @@ def test_the_former_matchers_are_gone():
         assert not hasattr(io, name), name
         assert name not in cellpatcher.__all__
     # CellPatcher's own pairing, removed in v0.2.0 (CP-2b): validation reads the run's pairing.
-    for name in ("validate_image_and_mask_folders",):
+    for name in ("validate_image_and_mask_folders", "pair_masks", "MaskPairing", "discover_folder_images"):
         assert not hasattr(io, name), name
 
 

From 569cd104944f69ad511e0cce9c92ce7358d05eac Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 2 Nov 2026 07:46:51 +0000
Subject: [PATCH 04/23] CP-2b: sort the imports the pairing change touched
 (ruff I001, F401)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G3qp9AxjpGPw9xfWAUJNqc
---
 src/cellpatcher/file_runs.py       | 6 +++++-
 tests/test_end_to_end_workflows.py | 5 ++---
 tests/test_io.py                   | 3 +--
 tests/test_ome_zarr_images.py      | 2 +-
 4 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/src/cellpatcher/file_runs.py b/src/cellpatcher/file_runs.py
index c1bc178..9c54050 100644
--- a/src/cellpatcher/file_runs.py
+++ b/src/cellpatcher/file_runs.py
@@ -26,7 +26,11 @@
 from typing import TYPE_CHECKING
 
 from cellpatcher.ids import object_set_from_mask_type, validate_object_set
-from cellpatcher.io import SINGLE_CONDITION_LABEL, ConditionRepeatFolder, refuse_removed_matching
+from cellpatcher.io import (
+    SINGLE_CONDITION_LABEL,
+    ConditionRepeatFolder,
+    refuse_removed_matching,
+)
 from cellpatcher.normalization import (
     CSV_SCOPES,
     check_image_type,
diff --git a/tests/test_end_to_end_workflows.py b/tests/test_end_to_end_workflows.py
index 6faa7dc..9278d5b 100644
--- a/tests/test_end_to_end_workflows.py
+++ b/tests/test_end_to_end_workflows.py
@@ -2,13 +2,12 @@
 
 import numpy as np
 
+from cellpatcher import validate_image_and_mask_folders
 from cellpatcher.cell_scan import scan_cell_patch_size
 from cellpatcher.config import CellPatcherConfig, GridConfig, RandomConfig
-from cellpatcher import validate_image_and_mask_folders
 from cellpatcher.io import read_array, write_array
 from cellpatcher.pipeline import run_patching
-from tests.helpers import make_synthetic_cell_image_and_labels, preprocess
-from tests.helpers import named
+from tests.helpers import make_synthetic_cell_image_and_labels, named, preprocess
 
 
 def test_e2e_cell_scan_mask_resize_export(tmp_path):
diff --git a/tests/test_io.py b/tests/test_io.py
index 5264780..8a0c77e 100644
--- a/tests/test_io.py
+++ b/tests/test_io.py
@@ -1,14 +1,13 @@
-import re
 
 import numpy as np
 import pytest
 
+from cellpatcher.file_runs import validate_image_and_mask_folders
 from cellpatcher.io import (
     list_supported_files,
     read_array,
     write_array,
 )
-from cellpatcher.file_runs import validate_image_and_mask_folders
 from tests.helpers import file_run_config, preprocess, write_tiff
 
 
diff --git a/tests/test_ome_zarr_images.py b/tests/test_ome_zarr_images.py
index af77308..3d986ff 100644
--- a/tests/test_ome_zarr_images.py
+++ b/tests/test_ome_zarr_images.py
@@ -11,6 +11,7 @@
 import pytest
 
 from cellpatcher.config import CellPatcherConfig, GridConfig
+from cellpatcher.file_runs import validate_image_and_mask_folders
 from cellpatcher.io import (
     conform_axes,
     discover_condition_repeat_folders,
@@ -19,7 +20,6 @@
     read_image,
     write_array,
 )
-from cellpatcher.file_runs import validate_image_and_mask_folders
 from cellpatcher.orchestration import run_patching_condition_repeat_tree
 from cellpatcher.statistics import PreprocessingUnavailableError
 from tests.helpers import (

From 786477a4d67da980425d5ec2227b72db92da06ca Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 2 Nov 2026 07:52:52 +0000
Subject: [PATCH 05/23] CP-2b: run_config.json version 2 records the
 preprocessing run and its manifest SHA-256

run_config.json now has run_config_version 2 and, when a preprocessing run
was read, a preprocessing section: the run's folder, the SHA-256 of its
run_manifest.json taken when this call opened it (refused if the manifest
changed while it was opened), and for a folder or tree run the array layout
built from the run's recorded roles. A file run no longer records
common.image_axes, mask_axes or its labels (they are the run's, not settings),
so its run_config.json loads back as a config a file run accepts; before, the
layout recorded as image_axes was refused by the migration check.

load_config and the exported-patch readers refuse any run_config_version but
1 (no version: before v0.2.0, or a plain config file) and 2.

run_config_data and the config reader move to cellpatcher.run_config_file
(pipeline.py and orchestration.py shrink).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G3qp9AxjpGPw9xfWAUJNqc
---
 src/cellpatcher/delivery.py        |  20 +---
 src/cellpatcher/file_runs.py       |   3 +-
 src/cellpatcher/orchestration.py   |  42 +-------
 src/cellpatcher/pipeline.py        |  22 +---
 src/cellpatcher/run_config_file.py | 160 +++++++++++++++++++++++++++++
 src/cellpatcher/run_open.py        |  17 ++-
 src/cellpatcher/run_session.py     |  25 ++++-
 tests/test_file_runs.py            |  46 ++++++++-
 8 files changed, 251 insertions(+), 84 deletions(-)
 create mode 100644 src/cellpatcher/run_config_file.py

diff --git a/src/cellpatcher/delivery.py b/src/cellpatcher/delivery.py
index 165848c..1648f84 100644
--- a/src/cellpatcher/delivery.py
+++ b/src/cellpatcher/delivery.py
@@ -43,6 +43,7 @@
 from cellpatcher.normalization import PatchNormalization, parameters_from_row
 from cellpatcher.planes import apply_plane_choice, patch_plane_choice, read_file_plane, select_mask_plane
 from cellpatcher.resize import resize_patch
+from cellpatcher.run_config_file import delivery_config
 
 
 def patch_axes(config, patch) -> str:
@@ -172,7 +173,7 @@ def _normalize_on_load(row: Mapping, array, run_config: Mapping | None) -> np.nd
     patch = _row_patch(row)
     clip = settings.get("clip")
     return PatchNormalization(parameters).apply(
-        array, patch_axes(_run_config(run_config), patch), clip=tuple(clip) if clip else None
+        array, patch_axes(delivery_config(run_config, "run_config.json"), patch), clip=tuple(clip) if clip else None
     )
 
 
@@ -268,20 +269,3 @@ def number(name):
         t=number("t"),
         c=number("c"),
     )
-
-
-def _run_config(data: Mapping):
-    """The config of a ``run_config.json``, for the axes of its patches.
-
-    A run normalized at a scope removed since (``condition``,
-    ``technical_repeat``; normalization brick N29) still loads here: its
-    parameters are in ``patches.csv``, and only the patch axes are needed.
-    """
-    from cellpatcher.config import REMOVED_NORMALIZATION_SCOPES
-    from cellpatcher.orchestration import _config_from_dict
-
-    data = dict(data)
-    normalization = data.get("normalization")
-    if isinstance(normalization, Mapping) and normalization.get("scope") in REMOVED_NORMALIZATION_SCOPES:
-        data["normalization"] = {**normalization, "scope": "image"}
-    return _config_from_dict(data)
diff --git a/src/cellpatcher/file_runs.py b/src/cellpatcher/file_runs.py
index 9c54050..76349c1 100644
--- a/src/cellpatcher/file_runs.py
+++ b/src/cellpatcher/file_runs.py
@@ -54,7 +54,7 @@
     run_layout,
     run_mask_layout,
 )
-from cellpatcher.run_session import keep_in_session
+from cellpatcher.run_session import keep_in_session, remember
 from cellpatcher.statistics import (
     PlaneStatistics,
     PreprocessingCheckError,
@@ -211,6 +211,7 @@ def open_file_run(
     refuse_file_run_settings(config, where)
     check_config_identity(config)
     inputs = open_run(config.common.preprocessing_run, experiment_root=experiment_root, masks_root=masks_root)
+    remember("file_run", config.common.preprocessing_run, "folder or tree run")
     fovs = inputs.fovs()
     if not fovs:
         raise ValueError(f"The preprocessing run in {inputs.output_folder} has no images.")
diff --git a/src/cellpatcher/orchestration.py b/src/cellpatcher/orchestration.py
index e8107f3..b6835a5 100644
--- a/src/cellpatcher/orchestration.py
+++ b/src/cellpatcher/orchestration.py
@@ -9,23 +9,12 @@
 from typing import Any
 
 from cellpatcher._deprecation import accept_deprecated_repeat
-from cellpatcher.config import (
-    CellConfig,
-    CellPatcherConfig,
-    CommonConfig,
-    ExportConfig,
-    ExtractionConfig,
-    FilterConfig,
-    GridConfig,
-    MatchConfig,
-    NormalizationConfig,
-    RandomConfig,
-    WholeFOVConfig,
-)
+from cellpatcher.config import CellPatcherConfig
 from cellpatcher.file_runs import FileRun, leaves, masks_used, open_file_run, patch_fovs, run_config_for
 from cellpatcher.io import SINGLE_TECHNICAL_REPEAT_LABEL, ConditionRepeatFolder, refuse_removed_matching
 from cellpatcher.export import IMAGE_TABLE_FILENAME, save_image_table_csv, save_metadata_csv
-from cellpatcher.pipeline import RUN_CONFIG_FILENAME, PatchingResult, run_config_data
+from cellpatcher.pipeline import RUN_CONFIG_FILENAME, PatchingResult
+from cellpatcher.run_config_file import config_from_dict, run_config_data
 from cellpatcher.run_session import statistics_session
 
 # Sections always written regardless of mode
@@ -252,30 +241,7 @@ def load_config(path) -> CellPatcherConfig:
     CellPatcherConfig
         A fully reconstructed config instance.
     """
-    return _config_from_dict(json.loads(Path(path).read_text()))
-
-
-def _config_from_dict(data: dict) -> CellPatcherConfig:
-    """Build a config from the data of a config or ``run_config.json`` file (extra keys are ignored)."""
-    # Each section is reconstructed only if present in the file (a
-    # mode-specific save omits irrelevant sections), otherwise it falls
-    # back to that section's own defaults.
-    return CellPatcherConfig(
-        mode=data.get("mode", "cell"),
-        common=CommonConfig(**data["common"]) if "common" in data else CommonConfig(),
-        cell=CellConfig(**data["cell"]) if "cell" in data else CellConfig(),
-        random=RandomConfig(**data["random"]) if "random" in data else RandomConfig(),
-        grid=GridConfig(**data["grid"]) if "grid" in data else GridConfig(),
-        whole_fov=WholeFOVConfig(**data["whole_fov"]) if "whole_fov" in data else WholeFOVConfig(),
-        filters=FilterConfig(**data["filters"]) if "filters" in data else FilterConfig(),
-        export=ExportConfig(**data["export"]) if "export" in data else ExportConfig(),
-        extraction=ExtractionConfig(**data["extraction"]) if "extraction" in data else ExtractionConfig(),
-        matching=MatchConfig(**data["matching"]) if "matching" in data else MatchConfig(),
-        # A run_config.json written before normalization existed means it was off.
-        normalization=(
-            NormalizationConfig(**data["normalization"]) if "normalization" in data else NormalizationConfig()
-        ),
-    )
+    return config_from_dict(json.loads(Path(path).read_text()), str(path))
 
 
 def run_patching_pipeline(
diff --git a/src/cellpatcher/pipeline.py b/src/cellpatcher/pipeline.py
index b33f963..aa1d413 100644
--- a/src/cellpatcher/pipeline.py
+++ b/src/cellpatcher/pipeline.py
@@ -1,7 +1,7 @@
 import json
 from collections import Counter
 from contextvars import ContextVar
-from dataclasses import asdict, dataclass, field, replace
+from dataclasses import dataclass, field, replace
 from pathlib import Path
 
 import numpy as np
@@ -31,11 +31,10 @@
     Normalizer,
     finish_patch_groups,
     resolved_patch_region,
-    normalization_inputs,
-    run_settings,
     split_channel_normalization,
     validate_normalization,
 )
+from cellpatcher.run_config_file import run_config_data
 from cellpatcher.run_session import one_session
 from cellpatcher.statistics import _preprocessing
 from cellpatcher.planes import iter_image_planes, plane_choices, splits_planes
@@ -555,23 +554,6 @@ def _normalize(config: CellPatcherConfig, image_list, masks, image_metadata, pat
     )
 
 
-def run_config_data(config: CellPatcherConfig) -> dict:
-    """The ``run_config.json`` content: the config, plus the normalization brick's records.
-
-    ``normalization_inputs`` when a CSV is used, and ``normalization_settings``
-    (the brick's ``NormalizationSettings.to_dict()``) for the image and patch
-    scopes.
-    """
-    data = asdict(config)
-    inputs = normalization_inputs(config)
-    if inputs is not None:
-        data["normalization_inputs"] = inputs
-    settings = run_settings(config)
-    if settings is not None:
-        data["normalization_settings"] = settings
-    return data
-
-
 def _build_result(
     config: CellPatcherConfig, image_list, patches: list[PatchRegion], masks=None, image_metadata=None,
     fraction_masks=None,
diff --git a/src/cellpatcher/run_config_file.py b/src/cellpatcher/run_config_file.py
new file mode 100644
index 0000000..69ce3ec
--- /dev/null
+++ b/src/cellpatcher/run_config_file.py
@@ -0,0 +1,160 @@
+"""The ``run_config.json`` written beside ``patches.csv``, and reading it back (layer: orchestration).
+
+Version 2 (CellPatcher v0.2.0, CP-2b; design v0.4 §6, §8) adds ``run_config_version`` and,
+when a preprocessing run was read, a ``preprocessing`` section:
+
+- ``run``: the run's output folder, as given (``common.preprocessing_run``, or the folder of
+  ``normalization.plane_histograms`` for a CSV scope of ``run_patching``);
+- ``manifest_sha256``: the SHA-256 of its ``run_manifest.json`` when this call opened it, which
+  names the run's images, masks, roles and table exactly;
+- for a folder or tree run, ``layout``: the order of the arrays CellPatcher built from the roles
+  the run recorded (T, Z, C, then Y, X; ``image`` and ``mask``), which delivers exported patches.
+
+A folder or tree run does not record ``common.image_axes``, ``mask_axes`` or the labels: they
+are the run's, not settings (each patch's labels are in ``patches.csv``), so the file loads back
+as a config a file run accepts. Version 1 is a ``run_config.json`` written before v0.2.0, or a
+config file without a version (:func:`cellpatcher.save_default_config`). Any other version is
+refused by every reader.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any
+
+from cellpatcher.config import (
+    REMOVED_NORMALIZATION_SCOPES,
+    CellConfig,
+    CellPatcherConfig,
+    CommonConfig,
+    ExportConfig,
+    ExtractionConfig,
+    FilterConfig,
+    GridConfig,
+    MatchConfig,
+    NormalizationConfig,
+    RandomConfig,
+    WholeFOVConfig,
+)
+from cellpatcher.normalization import CSV_SCOPES, normalization_inputs, run_settings
+from cellpatcher.run_session import recalled
+
+RUN_CONFIG_VERSION = 2
+READ_VERSIONS = (1, RUN_CONFIG_VERSION)
+
+# The common settings a folder or tree run takes from the preprocessing run, not recorded.
+_RUN_SETTINGS = ("image_axes", "mask_axes", "condition", "biological_repeat", "technical_repeat")
+
+
+def run_config_data(config: CellPatcherConfig) -> dict:
+    """Return the ``run_config.json`` content of a run with *config* (version 2).
+
+    The config, ``run_config_version``, the ``preprocessing`` section when a run was read
+    (see the module), and the normalization brick's records: ``normalization_inputs`` when a
+    CSV is used, ``normalization_settings`` when normalization is on.
+
+    Raises
+    ------
+    RuntimeError
+        If the preprocessing run read was not opened in this call (an internal error: its
+        manifest's SHA-256 is recorded when it is opened).
+    """
+    data: dict[str, Any] = {"run_config_version": RUN_CONFIG_VERSION, **asdict(config)}
+    preprocessing = _preprocessing_section(config)
+    if preprocessing is not None:
+        data["preprocessing"] = preprocessing
+    if preprocessing is not None and "layout" in preprocessing:
+        for name in _RUN_SETTINGS:
+            data["common"].pop(name)
+    inputs = normalization_inputs(config)
+    if inputs is not None:
+        data["normalization_inputs"] = inputs
+    settings = run_settings(config)
+    if settings is not None:
+        data["normalization_settings"] = settings
+    return data
+
+
+def _preprocessing_section(config: CellPatcherConfig) -> dict | None:
+    """Return the ``preprocessing`` section: the run read, its manifest's SHA-256 and a file run's layout."""
+    common, settings = config.common, config.normalization
+    file_run = common.preprocessing_run is not None and recalled("file_run", common.preprocessing_run) is not None
+    if file_run:
+        run = common.preprocessing_run
+    elif settings.enabled and settings.scope in CSV_SCOPES and settings.plane_histograms is not None:
+        run = str(Path(settings.plane_histograms).expanduser().parent)
+    else:
+        return None
+    sha256 = recalled("manifest_sha256", run)
+    if sha256 is None:
+        raise RuntimeError(f"The preprocessing run {run} was not opened in this call, so it cannot be recorded.")
+    section: dict[str, Any] = {"run": str(run), "manifest_sha256": sha256}
+    if file_run:
+        section["layout"] = {"image": common.image_axes, "mask": common.mask_axes}
+    return section
+
+
+def run_config_version(data: Mapping, where: str) -> int:
+    """Return the version of a config or ``run_config.json`` content, refusing one this CellPatcher cannot read.
+
+    Raises
+    ------
+    ValueError
+        For a ``run_config_version`` other than 1 or 2.
+    """
+    version = data.get("run_config_version", 1)
+    if type(version) is not int or version not in READ_VERSIONS:
+        raise ValueError(
+            f"{where} has run_config_version {version!r}; this CellPatcher reads versions "
+            f"{', '.join(map(str, READ_VERSIONS))}. It was written by another CellPatcher version: read it with "
+            "that version, or run the patching again."
+        )
+    return version
+
+
+def config_from_dict(data: Mapping, where: str = "The config") -> CellPatcherConfig:
+    """Build a config from the content of a config or ``run_config.json`` file (other keys are ignored).
+
+    Each section is built only when present (a mode-specific save leaves others out), otherwise
+    from its defaults; a file written before normalization existed means it was off.
+
+    Raises
+    ------
+    ValueError
+        For a version this CellPatcher cannot read (:func:`run_config_version`).
+    """
+    run_config_version(data, where)
+    sections = {
+        "common": CommonConfig,
+        "cell": CellConfig,
+        "random": RandomConfig,
+        "grid": GridConfig,
+        "whole_fov": WholeFOVConfig,
+        "filters": FilterConfig,
+        "export": ExportConfig,
+        "extraction": ExtractionConfig,
+        "matching": MatchConfig,
+        "normalization": NormalizationConfig,
+    }
+    built = {name: kind(**data[name]) if name in data else kind() for name, kind in sections.items()}
+    return CellPatcherConfig(mode=data.get("mode", "cell"), **built)
+
+
+def delivery_config(data: Mapping, where: str) -> CellPatcherConfig:
+    """Return the config of a ``run_config.json`` for delivering its exported patches.
+
+    A folder or tree run's arrays are in its recorded ``preprocessing.layout``, put back into
+    ``common.image_axes``/``mask_axes`` (the axes of its patches). A run normalized at a scope
+    removed since (``condition``, ``technical_repeat``; normalization brick N29) still loads: its
+    parameters are in ``patches.csv``, and only the patch axes are needed.
+    """
+    normalization = data.get("normalization")
+    if isinstance(normalization, Mapping) and normalization.get("scope") in REMOVED_NORMALIZATION_SCOPES:
+        data = {**data, "normalization": {**normalization, "scope": "image"}}
+    config = config_from_dict(data, where)
+    layout = (data.get("preprocessing") or {}).get("layout")
+    if layout is not None:
+        config.common.image_axes, config.common.mask_axes = layout["image"], layout["mask"]
+    return config
diff --git a/src/cellpatcher/run_open.py b/src/cellpatcher/run_open.py
index 8605eb2..7762913 100644
--- a/src/cellpatcher/run_open.py
+++ b/src/cellpatcher/run_open.py
@@ -14,6 +14,8 @@
 from pathlib import Path
 from typing import TYPE_CHECKING
 
+from cellpatcher.run_session import remember
+
 if TYPE_CHECKING:
     from morphobricks_normalization import PlaneRecord
     from morphobricks_preprocessing.run_inputs import RunInputs
@@ -133,7 +135,10 @@ def open_run(
     folder = Path(output_folder).expanduser()
     roots = [Path(root).expanduser() if root is not None else None for root in (experiment_root, masks_root)]
     try:
-        return RunInputs.open(folder, *roots)
+        before = _manifest_sha256(folder)
+        inputs = RunInputs.open(folder, *roots)
+        if _manifest_sha256(folder) != before:
+            raise RunInputsError("its run_manifest.json changed while it was opened.")
     except RunInputsError as exc:
         raise PreprocessingCheckError([
             error(
@@ -154,6 +159,16 @@ def open_run(
                 "Give the plane_histograms.csv the preprocessing brick wrote, or run it again.",
             )
         ]) from exc
+    remember("manifest_sha256", folder, before)
+    return inputs
+
+
+def _manifest_sha256(folder: Path) -> str | None:
+    """Return the SHA-256 of the run's ``run_manifest.json`` (recorded in ``run_config.json``), None if absent."""
+    from morphobricks_preprocessing import MANIFEST_FILENAME, file_sha256
+
+    path = folder / MANIFEST_FILENAME
+    return file_sha256(path) if path.is_file() else None
 
 
 def _refuse_other_file(setting: str, given: Path, expected: Path) -> None:
diff --git a/src/cellpatcher/run_session.py b/src/cellpatcher/run_session.py
index 046a7c9..4fef305 100644
--- a/src/cellpatcher/run_session.py
+++ b/src/cellpatcher/run_session.py
@@ -7,6 +7,9 @@
 manifest, and the brick checks each file again whenever it is read, so within
 a call nothing is read unchecked.
 
+The call also keeps what ``run_config.json`` records about the run (:func:`remember`): the
+SHA-256 of its manifest when it was opened, and whether it was read as a folder or tree run.
+
 Nothing is kept beyond the call: the next call opens the run again, so an
 image or mask changed in between, patched or not, is refused then (design
 v0.4 §6; CP-2a). Before CP-2a an opened run was cached for the whole session,
@@ -26,7 +29,7 @@
 if TYPE_CHECKING:
     from cellpatcher.statistics import PlaneStatistics
 
-_SESSION: ContextVar[dict[str, PlaneStatistics] | None] = ContextVar("cellpatcher_run_session", default=None)
+_SESSION: ContextVar[dict[str, PlaneStatistics | str] | None] = ContextVar("cellpatcher_run_session", default=None)
 _P = ParamSpec("_P")
 _R = TypeVar("_R")
 
@@ -81,3 +84,23 @@ def keep_in_session(statistics: PlaneStatistics) -> None:
     if session is None:
         raise RuntimeError("keep_in_session needs an open statistics_session().")
     session[str(statistics.plane_histograms.expanduser().resolve())] = statistics
+
+
+
+def remember(kind: str, output_folder: str | Path, value: str) -> None:
+    """Record *value* of *kind* (``"manifest_sha256"``, ``"file_run"``) for the run in *output_folder*, for this call.
+
+    Outside :func:`statistics_session` nothing is kept.
+    """
+    session = _SESSION.get()
+    if session is not None:
+        session[f"{kind}:{Path(output_folder).expanduser().resolve()}"] = value
+
+
+def recalled(kind: str, output_folder: str | Path) -> str | None:
+    """Return the value of *kind* recorded in this call for the run in *output_folder*, or None."""
+    session = _SESSION.get()
+    if session is None:
+        return None
+    value = session.get(f"{kind}:{Path(output_folder).expanduser().resolve()}")
+    return value if isinstance(value, str) else None
diff --git a/tests/test_file_runs.py b/tests/test_file_runs.py
index fb20bce..4aa4a53 100644
--- a/tests/test_file_runs.py
+++ b/tests/test_file_runs.py
@@ -179,17 +179,53 @@ def test_a_folder_run_patches_one_condition_and_repeat(tmp_path):
         run_patching_pipeline(run.experiment, config=_cell_config(run))
 
 
-def test_the_run_config_records_the_layout_read_and_the_run(tmp_path):
+def test_the_run_config_records_the_run_and_its_manifest_and_loads_back_for_a_file_run(tmp_path):
+    # run_config.json version 2 (CP-2b). Old main recorded the run's layout as common.image_axes
+    # ('CYX') and each leaf's labels, without a version or the manifest's SHA-256, so the file
+    # loaded back was refused for a file run (a migration message about image_axes).
     from cellpatcher.orchestration import load_config
 
     run = _clean_run(tmp_path, axes="CYX", shape=(2, 16, 20), mask_types=("Cells",))
     config = _cell_config(run)
     config.export.enabled, config.common.output_dir = True, str(tmp_path / "out")
-    run_patching_condition_repeat_tree(run.experiment, config=config, combine_metadata=True)
-    saved = load_config(tmp_path / "out" / "run_config.json")
-    assert (saved.common.image_axes, saved.common.mask_axes) == ("CYX", "YX")
-    assert saved.common.preprocessing_run == str(run.output)
+    first = run_patching_condition_repeat_tree(run.experiment, config=config)
+    leaf_file = tmp_path / "out" / first[0].relative_folder / "run_config.json"
+    data = json.loads(leaf_file.read_text(encoding="utf-8"))
+    assert data["run_config_version"] == 2
+    assert data["preprocessing"] == {
+        "run": str(run.output),
+        "manifest_sha256": hashlib.sha256((run.output / "run_manifest.json").read_bytes()).hexdigest(),
+        "layout": {"image": "CYX", "mask": "YX"},
+    }
+    assert not {"image_axes", "mask_axes", "condition", "biological_repeat", "technical_repeat"} & data["common"].keys()
     assert config.common.image_axes == "YX"  # the caller's config is not changed
+    saved = load_config(leaf_file)
+    assert saved.common.preprocessing_run == str(run.output)
+    saved.common.output_dir = str(tmp_path / "again")
+    again = run_patching_condition_repeat_tree(run.experiment, config=saved)
+    assert [p.patch_id for leaf in again for p in leaf.result.patches] == [
+        p.patch_id for leaf in first for p in leaf.result.patches
+    ]
+
+
+@pytest.mark.parametrize("version", [3, "2", None])
+def test_a_run_config_of_an_unknown_version_is_refused_by_every_reader(tmp_path, version):
+    from cellpatcher import iter_exported_patches
+    from cellpatcher.orchestration import load_config
+
+    run = _clean_run(tmp_path, axes="YX", shape=(16, 20), mask_types=("Cells",))
+    config = _cell_config(run)
+    config.export.enabled, config.common.output_dir = True, str(tmp_path / "out")
+    config.normalization.enabled, config.normalization.scope = True, "image"
+    config.normalization.export_values = "raw"
+    run_patching_condition_repeat_tree(run.experiment, config=config, combine_metadata=True)
+    path = tmp_path / "out" / "run_config.json"
+    path.write_text(json.dumps({**json.loads(path.read_text(encoding="utf-8")), "run_config_version": version}))
+    refusal = rf"run_config_version {version!r}; this CellPatcher reads versions 1, 2"
+    with pytest.raises(ValueError, match=refusal):
+        load_config(path)
+    with pytest.raises(ValueError, match=refusal):
+        list(iter_exported_patches(tmp_path / "out" / "patches.csv"))
 
 
 def test_another_table_than_the_run_s_is_refused(tmp_path):

From 01435631550e2ce2eab87667a9b1ba1b9a785c34 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 2 Nov 2026 07:58:59 +0000
Subject: [PATCH 06/23] CP-2b: lazy delivery of a file run reads through its
 preprocessing run

New cellpatcher.iter_run_patch_arrays(patches, config, experiment_root=,
masks_root=) delivers the patches of a folder or tree run one at a time: the
run is opened with RunInputs.open (where the experiment and masks are now),
each patch's image is the run's image at its source_relative_path with the
FOV key the run recorded (another image or key is refused), and only its
plane is read with RunInputs.read_plane, its mask with read_mask.

patch_array, iter_patch_arrays and PatchTorchDataset take arrays only: a file
path, which they read themselves with common.image_axes and CellPatcher's own
header check, now raises a TypeError naming iter_run_patch_arrays.

The tests of CellPatcher's header-axis check for lazy delivery from a path
(refuse_image_header_axes, refuse_mask_header_axes, header_axes_disagreement)
are removed with that path; the file-run refusals of declared axes stay.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G3qp9AxjpGPw9xfWAUJNqc
---
 src/cellpatcher/__init__.py     |   2 +
 src/cellpatcher/delivery.py     |  54 ++++++++---------
 src/cellpatcher/run_delivery.py | 104 ++++++++++++++++++++++++++++++++
 tests/test_declared_axes.py     |  72 ++++------------------
 tests/test_delivery.py          |  41 +++++++++----
 tests/test_file_runs.py         |  33 ++++++++++
 tests/test_plane_policies.py    |  25 ++++----
 7 files changed, 217 insertions(+), 114 deletions(-)
 create mode 100644 src/cellpatcher/run_delivery.py

diff --git a/src/cellpatcher/__init__.py b/src/cellpatcher/__init__.py
index 6cb8037..3dd5c6b 100644
--- a/src/cellpatcher/__init__.py
+++ b/src/cellpatcher/__init__.py
@@ -24,6 +24,7 @@
     WholeFOVConfig,
 )
 from cellpatcher.delivery import iter_exported_patches, iter_patch_arrays, load_exported_patch, patch_array
+from cellpatcher.run_delivery import iter_run_patch_arrays
 from cellpatcher.errors import CellPatcherRefusal, LabelRangeError, SamplingExhaustedError
 from cellpatcher.file_runs import validate_image_and_mask_folders
 from cellpatcher.export import (
@@ -132,6 +133,7 @@
     "save_patch_array",
     "export_patches",
     "iter_patch_arrays",
+    "iter_run_patch_arrays",
     "patch_array",
     "iter_exported_patches",
     "load_exported_patch",
diff --git a/src/cellpatcher/delivery.py b/src/cellpatcher/delivery.py
index 1648f84..f5dfff9 100644
--- a/src/cellpatcher/delivery.py
+++ b/src/cellpatcher/delivery.py
@@ -7,7 +7,9 @@
   patch): each patch is rebuilt from its source image with the pipeline's own
   steps (plane, extract, normalize with the patch's recorded parameters, mask,
   resize, channel), so only one patch, and one image or plane, is in memory at
-  a time; ``cellpatcher.torch_dataset.PatchTorchDataset`` is built on it;
+  a time; ``cellpatcher.torch_dataset.PatchTorchDataset`` is built on it. The
+  images are arrays (``run_patching``); a folder or tree run's patches are read
+  through their preprocessing run with :func:`cellpatcher.iter_run_patch_arrays`;
 - **from exported files**, with :func:`iter_exported_patches` (or
   :func:`load_exported_patch`): files exported with
   ``normalization.export_values="raw"`` are normalized on load with each row's
@@ -32,16 +34,10 @@
 
 from cellpatcher.axes import normalize_axes
 from cellpatcher.extract import extract_patch
-from cellpatcher.io import (
-    read_array,
-    read_image,
-    refuse_image_header_axes,
-    refuse_mask_header_axes,
-    refuse_transposed_mask_axes,
-)
+from cellpatcher.io import read_array, refuse_transposed_mask_axes
 from cellpatcher.masking import apply_label_mask_to_patch
 from cellpatcher.normalization import PatchNormalization, parameters_from_row
-from cellpatcher.planes import apply_plane_choice, patch_plane_choice, read_file_plane, select_mask_plane
+from cellpatcher.planes import apply_plane_choice, patch_plane_choice, select_mask_plane
 from cellpatcher.resize import resize_patch
 from cellpatcher.run_config_file import delivery_config
 
@@ -65,9 +61,9 @@ def patch_array(patch, image, config, *, mask=None) -> np.ndarray:
         A ``PatchRegion`` from a run with *config* (its ``z0``/``t``, ``c``,
         ``label_id`` and ``normalization_*`` fields are used).
     image
-        Its source image, in ``config.common.image_axes``: an array, or a
-        file path (for a TIFF or OME-Zarr image, only the patch's plane is
-        read).
+        Its source image, in ``config.common.image_axes``, as an array. A file
+        path is refused: the patches of a folder or tree run are delivered with
+        :func:`cellpatcher.iter_run_patch_arrays`, through their preprocessing run.
     config
         The run's ``CellPatcherConfig``.
     mask
@@ -97,8 +93,9 @@ def iter_patch_arrays(patches, images: Sequence, config, *, masks: Sequence | No
         *images*. A run with ``extract_arrays=False`` and no export gives
         them, with their normalization recorded, without holding any array.
     images
-        The run's source images, in image order: arrays or file paths (for a
-        folder run, ``cellpatcher.list_supported_files(folder)``).
+        The run's source images, in image order, as arrays (a file path is
+        refused: see :func:`cellpatcher.iter_run_patch_arrays` for folder and
+        tree runs).
     config
         The run's ``CellPatcherConfig``.
     masks
@@ -204,24 +201,27 @@ def _splits_channel(config, patch, axes: str) -> bool:
 
 
 def _image_plane(image, choice, config):
-    common = config.common
-    if isinstance(image, (str, os.PathLike)):
-        refuse_image_header_axes([image], common.image_axes)
-        return read_file_plane(image, common.image_axes, choice, common)
-    return apply_plane_choice(image, common.image_axes, choice)
+    _refuse_file(image, "image")
+    return apply_plane_choice(image, config.common.image_axes, choice)
 
 
 def _mask_plane(mask, choice, config):
     if mask is None:
         return None, None
-    common = config.common
-    if isinstance(mask, (str, os.PathLike)):
-        refuse_mask_header_axes([mask], common.mask_axes)
-        mask = read_image(mask, common.mask_axes)
-    else:
-        refuse_transposed_mask_axes(common.mask_axes)
-        mask = np.asarray(mask)
-    return select_mask_plane(mask, normalize_axes(common.mask_axes, mask.ndim), choice)
+    _refuse_file(mask, "mask")
+    refuse_transposed_mask_axes(config.common.mask_axes)
+    mask = np.asarray(mask)
+    return select_mask_plane(mask, normalize_axes(config.common.mask_axes, mask.ndim), choice)
+
+
+def _refuse_file(source, what: str) -> None:
+    """Refuse a file path: since v0.2.0 files are read only through the preprocessing run (CP-2b)."""
+    if isinstance(source, (str, os.PathLike)):
+        raise TypeError(
+            f"Lazy delivery takes the {what}s of run_patching as arrays; got the path {source}. Since CellPatcher "
+            "v0.2.0 an image or mask file is read only through its preprocessing run (design v0.4 §6): deliver "
+            "the patches of a folder or tree run with cellpatcher.iter_run_patch_arrays(patches, config)."
+        )
 
 
 def _finish_patch(patch, plane, axes, mask_plane, mask_axes, config) -> np.ndarray:
diff --git a/src/cellpatcher/run_delivery.py b/src/cellpatcher/run_delivery.py
new file mode 100644
index 0000000..8befc0c
--- /dev/null
+++ b/src/cellpatcher/run_delivery.py
@@ -0,0 +1,104 @@
+"""Deliver the patches of a folder or tree run lazily, read through its preprocessing run (layer: orchestration).
+
+Lazy delivery of ``run_patching`` takes the images as arrays (:func:`cellpatcher.iter_patch_arrays`).
+The images of a folder or tree run are files, and since v0.2.0 (CP-2b, design v0.4 §6) a file is
+read only through the clean preprocessing run the patches were made from: the run is opened with
+``RunInputs.open`` (where the experiment and masks folder are now), each patch's image is the run's
+image at its ``source_relative_path`` with its recorded FOV key, and only the patch's plane is read
+with ``RunInputs.read_plane``, its mask with ``RunInputs.read_mask``, in the run's layout. Nothing
+here names an axis, pairs a mask or reads a file itself.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterable, Iterator, Mapping
+from typing import TYPE_CHECKING
+
+from cellpatcher.delivery import _finish_patch
+from cellpatcher.file_runs import _read_mask, open_file_run, run_config_for
+from cellpatcher.io import SINGLE_CONDITION_LABEL
+from cellpatcher.planes import patch_plane_choice, select_mask_plane
+from cellpatcher.run_reading import read_fov
+from cellpatcher.run_session import statistics_session
+
+if TYPE_CHECKING:
+    import numpy as np
+    from morphobricks_preprocessing.run_inputs import Fov
+
+    from cellpatcher.config import CellPatcherConfig
+    from cellpatcher.types import PatchRegion
+
+
+def iter_run_patch_arrays(
+    patches: Iterable[PatchRegion],
+    config: CellPatcherConfig,
+    *,
+    experiment_root: str | os.PathLike | None = None,
+    masks_root: str | os.PathLike | None = None,
+) -> Iterator[tuple[PatchRegion, np.ndarray]]:
+    """Yield ``(patch, array)`` for patches of a folder or tree run, one at a time.
+
+    Each array equals the one eager delivery gave: the patch's plane is read through the
+    preprocessing run, then extracted, normalized with the patch's recorded parameters,
+    masked and resized as the run did. The run is opened when iteration starts.
+
+    Parameters
+    ----------
+    patches
+        ``PatchRegion`` objects of a folder or tree run (its ``result.patches``, any leaves).
+    config
+        The run's config (the one given to the run, or ``load_config`` of its
+        ``run_config.json``), with ``common.preprocessing_run``.
+    experiment_root, masks_root
+        Where the experiment and the run's masks folder are now; None: where the run recorded
+        them. Masks are read when ``extraction.apply_mask`` is on.
+
+    Yields
+    ------
+    tuple
+        ``(patch, array)``.
+
+    Raises
+    ------
+    PreprocessingCheckError
+        Without ``common.preprocessing_run``, or when ``RunInputs`` refuses the run.
+    ValueError
+        For a patch whose image is not an image of the run, or whose FOV key is not the one the
+        run recorded for it.
+    """
+    with statistics_session():  # closed before the first patch is yielded
+        run = open_file_run(
+            config, experiment_root, masks_root, use_masks=config.extraction.apply_mask, where="iter_run_patch_arrays"
+        )
+    delivered = run_config_for(config, run, (SINGLE_CONDITION_LABEL,) * 3)
+    fovs = {fov.relative_path: fov for fov in run.fovs}
+    mask: tuple[str, np.ndarray] | None = None
+    for patch in patches:
+        fov = _patch_fov(fovs, patch)
+        choice = patch_plane_choice(patch, run.layout, delivered.common)
+        plane, axes = read_fov(run.inputs, fov, run.layout, choice)
+        mask_plane, mask_axes = None, None
+        if run.mask_type is not None:
+            if mask is None or mask[0] != fov.relative_path:
+                mask = (fov.relative_path, _read_mask(run, fov))  # one image's mask in memory at a time
+            mask_plane, mask_axes = select_mask_plane(mask[1], run.mask_axes, choice)
+        yield patch, _finish_patch(patch, plane, axes, mask_plane, mask_axes, delivered)
+
+
+def _patch_fov(fovs: Mapping[str, Fov], patch: PatchRegion) -> Fov:
+    """Return the run's image of *patch*, refusing a patch of another image or with another FOV key."""
+    fov = fovs.get(str(patch.source_relative_path))
+    if fov is None:
+        raise ValueError(
+            f"Patch {patch.patch_id!r} comes from {patch.source_relative_path!r}, which is not an image of the "
+            "preprocessing run: give the patches of a run made from this preprocessing run."
+        )
+    key = (patch.condition, patch.biological_repeat, patch.technical_repeat, patch.position_id)
+    if key != tuple(fov.key):
+        raise ValueError(
+            f"Patch {patch.patch_id!r} has the FOV key {key}, but the preprocessing run recorded {tuple(fov.key)} "
+            f"for {fov.relative_path}: it was not made from this run."
+        )
+    return fov
+
diff --git a/tests/test_declared_axes.py b/tests/test_declared_axes.py
index 82f5d0e..bf75677 100644
--- a/tests/test_declared_axes.py
+++ b/tests/test_declared_axes.py
@@ -2,14 +2,10 @@
 
 Since CP-2a folder and tree runs declare no axes: they read each file in the roles the
 preprocessing run recorded, and refuse ``common.image_axes``/``mask_axes`` other than the
-default. Lazy delivery from a file path still declares them (until CP-2b), and CellPatcher
-keeps no copy of the rule: the declared axes are checked as the
-file's roles with the brick's ``review_axes`` (``check_mapping`` and
-``header_axis_issue``). A
-declaration may name what a header leaves open and never contradict it. Since
-preprocessing v0.4.0 a Y/X swap is refused like any other contradiction:
-nothing is ever read transposed (``check_declared_axes`` and
-``declared_axes_transposed`` were removed).
+default. Since CP-2b lazy delivery reads no file either (it reads through the run), so
+CellPatcher checks no declared axes against a file header: the preprocessing run does. Since
+preprocessing v0.4.0 a Y/X swap is refused like any other contradiction: nothing is ever read
+transposed. In-memory masks with X before Y are refused.
 """
 
 import csv
@@ -18,7 +14,6 @@
 import pytest
 import tifffile
 
-import cellpatcher.io
 from cellpatcher.config import CellPatcherConfig, GridConfig
 from cellpatcher.export import IMAGE_TABLE_FILENAME
 from cellpatcher.orchestration import run_patching_pipeline
@@ -47,22 +42,6 @@ def _image_rows(folder):
         return {row["image_file"]: row for row in csv.DictReader(handle)}
 
 
-def test_the_shared_rule_is_the_preprocessing_brick_s(tmp_path, monkeypatch):
-    import morphobricks_preprocessing
-
-    calls = []
-    check = morphobricks_preprocessing.review_axes
-
-    def recording(files, mapping):
-        calls.extend((meta.relative_path, mapping.roles_string) for meta in files)
-        return check(files, mapping)
-
-    monkeypatch.setattr(morphobricks_preprocessing, "review_axes", recording)
-    write_tiff(tmp_path / "exp" / "a.tif", np.zeros((3, 16, 16), dtype=np.uint8), "ZYX")
-    cellpatcher.io.refuse_image_header_axes([tmp_path / "exp" / "a.tif"], "ZYX")  # as lazy delivery checks a path
-    assert ("a.tif", "ZYX") in calls
-
-
 def test_y_and_x_declared_swapped_are_refused_never_read_transposed(tmp_path):
     # Before preprocessing v0.4 (CellPatcher v0.1.2), a declaration swapping the header's named
     # Y and X was accepted and the image read transposed (image_read_transposed). Design v0.4
@@ -70,13 +49,9 @@ def test_y_and_x_declared_swapped_are_refused_never_read_transposed(tmp_path):
     image = np.arange(3 * 16 * 24, dtype=np.uint16).reshape(3, 16, 24)  # Z, Y, X in the header
     write_tiff(tmp_path / "exp" / "a.tif", image, "ZYX")
     write_tiff(tmp_path / "exp" / "b.tif", image, "ZYX")
-    paths = [tmp_path / "exp" / "a.tif", tmp_path / "exp" / "b.tif"]
-    with pytest.raises(ValueError, match=r"common.image_axes='ZXY' does not fit the header of 2 image file\(s\): "
-                                         r"a.tif: \[axes_yx_swapped\].* b.tif: \[axes_yx_swapped\]") as error_info:
-        cellpatcher.io.refuse_image_header_axes(paths, "ZXY")  # lazy delivery from a path
-    assert "nothing is read transposed" in str(error_info.value)
     # A file run (CP-2a) declares nothing: the declaration is refused, and the image is read
-    # in the roles the preprocessing run recorded, Y before X.
+    # in the roles the preprocessing run recorded, Y before X. Lazy delivery no longer reads a
+    # file with declared axes (CP-2b), so no CellPatcher-side declaration of a file remains.
     config = file_run_config(_grid_config("ZXY", tmp_path / "out"), tmp_path / "exp", "ZYX")
     config.common.z_policy, config.common.z_index = "select", 1
     with pytest.raises(ValueError, match=r"common.image_axes='ZXY': each image's \(and mask's\) axes are the roles"):
@@ -97,14 +72,10 @@ def test_axes_as_named_are_recorded_as_not_transposed(tmp_path):
 
 
 def test_a_mask_declared_swapped_is_refused(tmp_path):
-    # A mask is checked with the same rule as an image: a Y/X swap is refused (lazy delivery);
-    # a file run declares no mask axes at all since CP-2a.
+    # A file run declares no mask axes at all since CP-2a: a declared swap is refused.
     image, labels, _ = make_synthetic_cell_image_and_labels(shape=(96, 96))
     write_tiff(tmp_path / "exp" / "a.tif", image, "YX")
     write_tiff(tmp_path / "masks" / "a_cells.tif", np.ascontiguousarray(labels.T.astype(np.uint16)), "YX")
-    with pytest.raises(ValueError, match=r"common.mask_axes='XY' does not fit the header of 1 mask file\(s\): "
-                                         r"a_cells.tif: \[axes_yx_swapped\]"):
-        cellpatcher.io.refuse_mask_header_axes([tmp_path / "masks" / "a_cells.tif"], "XY")
     config = file_run_config(_cell_config("YX", "XY"), tmp_path / "exp", masks=tmp_path / "masks")
     with pytest.raises(ValueError, match=r"common.mask_axes='XY': each image's \(and mask's\) axes"):
         run_patching_pipeline(str(tmp_path / "exp"), config=config, mask_folder_path=str(tmp_path / "masks"))
@@ -136,18 +107,18 @@ def test_a_mask_file_whose_header_names_x_before_y_is_refused(tmp_path):
         run_patching_pipeline(str(tmp_path / "exp"), config=config, mask_folder_path=str(tmp_path / "masks"))
 
 
-def test_lazy_delivery_refuses_a_mask_declared_swapped(tmp_path):
+def test_lazy_delivery_refuses_a_mask_file(tmp_path):
+    # Before CP-2b a mask path was read with common.mask_axes and checked against its header by
+    # CellPatcher; a file is now read only through the preprocessing run.
     from cellpatcher.delivery import patch_array
 
     image, labels, _ = make_synthetic_cell_image_and_labels(shape=(32, 32))
-    write_tiff(tmp_path / "a.tif", image, "YX")
     write_tiff(tmp_path / "m.tif", labels.astype(np.uint16), "YX")
     config = _cell_config("YX", "YX")
     patch = run_patching(images=[image], masks=[labels], config=config, image_metadata=named([image])).patches[0]
-    config.common.mask_axes = "XY"
     config.extraction.apply_mask = True
-    with pytest.raises(ValueError, match=r"m.tif: \[axes_yx_swapped\]"):
-        patch_array(patch, tmp_path / "a.tif", config, mask=tmp_path / "m.tif")
+    with pytest.raises(TypeError, match=r"takes the masks of run_patching as arrays; got the path .*m.tif"):
+        patch_array(patch, image, config, mask=tmp_path / "m.tif")
 
 
 def _cell_config(image_axes, mask_axes, output_dir=None):
@@ -172,22 +143,3 @@ def test_an_in_memory_run_records_no_transposition(tmp_path):
     assert row["image_read_transposed"] == ""
 
 
-@pytest.mark.parametrize("header, declared, problem", [
-    ("ZYX", "YZX", r"\[axes_contradict_header\]"),
-    ("ZYX", "TXY", r"\[axes_contradict_header\]"),  # a swap does not excuse another disagreement
-    ("ZYX", "YX", "2 declared for 3 dimensions"),
-])
-def test_other_disagreements_are_refused(tmp_path, header, declared, problem):
-    write_tiff(tmp_path / "exp" / "a.tif", np.zeros((3, 16, 16), dtype=np.uint8), header)
-    with pytest.raises(ValueError, match=rf"common.image_axes='{declared}'.*a.tif.*{problem}"):
-        cellpatcher.io.refuse_image_header_axes([tmp_path / "exp" / "a.tif"], declared)  # lazy delivery
-
-
-def test_a_plain_stack_may_be_declared_with_its_channels_last(tmp_path):
-    # preprocessing v0.3.4: a plain stack's positional Y and X are open, so a (Y, X, C)
-    # array written without metadata (tifffile: QYX) may be declared YXC, and is not transposed.
-    (tmp_path / "exp").mkdir()
-    pixels = np.arange(16 * 16 * 3, dtype=np.uint16).reshape(16, 16, 3)
-    tifffile.imwrite(tmp_path / "exp" / "a.tif", pixels, photometric="minisblack", planarconfig="contig", metadata=None)
-    problem, transposed = cellpatcher.io.header_axes_disagreement(tmp_path / "exp" / "a.tif", "YXC")
-    assert (problem, transposed) == (None, False)
diff --git a/tests/test_delivery.py b/tests/test_delivery.py
index e83f251..5a00bc7 100644
--- a/tests/test_delivery.py
+++ b/tests/test_delivery.py
@@ -12,10 +12,15 @@
 
 import numpy as np
 import pytest
+import tifffile
 
-from cellpatcher import iter_exported_patches, iter_patch_arrays, patch_array
+from cellpatcher import (
+    iter_exported_patches,
+    iter_run_patch_arrays,
+    patch_array,
+)
 from cellpatcher.config import CellPatcherConfig, GridConfig, NormalizationConfig
-from cellpatcher.io import list_supported_files, read_image
+from cellpatcher.io import list_supported_files
 from cellpatcher.orchestration import run_patching_condition_repeat_tree
 
 pytestmark = [
@@ -98,14 +103,18 @@ def config(csv_path):
 }
 
 
-def _run(root, masks, config, **options):
+def _file_run(config):
     # A file run reads through the preprocessing run, in the roles it recorded (CP-2a); the
-    # axes stay set for the lazy delivery from paths and arrays below.
+    # axes of *config* stay set for the lazy delivery from arrays below.
     config = copy.deepcopy(config)
     config.common.image_axes = config.common.mask_axes = "YX"
     config.common.preprocessing_run = str(Path(config.normalization.plane_histograms).parent)
+    return config
+
+
+def _run(root, masks, config, **options):
     return run_patching_condition_repeat_tree(
-        root, config=config, mask_root_path=masks if config.mode == "cell" else None, **options
+        root, config=_file_run(config), mask_root_path=masks if config.mode == "cell" else None, **options
     )
 
 
@@ -152,20 +161,22 @@ def test_files_raw_files_and_the_lazy_iterator_equal_eager_delivery(experiment,
         finite = [array[np.isfinite(array)] for array in eager.values()]  # NaN mask fill aside
         assert all(values.min() >= clip[0] and values.max() <= clip[1] for values in finite)
 
-    lazy_from_paths, lazy_from_arrays = {}, {}
-    for leaf in _run(root, masks, config):
+    lazy_from_run, lazy_from_arrays = {}, {}
+    leaves = _run(root, masks, config)
+    file_config = _file_run(config)
+    for patch, array in iter_run_patch_arrays([p for leaf in leaves for p in leaf.result.patches], file_config):
+        lazy_from_run[(patch.source_relative_path, patch.patch_id)] = array
+    for leaf in leaves:
         image_paths = list_supported_files(leaf.image_folder)
         mask_paths = list_supported_files(masks / "cells" / leaf.relative_folder) if config.mode == "cell" else None
-        for patch, array in iter_patch_arrays(leaf.result.patches, image_paths, config, masks=mask_paths):
-            lazy_from_paths[(patch.source_relative_path, patch.patch_id)] = array
-        images = [read_image(path, config.common.image_axes) for path in image_paths]
-        mask_arrays = [read_image(path, config.common.mask_axes) for path in mask_paths] if mask_paths else None
+        images = [tifffile.imread(path) for path in image_paths]  # stored ZCYX, the in-memory config's axes
+        mask_arrays = [tifffile.imread(path) for path in mask_paths] if mask_paths else None  # stored ZYX
         for patch in leaf.result.patches:
             mask = mask_arrays[int(patch.image_id[-4:])] if mask_arrays else None
             lazy_from_arrays[(patch.source_relative_path, patch.patch_id)] = patch_array(
                 patch, images[int(patch.image_id[-4:])], config, mask=mask
             )
-    _same(lazy_from_paths, eager)
+    _same(lazy_from_run, eager)
     _same(lazy_from_arrays, eager)
 
 
@@ -215,7 +226,11 @@ def test_delivery_settings_are_validated():
 @pytest.mark.parametrize("name", CONFIGS)
 def test_torch_datasets_give_the_same_arrays(experiment, tmp_path, name):
     pytest.importorskip("torch")
-    from cellpatcher.torch_dataset import ExportedPatchTorchDataset, PatchTensorConfig, PatchTorchDataset
+    from cellpatcher.torch_dataset import (
+        ExportedPatchTorchDataset,
+        PatchTensorConfig,
+        PatchTorchDataset,
+    )
 
     root, masks, csv_path = experiment
     config = CONFIGS[name](csv_path)
diff --git a/tests/test_file_runs.py b/tests/test_file_runs.py
index 4aa4a53..7815501 100644
--- a/tests/test_file_runs.py
+++ b/tests/test_file_runs.py
@@ -78,6 +78,39 @@ def test_a_moved_experiment_is_opened_where_it_is_now(tmp_path):
         run_patching_condition_repeat_tree(moved, config=_cell_config(run))
 
 
+def test_a_file_runs_patches_are_delivered_lazily_through_the_run_where_it_is_now(tmp_path):
+    # CP-2b: lazy delivery from a file path read the file itself (with common.image_axes and its
+    # own header check). A folder or tree run's patches are now read through their run.
+    from dataclasses import replace
+
+    from cellpatcher import iter_patch_arrays, iter_run_patch_arrays
+
+    run = _clean_run(tmp_path, axes="YX", shape=(16, 20), mask_types=("Cells",))
+    config = _cell_config(run)
+    config.extraction.apply_mask = True
+    leaves = run_patching_condition_repeat_tree(run.experiment, config=config)
+    eager = _patches(leaves)
+    patches = [patch for leaf in leaves for patch in leaf.result.patches]
+    with pytest.raises(TypeError, match=r"path .*a.ome.tif.*iter_run_patch_arrays\(patches, config\)"):
+        next(iter_patch_arrays(leaves[0].result.patches, [run.experiment / "ctrl" / "rep1" / "a.ome.tif"], config))
+    moved, moved_masks = tmp_path / "moved" / "experiment", tmp_path / "moved" / "masks"
+    moved.parent.mkdir()
+    shutil.move(run.experiment, moved)
+    shutil.move(run.masks, moved_masks)
+    lazy = dict(
+        ((patch.patch_id, patch.mask_file), array)
+        for patch, array in iter_run_patch_arrays(patches, config, experiment_root=moved, masks_root=moved_masks)
+    )
+    assert lazy.keys() == eager.keys() and len(lazy) == 8
+    assert all(np.array_equal(lazy[key], eager[key]) for key in eager)
+    with pytest.raises(ValueError, match="comes from 'ctrl/rep1/z.tif', which is not an image of the preprocessing run"):
+        list(iter_run_patch_arrays([replace(patches[0], source_relative_path="ctrl/rep1/z.tif")], config,
+                                   experiment_root=moved, masks_root=moved_masks))
+    with pytest.raises(ValueError, match=r"has the FOV key \('drug',.*but the preprocessing run recorded \('ctrl'"):
+        list(iter_run_patch_arrays([replace(patches[0], condition="drug")], config,
+                                   experiment_root=moved, masks_root=moved_masks))
+
+
 def test_a_copied_experiment_is_checked_where_it_is_read(tmp_path):
     # CP-2a closes a CP-1 gap: with a copy of the experiment (the original in place), the run
     # was opened at the original, and the copy's masks were read without any check. A mask
diff --git a/tests/test_plane_policies.py b/tests/test_plane_policies.py
index f563d61..2c4653a 100644
--- a/tests/test_plane_policies.py
+++ b/tests/test_plane_policies.py
@@ -305,20 +305,17 @@ def test_a_plain_stack_without_axis_metadata_keeps_its_declared_axes(tmp_path):
     assert sorted({p.t for p in result.patches}) == [0, 1, 2]
 
 
-def test_lazy_delivery_refuses_image_and_mask_files_whose_header_disagrees(tmp_path):
+def test_lazy_delivery_of_a_file_reads_its_planes_through_the_run(tmp_path):
+    # CP-2b: a path given to patch_array was read by CellPatcher (common.image_axes, its own header
+    # check). It is refused; the run's patches are read plane by plane through the run.
+    from cellpatcher import iter_run_patch_arrays
     from cellpatcher.delivery import patch_array
 
     write_tiff(tmp_path / "exp" / "a.tif", _stack(), "TYX")
-    result = preprocessed_folder(tmp_path / "exp", config=_grid_config("YX", t_policy="all"), axes="TYX")
-    patch = result.patches[0]
-    write_tiff(tmp_path / "z.tif", _stack(), "ZYX")
-    config = _grid_config(image_axes="TYX", t_policy="all")
-    np.testing.assert_array_equal(patch_array(patch, tmp_path / "exp" / "a.tif", config), result.patch_arrays[0])
-    with pytest.raises(ValueError, match=r"common.image_axes='TYX'.*z.tif: \[axes_contradict_header\].*header ZYX, confirmed TYX"):
-        patch_array(patch, tmp_path / "z.tif", config)
-    mask = np.ones((3, 16, 16), dtype=np.uint16)
-    write_tiff(tmp_path / "m.tif", mask, "ZYX")
-    config.common.mask_axes = "TYX"
-    config.extraction.apply_mask = True
-    with pytest.raises(ValueError, match=r"common.mask_axes='TYX'.*m.tif: \[axes_contradict_header\].*header ZYX, confirmed TYX"):
-        patch_array(patch, tmp_path / "exp" / "a.tif", config, mask=tmp_path / "m.tif")
+    config = _grid_config("YX", t_policy="all")
+    result = preprocessed_folder(tmp_path / "exp", config=config, axes="TYX")
+    with pytest.raises(TypeError, match="iter_run_patch_arrays"):
+        patch_array(result.patches[0], tmp_path / "exp" / "a.tif", _grid_config(image_axes="TYX", t_policy="all"))
+    lazy = [array for _, array in iter_run_patch_arrays(result.patches, config)]
+    assert len(lazy) == len(result.patch_arrays) > 3
+    assert all(np.array_equal(lazy_array, eager) for lazy_array, eager in zip(lazy, result.patch_arrays))

From 869378b791f1d0713d59fc92b2a7f4b039e5b991 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 2 Nov 2026 08:00:37 +0000
Subject: [PATCH 07/23] CP-2b: remove CellPatcher's own file readers and
 header-axis checks, now unused

Pure removal: io.read_image, io.conform_axes, io.refuse_image_header_axes,
io.refuse_mask_header_axes, io.refuse_header_axes,
io.header_axes_disagreement and planes.read_file_plane with its plane reader
(_read_choice, _plane_reader, _file_layout, _read_plane; the last
transposition plumbing: plane.T for a file whose X came before Y) had no
caller once lazy delivery stopped reading files. Their tests go with them;
read_array still reads a store in its stored order.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G3qp9AxjpGPw9xfWAUJNqc
---
 src/cellpatcher/io.py         | 154 ----------------------------------
 src/cellpatcher/planes.py     | 105 -----------------------
 tests/test_delivery.py        |   4 +-
 tests/test_file_runs.py       |  11 ++-
 tests/test_normalization.py   |   4 +-
 tests/test_ome_zarr_images.py |  22 +----
 tests/test_patch_identity.py  |  26 ------
 7 files changed, 12 insertions(+), 314 deletions(-)

diff --git a/src/cellpatcher/io.py b/src/cellpatcher/io.py
index 294a9a9..fd52bb4 100644
--- a/src/cellpatcher/io.py
+++ b/src/cellpatcher/io.py
@@ -1,11 +1,8 @@
 from __future__ import annotations
 
-import os
 import warnings
-from collections.abc import Iterable
 from dataclasses import dataclass
 from pathlib import Path
-from typing import TYPE_CHECKING
 
 import numpy as np
 from morphobricks_normalization.records import SINGLE
@@ -13,9 +10,6 @@
 from cellpatcher._deprecation import accept_deprecated_repeat
 from cellpatcher.axes import normalize_axes
 
-if TYPE_CHECKING:
-    from morphobricks_preprocessing import TiffMetadata
-
 # ".zarr" is an OME-Zarr image: a folder, read with the preprocessing brick's
 # reader and the ``zarr`` extra (docs/normalization_contract.md §2); every other
 # extension is a file.
@@ -478,57 +472,6 @@ def read_ome_zarr(path) -> tuple[np.ndarray, str]:
     return pixels, image.axes
 
 
-def conform_axes(array, array_axes: str, target_axes: str, *, name="the image") -> np.ndarray:
-    """Rearrange *array* (with axes *array_axes*) into *target_axes*, matching axes by role.
-
-    Used for OME-Zarr images, whose axes come from their metadata. A
-    dimension of length 1 that *target_axes* lacks (including an axis
-    without a role, ``Q``) is dropped; a target axis the array lacks is added
-    with length 1; then the dimensions are put in the target order.
-
-    Raises
-    ------
-    ValueError
-        If the array has a dimension longer than 1 that *target_axes* does
-        not have, or the same role twice.
-    """
-    target = normalize_axes(target_axes)
-    array = np.asarray(array)
-    if len(array_axes) != array.ndim:
-        raise ValueError(f"{name}: {len(array_axes)} axes ({array_axes!r}) for {array.ndim} dimensions.")
-    kept, kept_axes = [], ""
-    for dim, (axis, length) in enumerate(zip(array_axes, array.shape)):
-        if axis in target and axis not in kept_axes:
-            kept.append(dim)
-            kept_axes += axis
-        elif length != 1:
-            role = "an axis without a known role" if axis not in target else f"a second {axis} axis"
-            raise ValueError(
-                f"{name} has {role} ({axis!r}, length {length}) that the axes {target!r} do not have; "
-                f"its axes are {array_axes!r}. Set the axes (common.image_axes or common.mask_axes) to "
-                "include every axis longer than 1."
-            )
-    squeezed = array.reshape([array.shape[dim] for dim in kept])
-    for axis in target:
-        if axis not in kept_axes:
-            squeezed = squeezed[..., np.newaxis]
-            kept_axes += axis
-    return np.transpose(squeezed, [kept_axes.index(axis) for axis in target])
-
-
-def read_image(file_path, axes: str):
-    """Read an image or mask for patching with *axes* (``common.image_axes``/``mask_axes``).
-
-    The same as :func:`read_array`, except that an OME-Zarr image is put
-    into *axes* by role with :func:`conform_axes`, since its own axes come
-    from its metadata rather than from the configuration.
-    """
-    if not is_ome_zarr(file_path):
-        return read_array(file_path)
-    pixels, stored_axes = read_ome_zarr(file_path)
-    return conform_axes(pixels, stored_axes, axes, name=Path(file_path).name)
-
-
 def read_array_shape(file_path) -> tuple[int, ...]:
     return tuple(read_array(file_path).shape)
 
@@ -611,103 +554,6 @@ def refuse_transposed_mask_axes(mask_axes) -> None:
         )
 
 
-def header_axes_disagreement(path: str | os.PathLike, declared_axes: str) -> tuple[str | None, bool]:
-    """Check *declared_axes* against a TIFF file's header with the preprocessing brick's rule.
-
-    The declared axes are the file's roles, checked with the brick's
-    ``review_axes`` (``check_mapping`` and ``header_axis_issue``, design v0.4
-    §3; CellPatcher keeps no copy): they may name what the header leaves
-    open, never contradict an axis it names. A Y/X swap is refused like any contradiction:
-    nothing is ever read transposed. OME-Zarr images are matched by role when
-    read (:func:`conform_axes`), not here.
-
-    Returns
-    -------
-    tuple
-        The brick's message, or None when the declaration fits; and False (no
-        file is read transposed; kept until ``image_read_transposed`` goes).
-    """
-    from morphobricks_preprocessing import inspect_image
-
-    path = Path(path)
-    meta = inspect_image(path, path.name)
-    if meta.is_ome_zarr:
-        return None, False  # OME-Zarr axes are matched by role when read (conform_axes), not by position
-    return _declared_axes_problem(meta, normalize_axes(declared_axes)), False
-
-
-def _declared_axes_problem(meta: TiffMetadata, declared: str) -> str | None:
-    """Return the errors of the brick's ``review_axes`` for roles *declared* on a TIFF header, or None.
-
-    Its warnings (``axes_not_named``) do not block; an unreadable header, which it leaves out, does.
-    """
-    from morphobricks_preprocessing import AxisMapping, review_axes
-
-    if not meta.readable:
-        return f"The header of {meta.relative_path} could not be read, so its axes cannot be checked."
-    if len(declared) != len(meta.axes):
-        return f"{meta.relative_path}: {len(declared)} declared for {len(meta.axes)} dimensions ({meta.axes!r})."
-    review = review_axes([meta], AxisMapping(meta.axes, tuple(declared)))
-    errors = [issue for issue in review.issues if issue.is_error]
-    return " ".join(f"{meta.relative_path}: [{issue.code}] {issue.message} {issue.action}" for issue in errors) or None
-
-
-def refuse_header_axes(
-    paths: Iterable[str | os.PathLike], declared_axes: str, *, setting: str, what: str
-) -> set[str | os.PathLike]:
-    """Refuse *declared_axes* (the setting named *setting*) that do not fit the header axes of *paths*.
-
-    Every file is checked before any is read; all disagreements are listed in
-    one message. See :func:`header_axes_disagreement`.
-
-    Returns
-    -------
-    set
-        The paths (as given) read transposed: always empty, as a Y/X swap is
-        refused (kept until ``image_read_transposed`` is removed).
-    """
-    problems = [problem for problem, _ in (header_axes_disagreement(path, declared_axes) for path in paths) if problem]
-    if problems:
-        raise ValueError(
-            f"{setting}={declared_axes!r} does not fit the header of "
-            f"{len(problems)} {what} file(s): {' '.join(problems[:10])}{' ...' if len(problems) > 10 else ''} "
-            f"Axes are never reinterpreted and nothing is read transposed: set {setting} to the "
-            f"{what}s' header axes, or fix the {what}s' metadata."
-        )
-    return set()
-
-
-def refuse_image_header_axes(image_paths: Iterable[str | os.PathLike], image_axes: str) -> set[str | os.PathLike]:
-    """Refuse ``common.image_axes`` that do not fit an image file's own header axes.
-
-    A TIFF image is read in its stored order and then interpreted with
-    *image_axes*, so an image whose header names its axes ZYX would, with
-    ``image_axes='TYX'``, have its depth slices read as time points (or, with
-    ``'CYX'``, as channels). Returns the images read transposed, always none
-    (see :func:`refuse_header_axes`). See :func:`header_axes_disagreement`.
-    """
-    return refuse_header_axes(image_paths, image_axes, setting="common.image_axes", what="image")
-
-
-def refuse_mask_header_axes(mask_paths: Iterable[str | os.PathLike], mask_axes: str) -> None:
-    """Refuse ``common.mask_axes`` that do not fit a mask file's own header axes.
-
-    A mask TIFF is read in its stored order and then interpreted with
-    *mask_axes*, so a mask whose header names its axes ZYX would, with
-    ``mask_axes='TYX'``, have its depth slices read as time points: a guessed
-    axis. Every mask is checked before any is read; all disagreements are
-    listed in one message. See :func:`header_axes_disagreement`.
-
-    A mask declared with its header's Y and X swapped is refused by the same
-    rule as an image (``axes_yx_swapped``), and a mask whose header names X
-    before Y, declared as named, by :func:`refuse_transposed_mask_axes`:
-    CellPatcher takes a label plane's two dimensions as Y and X in their
-    stored order.
-    """
-    refuse_header_axes(mask_paths, mask_axes, setting="common.mask_axes", what="mask")
-    refuse_transposed_mask_axes(mask_axes)  # a header naming X before Y, declared as named
-
-
 def _issue_text(issue) -> str:
     paths = list(issue.paths)
     listed = f" ({', '.join(paths[:10])}{', ...' if len(paths) > 10 else ''})" if paths else ""
diff --git a/src/cellpatcher/planes.py b/src/cellpatcher/planes.py
index fa62d88..3f12638 100644
--- a/src/cellpatcher/planes.py
+++ b/src/cellpatcher/planes.py
@@ -22,7 +22,6 @@
 import itertools
 from collections.abc import Iterator
 from dataclasses import dataclass
-from pathlib import Path
 
 import numpy as np
 
@@ -190,26 +189,6 @@ def patch_plane_choice(patch, image_axes, common) -> PlaneChoice:
     return PlaneChoice(t=values["T"], z=values["Z"], suffix="")
 
 
-def read_file_plane(path, image_axes, choice: PlaneChoice, common):
-    """Read the plane *choice* of an image file: ``(pixels, axes)``.
-
-    A TIFF or OME-Zarr plane is read on its
-    own; any other image is read whole
-    and the plane taken from it.
-    """
-    from cellpatcher.io import read_image
-
-    mbp = _plane_reader(path, common)
-    if mbp is None or any(isinstance(choice.value(axis), str) for axis in ("T", "Z")):
-        return apply_plane_choice(read_image(path, image_axes), image_axes, choice)
-    path = Path(path).expanduser()
-    target = normalize_axes(image_axes)
-    mapping, shape, dtype = _file_layout(mbp, path, target)
-    return _read_choice(mbp, path, mapping, shape, dtype, target, choice), "".join(
-        axis for axis in target if choice.value(axis) is None
-    )
-
-
 def select_mask_plane(mask, mask_axes, choice: PlaneChoice):
     """The mask plane for *choice*: a mask axis with the image's length follows it, length 1 is shared."""
     if mask is None:
@@ -224,90 +203,6 @@ def select_mask_plane(mask, mask_axes, choice: PlaneChoice):
     return mask, mask_axes
 
 
-def _read_choice(mbp, path: Path, mapping, shape, dtype, target: str, choice: PlaneChoice) -> np.ndarray:
-    """Read the plane *choice* of a file, one 2D plane at a time, in *target* order minus resolved axes."""
-    plane_axes = "".join(axis for axis in target if choice.value(axis) is None)
-    pixels = np.empty([shape[target.index(axis)] for axis in plane_axes], dtype=dtype)
-    # Axes kept in the plane (channels, or a "keep" axis) are read one 2D
-    # plane at a time and stacked back in place.
-    stacked = [axis for axis in plane_axes if axis not in "YX"]
-    y_before_x = plane_axes.index("Y") < plane_axes.index("X")
-    for position in np.ndindex(*(pixels.shape[plane_axes.index(axis)] for axis in stacked)):
-        coordinates = {"T": choice.index("T"), "Z": choice.index("Z"), "C": None}
-        coordinates.update(zip(stacked, position))
-        plane = _read_plane(mbp, path, mapping, coordinates)
-        where = tuple(position[stacked.index(axis)] if axis in stacked else slice(None) for axis in plane_axes)
-        pixels[where] = plane if y_before_x else plane.T
-    return pixels
-
-
-def _plane_reader(path, common):
-    """The preprocessing package when *path* can be read plane by plane under *common*, else None."""
-    from cellpatcher.io import is_ome_zarr
-    from cellpatcher.statistics import _preprocessing
-
-    policies = (common.z_policy, common.t_policy)
-    if not splits_planes(common) or any(policy in _PROJECTIONS for policy in policies):
-        return None
-    if not (is_ome_zarr(path) or Path(path).suffix.lower() in (".tif", ".tiff")):
-        return None
-    return _preprocessing()
-
-
-def _file_layout(mbp, path: Path, target: str):
-    """The preprocessing ``AxisMapping`` of a file, and its shape and dtype in *target* order.
-
-    Raises
-    ------
-    ValueError
-        If the file cannot be read, or holds more than one image (several
-        series, positions or wells): its planes would be read from the first
-        one only, as when reading it whole (``io.read_ome_zarr``).
-    """
-    meta = mbp.inspect_image(path, path.name)
-    if not meta.readable:
-        raise ValueError(f"{path.name} cannot be read: {meta.error}")
-    if meta.series_count > 1:
-        raise ValueError(
-            f"{path} holds {meta.series_count} images (several series, positions or wells); CellPatcher reads "
-            "one image per file or OME-Zarr folder and would patch only the first. Save each image in its own "
-            "file or folder."
-        )
-    if meta.kind == "ome-zarr":
-        # OME-Zarr axes come from the metadata and are matched by role, as in
-        # io.conform_axes: an axis the configured axes lack must have length 1.
-        for axis, length in zip(meta.axes, meta.shape):
-            if axis not in target and length != 1:
-                raise ValueError(
-                    f"{path.name} has an axis {axis!r} of length {length} that the axes {target!r} do not "
-                    f"have; its axes are {meta.axes!r}. Set common.image_axes to include every axis "
-                    "longer than 1."
-                )
-        lengths = dict(zip(meta.axes, meta.shape))
-        roles = tuple(axis if axis in target else None for axis in meta.axes)
-        shape = tuple(lengths.get(axis, 1) for axis in target)
-    else:
-        # A TIFF's dimensions are those tifffile.imread returns, which
-        # common.image_axes names in order.
-        normalize_axes(target, len(meta.shape))
-        roles = tuple(target)
-        shape = tuple(meta.shape)
-    return mbp.AxisMapping(meta.axes, roles), shape, np.dtype(meta.dtype)
-
-
-def _read_plane(mbp, path: Path, mapping, coordinates) -> np.ndarray:
-    """Read one (Y, X) plane, with None for roles the file does not have."""
-    present = set(mapping.roles)
-    wanted = {axis.lower(): (value if axis in present else None) for axis, value in coordinates.items()}
-    try:
-        return mbp.read_plane(path, mapping, **wanted).pixels
-    except mbp.PlaneMemoryError as exc:
-        raise ValueError(
-            f"CellPatcher needs each plane whole in memory to patch it, and a plane of {path.name} is too "
-            f"large: {exc}"
-        ) from exc
-
-
 def _axis_choices(image_shape, image_axes, mask_shape, mask_axes, axis, policy, index, single_planes) -> list[tuple]:
     """``(value, id label)`` per plane along ``axis``: an index, a projection name, or None (unchanged)."""
     position = axis_index(image_axes, axis)
diff --git a/tests/test_delivery.py b/tests/test_delivery.py
index 5a00bc7..c031bef 100644
--- a/tests/test_delivery.py
+++ b/tests/test_delivery.py
@@ -239,9 +239,9 @@ def test_torch_datasets_give_the_same_arrays(experiment, tmp_path, name):
 
     from_images = {}
     for leaf in _run(root, masks, config):
-        images = [read_image(p, config.common.image_axes) for p in list_supported_files(leaf.image_folder)]
+        images = [tifffile.imread(p) for p in list_supported_files(leaf.image_folder)]  # stored ZCYX
         mask_list = (
-            [read_image(p, config.common.mask_axes) for p in list_supported_files(masks / "cells" / leaf.relative_folder)]
+            [tifffile.imread(p) for p in list_supported_files(masks / "cells" / leaf.relative_folder)]  # stored ZYX
             if config.mode == "cell" else None
         )
         dataset = PatchTorchDataset(images, leaf.result.patches, masks=mask_list, config=config, tensor_config=tensors)
diff --git a/tests/test_file_runs.py b/tests/test_file_runs.py
index 7815501..9aaef14 100644
--- a/tests/test_file_runs.py
+++ b/tests/test_file_runs.py
@@ -176,10 +176,13 @@ def test_file_runs_read_through_run_inputs_only(tmp_path, monkeypatch):
     def refused(*args, **kwargs):
         raise AssertionError("CellPatcher read or paired a file itself")
 
-    for module, name in ((cellpatcher.io, "read_image"), (cellpatcher.io, "read_array"),
-                         (cellpatcher.io, "refuse_image_header_axes"), (cellpatcher.io, "discover_images"),
-                         (cellpatcher.planes, "read_file_plane")):
-        monkeypatch.setattr(module, name, refused)
+    for name in ("read_array", "discover_images"):
+        monkeypatch.setattr(cellpatcher.io, name, refused)
+    # CellPatcher's own file readers and header checks are gone (CP-2b).
+    for module, name in ((cellpatcher.io, "read_image"), (cellpatcher.io, "conform_axes"), (cellpatcher.io, "pair_masks"),
+                         (cellpatcher.io, "refuse_image_header_axes"), (cellpatcher.io, "refuse_mask_header_axes"),
+                         (cellpatcher.planes, "read_file_plane"), (cellpatcher.planes, "iter_file_planes")):
+        assert not hasattr(module, name), name
     run = _clean_run(tmp_path, axes="ZCYX", shape=(3, 2, 16, 20), mask_types=())
     config = CellPatcherConfig(mode="grid")
     config.grid.tile_size = 8
diff --git a/tests/test_normalization.py b/tests/test_normalization.py
index 8965b3a..45fce1b 100644
--- a/tests/test_normalization.py
+++ b/tests/test_normalization.py
@@ -745,13 +745,13 @@ def offsets(pooling):
 
 
 def test_a_missing_or_unconfirmed_design_stops_the_run_before_any_image_is_read(tmp_path, monkeypatch):
-    import cellpatcher.io
+    from morphobricks_preprocessing.run_inputs import RunInputs
 
     def no_reading(*args, **kwargs):
         raise AssertionError("an image was read")
 
     root, _, csv_path = _unpaired_experiment(tmp_path, design=None)  # no experiment_design.csv
-    monkeypatch.setattr(cellpatcher.io, "read_image", no_reading)
+    monkeypatch.setattr(RunInputs, "read_plane", no_reading)
     config = _config(csv_path, image_axes="YX", scope="biological_repeat")
     with pytest.raises(PreprocessingCheckError) as missing:
         _tree(root, config)
diff --git a/tests/test_ome_zarr_images.py b/tests/test_ome_zarr_images.py
index 3d986ff..e847b0c 100644
--- a/tests/test_ome_zarr_images.py
+++ b/tests/test_ome_zarr_images.py
@@ -13,11 +13,9 @@
 from cellpatcher.config import CellPatcherConfig, GridConfig
 from cellpatcher.file_runs import validate_image_and_mask_folders
 from cellpatcher.io import (
-    conform_axes,
     discover_condition_repeat_folders,
     list_supported_files,
     read_array,
-    read_image,
     write_array,
 )
 from cellpatcher.orchestration import run_patching_condition_repeat_tree
@@ -102,34 +100,16 @@ def test_reading_a_store_without_the_extra_names_the_install_command(tmp_path, m
 # ---------------------------------------------------------------------------
 
 
-def test_conform_axes_reorders_drops_and_adds_length_one_axes():
-    data = np.arange(2 * 1 * 3 * 4).reshape(2, 1, 3, 4)  # C, Z (length 1), Y, X
-    out = conform_axes(data, "CZYX", "YXC")
-    assert out.shape == (3, 4, 2)
-    np.testing.assert_array_equal(out[..., 1], data[1, 0])
-    assert conform_axes(data, "CZYX", "TCYX").shape == (1, 2, 3, 4)
-
-
-def test_conform_axes_rejects_axes_longer_than_one_without_a_role():
-    with pytest.raises(ValueError, match="without a known role"):
-        conform_axes(np.zeros((2, 3, 4)), "QYX", "YX")
-    with pytest.raises(ValueError, match="'Z', length 2"):
-        conform_axes(np.zeros((2, 3, 4)), "ZYX", "YX")
-
-
 # ---------------------------------------------------------------------------
 # Reading and patching (needs the extra)
 # ---------------------------------------------------------------------------
 
 
 @needs_zarr
-def test_read_array_and_read_image(tmp_path):
+def test_read_array_reads_a_store_in_its_stored_order(tmp_path):
     data = np.arange(2 * 3 * 4 * 5, dtype=np.uint16).reshape(2, 3, 4, 5)
     path = write_ngff(tmp_path / "a.ome.zarr", data, "czyx")
     np.testing.assert_array_equal(read_array(path), data)
-    as_zcyx = read_image(path, "ZCYX")
-    assert as_zcyx.shape == (3, 2, 4, 5)
-    np.testing.assert_array_equal(as_zcyx[1, 0], data[0, 1])
 
 
 @needs_zarr
diff --git a/tests/test_patch_identity.py b/tests/test_patch_identity.py
index 95dc2fc..bd94a7b 100644
--- a/tests/test_patch_identity.py
+++ b/tests/test_patch_identity.py
@@ -19,9 +19,6 @@
 from tests.helpers import preprocess, write_ngff, write_ngff_labels
 from tests.helpers import preprocessed_folder as _folder, preprocessed_tree as _tree
 
-needs_preprocessing = pytest.mark.skipif(
-    importlib.util.find_spec("morphobricks_preprocessing") is None, reason="needs morphobricks-preprocessing (a core dependency)"
-)
 needs_zarr = pytest.mark.skipif(
     importlib.util.find_spec("morphobricks_preprocessing") is None or importlib.util.find_spec("zarr") is None,
     reason="needs the 'zarr' extra",
@@ -350,29 +347,6 @@ def test_a_multi_series_tiff_never_reaches_a_file_run(tmp_path):
         preprocess(path.parent, "ZYX")
 
 
-@needs_preprocessing
-def test_a_multi_series_tiff_is_refused_when_reading_planes(tmp_path):
-    # Lazy delivery from a path still reads planes with planes.read_file_plane (until CP-2b).
-    import tifffile
-
-    from cellpatcher.planes import PlaneChoice, read_file_plane
-
-    path = tmp_path / "plate.tif"
-    tifffile.imwrite(path, np.zeros((2, 16, 16), dtype=np.uint16))
-    tifffile.imwrite(path, np.ones((2, 16, 16), dtype=np.uint16), append=True)
-    with pytest.raises(ValueError, match="plate.tif holds 2 images"):
-        read_file_plane(path, "ZYX", PlaneChoice(t=None, z=0, suffix=""), CommonConfig(image_axes="ZYX", z_policy="all"))
-
-
-@needs_zarr
-def test_a_store_with_several_images_is_refused_when_reading_planes(tmp_path):
-    from cellpatcher.planes import PlaneChoice, read_file_plane
-
-    path = write_ngff(tmp_path / "plate.ome.zarr", np.zeros((2, 16, 16), dtype=np.uint16), "zyx", images=2)
-    with pytest.raises(ValueError, match="plate.ome.zarr holds 2 images"):
-        read_file_plane(path, "ZYX", PlaneChoice(t=None, z=0, suffix=""), CommonConfig(image_axes="ZYX", z_policy="all"))
-
-
 def test_positions_differing_only_in_case_are_refused_in_one_repeat():
     """D85: position_id is unique within its technical repeat whatever its case."""
     config = CellPatcherConfig(mode="whole_fov")

From c35802a26d70c5c251444b46cc4d3cd8248a6ae4 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 2 Nov 2026 08:02:21 +0000
Subject: [PATCH 08/23] CP-2b: a dict comprehension in the lazy delivery test
 (ruff C402)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G3qp9AxjpGPw9xfWAUJNqc
---
 tests/test_file_runs.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/tests/test_file_runs.py b/tests/test_file_runs.py
index 9aaef14..85192de 100644
--- a/tests/test_file_runs.py
+++ b/tests/test_file_runs.py
@@ -97,10 +97,10 @@ def test_a_file_runs_patches_are_delivered_lazily_through_the_run_where_it_is_no
     moved.parent.mkdir()
     shutil.move(run.experiment, moved)
     shutil.move(run.masks, moved_masks)
-    lazy = dict(
-        ((patch.patch_id, patch.mask_file), array)
+    lazy = {
+        (patch.patch_id, patch.mask_file): array
         for patch, array in iter_run_patch_arrays(patches, config, experiment_root=moved, masks_root=moved_masks)
-    )
+    }
     assert lazy.keys() == eager.keys() and len(lazy) == 8
     assert all(np.array_equal(lazy[key], eager[key]) for key in eager)
     with pytest.raises(ValueError, match="comes from 'ctrl/rep1/z.tif', which is not an image of the preprocessing run"):

From 6d04268d03b1bde5e2dfdaa9e039fa276698d33a Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 2 Nov 2026 08:06:13 +0000
Subject: [PATCH 09/23] CP-2b: remove image_read_transposed and the mask_source
 settings

Breaking, listed in the CHANGELOG:
- images.csv loses its last column image_read_transposed (and ImageRecord
  its field): since preprocessing v0.4 refuses every Y/X swap it was always
  false for a file and empty in memory.
- common.mask_source and common.mask_label_name are removed: folder and tree
  runs read the masks their preprocessing run paired (label images included,
  chosen with matching.mask_type), and run_patching never used them.
  CommonConfig(mask_source=...) is a TypeError; a config or run_config.json
  file holding their defaults (every file before v0.2.0) still loads, and
  one with another value is refused naming the setting and what replaces it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G3qp9AxjpGPw9xfWAUJNqc
---
 src/cellpatcher/config.py          | 18 +++---------------
 src/cellpatcher/export.py          |  5 +----
 src/cellpatcher/file_runs.py       | 18 +++++-------------
 src/cellpatcher/pipeline.py        |  1 -
 src/cellpatcher/run_config_file.py | 22 ++++++++++++++++++++++
 src/cellpatcher/types.py           |  6 ------
 tests/test_declared_axes.py        | 21 ++++++++-------------
 tests/test_file_runs.py            |  3 +--
 tests/test_image_table.py          |  1 -
 tests/test_ngff_labels.py          | 17 ++++-------------
 tests/test_types_and_config.py     | 16 ++++++++++++++++
 11 files changed, 60 insertions(+), 68 deletions(-)

diff --git a/src/cellpatcher/config.py b/src/cellpatcher/config.py
index 56b8255..f263fce 100644
--- a/src/cellpatcher/config.py
+++ b/src/cellpatcher/config.py
@@ -13,15 +13,12 @@
 from cellpatcher.ids import validate_object_set
 from cellpatcher.planes import validate_plane_policies
 
-MASK_SOURCES = ("tiff_tree", "ngff_labels")
-
-
 @accept_deprecated_repeat
 @dataclass
 class CommonConfig:
-    # The axes of in-memory arrays given to run_patching (canonical, Y before X). File runs
-    # read each image and mask in the roles the preprocessing run recorded and refuse other
-    # values than "YX" (CP-2a; removed for them in CP-2b).
+    # The axes of in-memory arrays given to run_patching (canonical, Y before X). Folder and
+    # tree runs read each image and mask in the roles the preprocessing run recorded, refuse
+    # other values than "YX" and do not record them in run_config.json (design v0.4 §6).
     image_axes: str = "YX"
     mask_axes: str = "YX"
     output_dir: str | None = None
@@ -48,11 +45,6 @@ class CommonConfig:
     z_index: int | None = None
     t_policy: str = "keep"
     t_index: int | None = None
-    # Where folder and tree runs read masks before CP-2a. They now read the masks the
-    # preprocessing run paired (choose the type with matching.mask_type) and refuse other
-    # values than these defaults.
-    mask_source: str = "tiff_tree"
-    mask_label_name: str | None = None
     # The object set of cell-mode patches (the `object_set` column and a
     # level of patch_id, cellpatcher.ids). None: folder and tree runs name it
     # after the mask type the preprocessing run recorded (a folder name, or an
@@ -63,10 +55,6 @@ class CommonConfig:
 
     def __post_init__(self) -> None:
         validate_plane_policies(self)
-        if self.mask_source not in MASK_SOURCES:
-            raise ValueError(f"mask_source must be one of {list(MASK_SOURCES)}; got {self.mask_source!r}.")
-        if self.mask_label_name is not None and not isinstance(self.mask_label_name, str):
-            raise ValueError("mask_label_name must be a string or None.")
         validate_object_set(self.object_set)
 
 
diff --git a/src/cellpatcher/export.py b/src/cellpatcher/export.py
index 6940d62..c209ecd 100644
--- a/src/cellpatcher/export.py
+++ b/src/cellpatcher/export.py
@@ -85,10 +85,7 @@ def save_image_table_csv(image_records, csv_path):
         writer = csv.DictWriter(f, fieldnames=list(IMAGE_TABLE_COLUMNS))
         writer.writeheader()
         for record in image_records:
-            row = record.to_dict()
-            if isinstance(row["image_read_transposed"], bool):
-                row["image_read_transposed"] = "true" if row["image_read_transposed"] else "false"
-            writer.writerow(row)
+            writer.writerow(record.to_dict())
 
 
 def image_records_from_patches(patches) -> list[ImageRecord]:
diff --git a/src/cellpatcher/file_runs.py b/src/cellpatcher/file_runs.py
index 76349c1..92f7a97 100644
--- a/src/cellpatcher/file_runs.py
+++ b/src/cellpatcher/file_runs.py
@@ -12,9 +12,9 @@
   with ``RunInputs.read_mask`` by the run's pairing (:mod:`cellpatcher.run_reading`);
 - the CSV normalization scopes read the run's own table, design and image type.
 
-The settings that told CellPatcher how to read files (``common.image_axes``, ``mask_axes``,
-``mask_source``, ``mask_label_name`` and the labels) are refused for file runs with a
-migration message; CP-2b removes them. In-memory ``run_patching`` keeps them.
+The settings that told CellPatcher how to read files (``common.image_axes``, ``mask_axes`` and
+the labels) are refused for file runs with a migration message; in-memory ``run_patching``
+keeps them. ``mask_source`` and ``mask_label_name`` were removed in v0.2.0 (CP-2b).
 """
 
 from __future__ import annotations
@@ -126,12 +126,6 @@ def refuse_file_run_settings(config: CellPatcherConfig, where: str) -> None:
         for name in ("image_axes", "mask_axes")
         if getattr(common, name) != _DEFAULT_AXES
     ]
-    if common.mask_source != "tiff_tree" or common.mask_label_name is not None:
-        problems.append(
-            f"common.mask_source={common.mask_source!r}, common.mask_label_name={common.mask_label_name!r}: the "
-            "masks are those the preprocessing run paired (masks-folder TIFFs and OME-Zarr label images); "
-            "choose the type with matching.mask_type (a label image's type is its name)"
-        )
     problems += [
         f"common.{name}={getattr(common, name)!r}: each image's labels are its folders, as the preprocessing "
         "run recorded them; leave it unset"
@@ -142,8 +136,7 @@ def refuse_file_run_settings(config: CellPatcherConfig, where: str) -> None:
         raise ValueError(
             f"{where} reads the images, masks and labels through the preprocessing run since CellPatcher "
             "v0.2.0 (design v0.4 §6), so these settings are not used for files: " + "; ".join(problems) + ". "
-            "The axes and labels still describe in-memory arrays given to run_patching; mask_source and "
-            "mask_label_name are not used there."
+            "The axes and labels still describe in-memory arrays given to run_patching."
         )
     if common.preprocessing_run is None:
         _refuse_without_run(where)
@@ -375,14 +368,13 @@ def fov_metadata(run: FileRun, fov: Fov, config: CellPatcherConfig) -> dict:
 
     The FOV key is the run's (``position_id`` and ``technical_repeat`` included); the mask
     file and, in ``cell`` mode without ``common.object_set``, the object set come from the
-    recorded mask and its type. Nothing is read transposed (``image_read_transposed`` False).
+    recorded mask and its type.
     """
     meta = {
         "image_file": PurePosixPath(fov.relative_path).name,
         "source_relative_path": fov.relative_path,
         "position_id": fov.key[3],
         "technical_repeat": fov.key[2],
-        "image_read_transposed": False,
     }
     if run.mask_type is not None:
         meta["mask_file"] = mask_file_name(_record(run.inputs, fov, run.mask_type))
diff --git a/src/cellpatcher/pipeline.py b/src/cellpatcher/pipeline.py
index aa1d413..41855f7 100644
--- a/src/cellpatcher/pipeline.py
+++ b/src/cellpatcher/pipeline.py
@@ -222,7 +222,6 @@ def _image_record(config: CellPatcherConfig, image_id: str, meta, image_shape=No
         image_height=height,
         image_width=width,
         position_id=None if meta.get("position_id") is None else str(meta["position_id"]),
-        image_read_transposed=meta.get("image_read_transposed"),
     )
 
 
diff --git a/src/cellpatcher/run_config_file.py b/src/cellpatcher/run_config_file.py
index 69ce3ec..fbf8a88 100644
--- a/src/cellpatcher/run_config_file.py
+++ b/src/cellpatcher/run_config_file.py
@@ -44,6 +44,9 @@
 RUN_CONFIG_VERSION = 2
 READ_VERSIONS = (1, RUN_CONFIG_VERSION)
 
+# Settings removed in v0.2.0 (CP-2b), with the value that had no effect.
+_REMOVED_COMMON = {"mask_source": "tiff_tree", "mask_label_name": None}
+
 # The common settings a folder or tree run takes from the preprocessing run, not recorded.
 _RUN_SETTINGS = ("image_axes", "mask_axes", "condition", "biological_repeat", "technical_repeat")
 
@@ -138,10 +141,29 @@ def config_from_dict(data: Mapping, where: str = "The config") -> CellPatcherCon
         "matching": MatchConfig,
         "normalization": NormalizationConfig,
     }
+    data = {**data, "common": _without_removed_settings(data.get("common", {}), where)}
     built = {name: kind(**data[name]) if name in data else kind() for name, kind in sections.items()}
     return CellPatcherConfig(mode=data.get("mode", "cell"), **built)
 
 
+def _without_removed_settings(common: Mapping, where: str) -> dict:
+    """Return the ``common`` section without the settings removed in v0.2.0, refusing one that was used.
+
+    ``mask_source`` and ``mask_label_name`` chose where folder and tree runs read masks; a file
+    written before v0.2.0 holds their defaults, which had no effect and are left out.
+    """
+    common = dict(common)
+    for name, default in _REMOVED_COMMON.items():
+        value = common.pop(name, default)
+        if value != default:
+            raise ValueError(
+                f"{where}: common.{name}={value!r} was removed in CellPatcher v0.2.0: a folder or tree run reads "
+                "the masks its preprocessing run paired, masks-folder TIFFs and OME-Zarr label images alike. "
+                "Remove it and choose the mask type with matching.mask_type (a label image's type is its name)."
+            )
+    return common
+
+
 def delivery_config(data: Mapping, where: str) -> CellPatcherConfig:
     """Return the config of a ``run_config.json`` for delivering its exported patches.
 
diff --git a/src/cellpatcher/types.py b/src/cellpatcher/types.py
index cd0bf49..4d60ecd 100644
--- a/src/cellpatcher/types.py
+++ b/src/cellpatcher/types.py
@@ -290,11 +290,6 @@ def normalization_channel_columns(parameters) -> dict[str, str]:
     "n_regions",
     "n_kept",
     "n_normalized",
-    # Whether the image was read transposed: its header's named Y and X
-    # declared swapped in common.image_axes (v0.1.2 only: since preprocessing
-    # v0.4 a swap is refused, so always false for a TIFF file). Empty when not
-    # checked (an in-memory array, an OME-Zarr image matched by role).
-    "image_read_transposed",
 )
 
 
@@ -333,7 +328,6 @@ class ImageRecord:
     n_patches: int = 0
     skip_reason: str | None = None
     position_id: str | None = None
-    image_read_transposed: bool | None = None
 
     @property
     def status(self) -> str:
diff --git a/tests/test_declared_axes.py b/tests/test_declared_axes.py
index bf75677..9a1b845 100644
--- a/tests/test_declared_axes.py
+++ b/tests/test_declared_axes.py
@@ -63,12 +63,18 @@ def test_y_and_x_declared_swapped_are_refused_never_read_transposed(tmp_path):
     assert np.array_equal(result.patch_arrays[0], image[1, patch.y0:patch.y1, patch.x0:patch.x1])
 
 
-def test_axes_as_named_are_recorded_as_not_transposed(tmp_path):
+def test_the_image_table_has_no_transposition_column(tmp_path):
+    # images.csv had a last column image_read_transposed (v0.1.2), always false or empty since
+    # preprocessing v0.4 refuses every Y/X swap; removed in v0.2.0 (CP-2b).
     write_tiff(tmp_path / "exp" / "a.tif", np.zeros((3, 16, 24), dtype=np.uint8), "ZYX")
     config = _grid_config("YX", tmp_path / "out")
     config.common.z_policy = "all"
     preprocessed_folder(tmp_path / "exp", config=config, axes="ZYX")
-    assert _image_rows(tmp_path / "out")["a.tif"]["image_read_transposed"] == "false"
+    images = [np.zeros((16, 16), dtype=np.uint8)]
+    run_patching(images=images, config=_grid_config("YX", tmp_path / "memory"), image_metadata=named(images))
+    for out in (tmp_path / "out", tmp_path / "memory"):
+        (row,) = _image_rows(out).values()
+        assert list(row)[-1] == "n_normalized" and "image_read_transposed" not in row
 
 
 def test_a_mask_declared_swapped_is_refused(tmp_path):
@@ -132,14 +138,3 @@ def _cell_config(image_axes, mask_axes, output_dir=None):
         config.export.enabled = True
         config.common.output_dir = str(output_dir)
     return config
-
-
-def test_an_in_memory_run_records_no_transposition(tmp_path):
-    images = [np.zeros((16, 16), dtype=np.uint8)]
-    config = _grid_config("YX", tmp_path / "out")
-    run_patching(images=images, config=config, image_metadata=named(images))
-    with open(tmp_path / "out" / IMAGE_TABLE_FILENAME, newline="", encoding="utf-8") as handle:
-        (row,) = csv.DictReader(handle)
-    assert row["image_read_transposed"] == ""
-
-
diff --git a/tests/test_file_runs.py b/tests/test_file_runs.py
index 85192de..df1f090 100644
--- a/tests/test_file_runs.py
+++ b/tests/test_file_runs.py
@@ -197,8 +197,7 @@ def refused(*args, **kwargs):
 
 
 @pytest.mark.parametrize(("setting", "value"), [
-    ("image_axes", "ZCYX"), ("mask_axes", "ZYX"), ("mask_source", "ngff_labels"), ("mask_label_name", "Cells"),
-    ("condition", "ctrl"), ("biological_repeat", "rep1"), ("technical_repeat", "B02"),
+    ("image_axes", "ZCYX"), ("mask_axes", "ZYX"), ("condition", "ctrl"), ("biological_repeat", "rep1"), ("technical_repeat", "B02"),
 ])
 def test_the_former_file_settings_raise_a_migration_message(tmp_path, monkeypatch, setting, value):
     from cellpatcher import file_runs
diff --git a/tests/test_image_table.py b/tests/test_image_table.py
index 74a900f..1434193 100644
--- a/tests/test_image_table.py
+++ b/tests/test_image_table.py
@@ -94,7 +94,6 @@ def test_folder_run_lists_images_with_and_without_patches(tmp_path):
         "source_relative_path": "a.tif", "image_height": "96", "image_width": "128",
         "n_patches": "4", "status": "processed", "reason": "",
         "position_id": "a", "n_regions": "4", "n_kept": "4", "n_normalized": "4",
-        "image_read_transposed": "false",
     }
     # The image whose mask holds no cell is listed, not dropped.
     assert by_file["b.tif"]["n_patches"] == "0"
diff --git a/tests/test_ngff_labels.py b/tests/test_ngff_labels.py
index c924fa7..2c91879 100644
--- a/tests/test_ngff_labels.py
+++ b/tests/test_ngff_labels.py
@@ -2,8 +2,8 @@
 
 Since CP-2a a file run reads the masks the preprocessing run paired, a label image's type
 being its name (``matching.mask_type``), with ``RunInputs.read_mask``; the former
-``common.mask_source='ngff_labels'`` and ``mask_label_name`` are refused. Needs the ``zarr``
-extra; the tests skip without it.
+``common.mask_source='ngff_labels'`` and ``mask_label_name`` were removed in v0.2.0 (CP-2b).
+Needs the ``zarr`` extra; the tests skip without it.
 """
 
 import importlib.util
@@ -50,12 +50,6 @@ def _image(root, name="a.ome.zarr", shape=(16, 16), axes="yx", labels=None, labe
     return path
 
 
-def test_mask_source_is_validated():
-    assert (CommonConfig().mask_source, CommonConfig().mask_label_name) == ("tiff_tree", None)
-    with pytest.raises(ValueError, match="mask_source must be one of"):
-        CommonConfig(mask_source="labels")
-
-
 def test_cell_mode_reads_the_only_label_image(tmp_path):
     _image(tmp_path, labels={"cells": _labels((16, 16), [(1, 2, 2), (2, 9, 9)])})
 
@@ -108,13 +102,10 @@ def test_a_label_image_that_does_not_fit_has_no_clean_run(tmp_path):
         preprocess(floats)
 
 
-def test_the_former_label_settings_are_refused_for_file_runs(tmp_path):
+def test_every_image_needs_a_label_image_of_the_type(tmp_path):
     _image(tmp_path, labels={"cells": _labels((16, 16), [(1, 2, 2)])})
     write_array(tmp_path / "control" / "b.tif", np.ones((16, 16), dtype=np.uint16))
-    for setting in ({"mask_source": "ngff_labels"}, {"mask_label_name": "cells"}):
-        with pytest.raises(ValueError, match="common.mask_source=.*choose the type with matching.mask_type"):
-            run_patching_condition_repeat_tree(tmp_path, config=_cell_config(preprocessing_run="run", **setting))
-    # Every image needs a mask of the type: the TIFF has no label image.
+    # The TIFF has no label image.
     with pytest.raises(ValueError, match="recorded no 'cells' mask for control/b.tif"):
         _tree(tmp_path, _cell_config())
 
diff --git a/tests/test_types_and_config.py b/tests/test_types_and_config.py
index 27ba547..b39baad 100644
--- a/tests/test_types_and_config.py
+++ b/tests/test_types_and_config.py
@@ -391,3 +391,19 @@ def test_save_config_for_mode_default_values_match_dataclass_defaults(tmp_path):
     assert cfg.grid.tile_size == expected.grid.tile_size
     assert cfg.common.image_axes == expected.common.image_axes
     assert cfg.export.enabled == expected.export.enabled
+
+
+def test_the_mask_source_settings_are_removed(tmp_path):
+    # Removed in v0.2.0 (CP-2b): old main still accepted them (refused for file runs only, unused
+    # in memory). A file written before holds their defaults, which had no effect: it still loads.
+    from cellpatcher.config import CommonConfig
+
+    with pytest.raises(TypeError, match="mask_source"):
+        CommonConfig(mask_source="ngff_labels")
+    path = tmp_path / "run_config.json"
+    path.write_text(json.dumps({"mode": "grid", "common": {"mask_source": "tiff_tree", "mask_label_name": None}}))
+    assert load_config(path).common == CommonConfig()
+    for name, value in (("mask_source", "ngff_labels"), ("mask_label_name", "cells")):
+        path.write_text(json.dumps({"mode": "cell", "common": {name: value}}))
+        with pytest.raises(ValueError, match=rf"common.{name}={value!r} was removed in CellPatcher v0.2.0.*mask_type"):
+            load_config(path)

From 46d09854aa5ddee590009a237b7c0ef111455580 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 2 Nov 2026 08:09:19 +0000
Subject: [PATCH 10/23] CP-2b: drop the CommonConfig import the label test no
 longer uses (ruff F401)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G3qp9AxjpGPw9xfWAUJNqc
---
 tests/test_ngff_labels.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/test_ngff_labels.py b/tests/test_ngff_labels.py
index 2c91879..02be888 100644
--- a/tests/test_ngff_labels.py
+++ b/tests/test_ngff_labels.py
@@ -11,7 +11,7 @@
 import numpy as np
 import pytest
 
-from cellpatcher.config import CellPatcherConfig, CommonConfig
+from cellpatcher.config import CellPatcherConfig
 from cellpatcher.io import write_array
 from cellpatcher.orchestration import run_patching_condition_repeat_tree
 from tests.helpers import file_run_config, preprocess, write_ngff, write_ngff_labels

From e77c7e63407fc75daa56c567168715bae42d718e Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 2 Nov 2026 08:10:50 +0000
Subject: [PATCH 11/23] CP-2b: grid and whole-FOV folder runs take
 mask_folder_path for a moved masks folder

Owner decision 3 (2026-11-02): as the tree run already did, run_patching_pipeline
(and run_patching_from_folders) accept mask_folder_path in grid and whole_fov
mode and use it only to open the preprocessing run, whose masks are checked
there and never read. Before, it was refused, so the run of an experiment
whose masks folder had moved could not be opened.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G3qp9AxjpGPw9xfWAUJNqc
---
 src/cellpatcher/file_runs.py     | 14 +++--------
 src/cellpatcher/orchestration.py | 10 ++++----
 tests/test_io.py                 | 40 +++++++++++++-------------------
 3 files changed, 24 insertions(+), 40 deletions(-)

diff --git a/src/cellpatcher/file_runs.py b/src/cellpatcher/file_runs.py
index 92f7a97..a1d5f3a 100644
--- a/src/cellpatcher/file_runs.py
+++ b/src/cellpatcher/file_runs.py
@@ -161,19 +161,11 @@ def _refuse_without_run(where: str, setting: str = "common.preprocessing_run") -
 def masks_used(config: CellPatcherConfig, masks_root: str | os.PathLike | None) -> bool:
     """Return whether the run reads masks: always in ``cell`` mode, in ``random`` mode when asked.
 
-    ``random`` mode reads them when a masks folder or ``matching.mask_type`` is given.
-
-    Raises
-    ------
-    ValueError
-        For a masks folder in ``grid`` or ``whole_fov`` mode, which use no masks.
+    ``random`` mode reads them when a masks folder or ``matching.mask_type`` is given. ``grid``
+    and ``whole_fov`` read none: a masks folder given for them only says where the run's masks
+    folder is now (owner decision of 2026-11-02), and the run checks its masks there.
     """
     if config.mode in {"grid", "whole_fov"}:
-        if masks_root is not None:
-            raise ValueError(
-                f"mask_folder_path is not supported for mode='{config.mode}'. "
-                "Remove it, or switch to 'cell' or 'random' mode."
-            )
         return False
     return config.mode == "cell" or masks_root is not None or config.matching.mask_type is not None
 
diff --git a/src/cellpatcher/orchestration.py b/src/cellpatcher/orchestration.py
index b6835a5..d888b38 100644
--- a/src/cellpatcher/orchestration.py
+++ b/src/cellpatcher/orchestration.py
@@ -333,9 +333,9 @@ def run_patching_pipeline(
         * ``'cell'`` mode always reads masks.
         * ``'random'`` mode reads them when this or ``matching.mask_type``
           is given — masks restrict where patches are sampled.
-        * **Must not be provided** for ``'grid'`` or ``'whole_fov'`` modes
-          (those modes do not consume masks; a ``ValueError`` is raised if
-          this argument is set for those modes).
+        * ``'grid'`` and ``'whole_fov'`` read none; given, it only says
+          where the run's masks folder is now (its masks are checked there,
+          as for the tree run).
     strategy, mask_suffixes, case_sensitive:
         Former matching options, removed in v0.1.1 and refused by name:
         the masks are those the preprocessing run paired; choose the mask
@@ -368,6 +368,7 @@ def run_patching_pipeline(
     config = _checked_config(config, overrides)
     refuse_removed_matching("run_patching_pipeline", removed_options)
     with statistics_session():
+        # grid/whole_fov read no masks: a masks folder given for them only says where the run's is now.
         use_masks = masks_used(config, mask_folder_path)
         run = open_file_run(
             config, image_folder_path, mask_folder_path, use_masks=use_masks, where="run_patching_pipeline"
@@ -506,8 +507,7 @@ def run_patching_condition_repeat_tree(
             "combine_metadata=True requires config.export.enabled=True and config.common.output_dir to be set."
         )
     refuse_removed_matching("run_patching_condition_repeat_tree", removed_options)
-    # grid/whole_fov read no masks: a masks folder given for them only says where the run's is now.
-    use_masks = masks_used(config, None if config.mode in {"grid", "whole_fov"} else mask_root_path)
+    use_masks = masks_used(config, mask_root_path)
     with statistics_session():
         run = open_file_run(
             config, image_root_path, mask_root_path, use_masks=use_masks, where="run_patching_condition_repeat_tree"
diff --git a/tests/test_io.py b/tests/test_io.py
index 8a0c77e..c474738 100644
--- a/tests/test_io.py
+++ b/tests/test_io.py
@@ -158,32 +158,24 @@ def test_run_patching_pipeline_alias_grid_mode(tmp_path):
     assert len(result.patches) == 4
 
 
-def test_run_patching_pipeline_grid_raises_if_mask_folder_provided(tmp_path):
-    """grid mode must not silently ignore a provided mask folder."""
-    img_dir = tmp_path / "images"
-    mask_dir = tmp_path / "masks"
-    img_dir.mkdir()
-    mask_dir.mkdir()
-    write_array(img_dir / "a.tif", np.zeros((8, 8)))
-    write_array(mask_dir / "a_mask.tif", np.zeros((8, 8), dtype=np.int32))
-
-    config = CellPatcherConfig(mode="grid")
-    with pytest.raises(ValueError, match="mask_folder_path"):
-        run_patching_pipeline(img_dir, config=config, mask_folder_path=mask_dir)
-
+@pytest.mark.parametrize("mode", ["grid", "whole_fov"])
+def test_grid_and_whole_fov_folder_runs_take_a_moved_masks_folder(tmp_path, mode):
+    """Owner decision 3 (2026-11-02): as in the tree run, mask_folder_path says where the run's masks
+    folder is now; the masks are checked there and never read. Old main refused it for these modes."""
+    import shutil
 
-def test_run_patching_pipeline_whole_fov_raises_if_mask_folder_provided(tmp_path):
-    """whole_fov mode must not silently ignore a provided mask folder."""
-    img_dir = tmp_path / "images"
-    mask_dir = tmp_path / "masks"
-    img_dir.mkdir()
-    mask_dir.mkdir()
-    write_array(img_dir / "a.tif", np.zeros((8, 8)))
-    write_array(mask_dir / "a_mask.tif", np.zeros((8, 8), dtype=np.int32))
+    from cellpatcher.statistics import PreprocessingCheckError
 
-    config = CellPatcherConfig(mode="whole_fov")
-    with pytest.raises(ValueError, match="mask_folder_path"):
-        run_patching_pipeline(img_dir, config=config, mask_folder_path=mask_dir)
+    img_dir, mask_dir = tmp_path / "images", tmp_path / "masks"
+    write_array(img_dir / "a.tif", np.zeros((8, 8), dtype=np.uint16))
+    write_array(mask_dir / "a_mask.tif", np.ones((8, 8), dtype=np.uint16))
+    config = file_run_config(CellPatcherConfig(mode=mode), img_dir, masks=mask_dir)
+    config.grid.tile_size = 4
+    shutil.move(mask_dir, tmp_path / "moved")
+    with pytest.raises(PreprocessingCheckError, match="1 mask changed or missing since the run"):
+        run_patching_pipeline(img_dir, config=config)  # checked where the run recorded it: gone
+    result = run_patching_pipeline(img_dir, config=config, mask_folder_path=tmp_path / "moved")
+    assert result.patches and all(patch.mask_file is None for patch in result.patches)
 
 
 def test_run_patching_pipeline_random_mode_with_optional_mask(tmp_path):

From 26a4b6a6e177a39369a9781b58093f777a0476e9 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 2 Nov 2026 08:15:37 +0000
Subject: [PATCH 12/23] CP-2b: normalization.experiment_root/masks_root for
 run_patching at a CSV scope

Owner decision 4 (2026-11-02): in-memory run_patching with the image or
biological_repeat scope opened the preprocessing run where it recorded the
experiment, so a moved experiment was refused. normalization.experiment_root
and masks_root now say where they are now; the run is opened there with
RunInputs.open. A folder or tree run is told by its arguments and refuses
these settings with the migration message.

cached_statistics moves from cellpatcher.normalization to cellpatcher.run_open
(normalization.py was over 600 lines), beside the new settings_statistics
that both CSV-scope readers use.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G3qp9AxjpGPw9xfWAUJNqc
---
 src/cellpatcher/config.py        | 25 +++++++++---------
 src/cellpatcher/file_runs.py     |  6 +++++
 src/cellpatcher/normalization.py | 34 +++---------------------
 src/cellpatcher/run_open.py      | 45 ++++++++++++++++++++++++++++++--
 tests/test_file_runs.py          | 33 ++++++++++++++++++++++-
 5 files changed, 97 insertions(+), 46 deletions(-)

diff --git a/src/cellpatcher/config.py b/src/cellpatcher/config.py
index f263fce..31951a3 100644
--- a/src/cellpatcher/config.py
+++ b/src/cellpatcher/config.py
@@ -26,12 +26,10 @@ class CommonConfig:
     # The output folder of the clean preprocessing run (v0.4) a folder or tree run reads its
     # images, masks and labels through (RunInputs, design v0.4 §6); required for file runs.
     preprocessing_run: str | None = None
-    # The MorphoBricks shared-CSV-contract `condition`/`biological_repeat`/`technical_repeat`
-    # columns (AGENTS.md §5) of in-memory run_patching; a label not given (or None) is
-    # "single", as for a missing folder level. Folder and tree runs take each image's labels
-    # from the preprocessing run and refuse other values. technical_repeat is the well/dish/
-    # coverslip; per-image image_metadata["technical_repeat"] overrides it. `repeat` stays
-    # accepted as a deprecated alias of biological_repeat (DeprecationWarning).
+    # The shared-CSV-contract labels (AGENTS.md §5) of in-memory run_patching; None is "single",
+    # as for a missing folder level. Folder and tree runs take each image's from the run and
+    # refuse other values. technical_repeat (well/dish/coverslip) is overridden per image by
+    # image_metadata["technical_repeat"]; `repeat` is a deprecated alias of biological_repeat.
     condition: str | None = SINGLE_CONDITION_LABEL
     biological_repeat: str | None = SINGLE_BIOLOGICAL_REPEAT_LABEL
     technical_repeat: str | None = SINGLE_TECHNICAL_REPEAT_LABEL
@@ -45,12 +43,10 @@ class CommonConfig:
     z_index: int | None = None
     t_policy: str = "keep"
     t_index: int | None = None
-    # The object set of cell-mode patches (the `object_set` column and a
-    # level of patch_id, cellpatcher.ids). None: folder and tree runs name it
-    # after the mask type the preprocessing run recorded (a folder name, or an
-    # OME-NGFF label name), and "mask" when the mask gives no name (in-memory
-    # run_patching). Set it to name it
-    # explicitly; image_metadata["object_set"] overrides it per image.
+    # The object set of cell-mode patches (the `object_set` column and a level of patch_id,
+    # cellpatcher.ids). None: folder and tree runs name it after the mask type the run recorded
+    # (a folder name, or an OME-NGFF label name), in-memory run_patching "mask". Set it to name
+    # it explicitly; image_metadata["object_set"] overrides it per image.
     object_set: str | None = None
 
     def __post_init__(self) -> None:
@@ -360,6 +356,9 @@ class NormalizationConfig:
     manifest
         The run's ``run_manifest.json``: None, or the one in the table's
         folder (another file is refused).
+    experiment_root, masks_root
+        For ``run_patching`` at a CSV scope: where the run's experiment and masks
+        folder are now, if moved since the run (None: where it recorded them).
     method
         ``"minmax"``, ``"percentile"`` (default), ``"zscore"`` or
         ``"robust_zscore"`` (MAD x 1.4826); only ``"percentile"`` for
@@ -415,6 +414,8 @@ class NormalizationConfig:
     enabled: bool = False
     plane_histograms: str | None = None
     manifest: str | None = None
+    experiment_root: str | None = None
+    masks_root: str | None = None
     method: str = "percentile"
     percentile: tuple[float, float] = (1.0, 99.8)
     clip: tuple[float, float] | None = None
diff --git a/src/cellpatcher/file_runs.py b/src/cellpatcher/file_runs.py
index a1d5f3a..9bb667b 100644
--- a/src/cellpatcher/file_runs.py
+++ b/src/cellpatcher/file_runs.py
@@ -126,6 +126,12 @@ def refuse_file_run_settings(config: CellPatcherConfig, where: str) -> None:
         for name in ("image_axes", "mask_axes")
         if getattr(common, name) != _DEFAULT_AXES
     ]
+    problems += [
+        f"normalization.{name}={getattr(config.normalization, name)!r}: where the experiment and masks are now "
+        "is the image folder or root and mask_folder_path or mask_root_path of the run; leave it unset"
+        for name in ("experiment_root", "masks_root")
+        if getattr(config.normalization, name) is not None
+    ]
     problems += [
         f"common.{name}={getattr(common, name)!r}: each image's labels are its folders, as the preprocessing "
         "run recorded them; leave it unset"
diff --git a/src/cellpatcher/normalization.py b/src/cellpatcher/normalization.py
index 7b1e851..eee9b53 100644
--- a/src/cellpatcher/normalization.py
+++ b/src/cellpatcher/normalization.py
@@ -44,8 +44,7 @@
 
 from cellpatcher.axes import normalize_axes
 from cellpatcher.masking import _label_to_2d
-from cellpatcher.run_open import _refuse_other_file
-from cellpatcher.run_session import session_statistics
+from cellpatcher.run_open import _refuse_other_file, settings_statistics
 from cellpatcher.statistics import (
     PlaneStatistics,
     PreprocessingCheckError,
@@ -53,13 +52,10 @@
     _preprocessing,
     check_images,
     check_planes,
-    load_plane_statistics,
     require_normalization,
 )
 
 if TYPE_CHECKING:
-    import os
-
     from morphobricks_preprocessing import ConfirmedDesign
 
     from cellpatcher.config import CellPatcherConfig, NormalizationConfig
@@ -116,30 +112,6 @@ def validate_normalization(config) -> None:
         )
 
 
-def cached_statistics(
-    plane_histograms: str | os.PathLike,
-    manifest: str | os.PathLike | None = None,
-    *,
-    experiment_root: str | os.PathLike | None = None,
-    masks_root: str | os.PathLike | None = None,
-) -> PlaneStatistics:
-    """:func:`~cellpatcher.statistics.load_plane_statistics`, opened once per CellPatcher call.
-
-    Within one call (:mod:`cellpatcher.run_session`: a tree run normalizes every leaf with
-    the same, possibly large, table) the run is opened once; outside a call, or in the next
-    one, it is opened again, so ``RunInputs.open`` checks every image and mask of the run each
-    time. Nothing is reused across calls.
-    """
-    csv_path = Path(plane_histograms).expanduser()
-    statistics = session_statistics(
-        csv_path,
-        lambda: load_plane_statistics(csv_path, manifest, experiment_root=experiment_root, masks_root=masks_root),
-    )
-    if manifest is not None:
-        _refuse_other_file("normalization.manifest", Path(manifest).expanduser(), statistics.manifest_path)
-    return statistics
-
-
 def experiment_design_path(settings: NormalizationConfig) -> Path:
     """The preprocessing run's ``experiment_design.csv``, beside ``plane_histograms``.
 
@@ -244,7 +216,7 @@ def normalization_inputs(config: CellPatcherConfig) -> dict | None:
     settings = config.normalization
     if not settings.enabled or settings.scope not in CSV_SCOPES or settings.plane_histograms is None:
         return None
-    statistics = cached_statistics(settings.plane_histograms, settings.manifest)
+    statistics = settings_statistics(settings)
     manifest = statistics.manifest
     inputs = {
         "plane_histograms_sha256": manifest.csv_sha256,
@@ -499,7 +471,7 @@ def for_config(cls, config) -> Normalizer | None:
         validate_normalization(config)
         statistics, repeat_groups = None, None
         if settings.scope in CSV_SCOPES:
-            statistics = cached_statistics(settings.plane_histograms, settings.manifest)
+            statistics = settings_statistics(settings)
             check_image_type(settings, statistics)
             warnings.warn(
                 "The group and image statistics of the preprocessing brick come from whole planes, "
diff --git a/src/cellpatcher/run_open.py b/src/cellpatcher/run_open.py
index 7762913..9ef2f08 100644
--- a/src/cellpatcher/run_open.py
+++ b/src/cellpatcher/run_open.py
@@ -4,7 +4,8 @@
 refuses a run before v0.4.0, a table or design whose SHA-256 is not the manifest's, and an
 image or mask changed or missing since the run. An experiment moved or copied since its run is
 opened with where it is now (``experiment_root``, ``masks_root``). Re-exported by
-:mod:`cellpatcher.statistics`, where these functions were before CP-2a.
+:mod:`cellpatcher.statistics`, where these functions were before CP-2a. :func:`cached_statistics`
+(moved from :mod:`cellpatcher.normalization` in CP-2b) keeps an opened run for one call.
 """
 
 from __future__ import annotations
@@ -14,12 +15,13 @@
 from pathlib import Path
 from typing import TYPE_CHECKING
 
-from cellpatcher.run_session import remember
+from cellpatcher.run_session import remember, session_statistics
 
 if TYPE_CHECKING:
     from morphobricks_normalization import PlaneRecord
     from morphobricks_preprocessing.run_inputs import RunInputs
 
+    from cellpatcher.config import NormalizationConfig
     from cellpatcher.statistics import PlaneStatistics
 
 
@@ -78,6 +80,45 @@ def load_plane_statistics(
     return statistics_of(open_run(folder, experiment_root=experiment_root, masks_root=masks_root))
 
 
+def cached_statistics(
+    plane_histograms: str | os.PathLike,
+    manifest: str | os.PathLike | None = None,
+    *,
+    experiment_root: str | os.PathLike | None = None,
+    masks_root: str | os.PathLike | None = None,
+) -> PlaneStatistics:
+    """:func:`~cellpatcher.statistics.load_plane_statistics`, opened once per CellPatcher call.
+
+    Within one call (:mod:`cellpatcher.run_session`: a tree run normalizes every leaf with
+    the same, possibly large, table) the run is opened once; outside a call, or in the next
+    one, it is opened again, so ``RunInputs.open`` checks every image and mask of the run each
+    time. Nothing is reused across calls.
+    """
+    csv_path = Path(plane_histograms).expanduser()
+    statistics = session_statistics(
+        csv_path,
+        lambda: load_plane_statistics(csv_path, manifest, experiment_root=experiment_root, masks_root=masks_root),
+    )
+    if manifest is not None:
+        _refuse_other_file("normalization.manifest", Path(manifest).expanduser(), statistics.manifest_path)
+    return statistics
+
+
+def settings_statistics(settings: NormalizationConfig) -> PlaneStatistics:
+    """Return :func:`cached_statistics` of ``settings.plane_histograms``, opened where the experiment is now.
+
+    ``normalization.experiment_root``/``masks_root`` say where the run's experiment and masks
+    folder are when they moved since the run (owner decision of 2026-11-02); a folder or tree
+    run gives them as its arguments instead.
+    """
+    return cached_statistics(
+        settings.plane_histograms,
+        settings.manifest,
+        experiment_root=settings.experiment_root,
+        masks_root=settings.masks_root,
+    )
+
+
 def statistics_of(inputs: RunInputs) -> PlaneStatistics:
     """Return the :class:`PlaneStatistics` of a run opened with :func:`open_run`.
 
diff --git a/tests/test_file_runs.py b/tests/test_file_runs.py
index df1f090..5ae76fc 100644
--- a/tests/test_file_runs.py
+++ b/tests/test_file_runs.py
@@ -111,6 +111,37 @@ def test_a_file_runs_patches_are_delivered_lazily_through_the_run_where_it_is_no
                                    experiment_root=moved, masks_root=moved_masks))
 
 
+def test_run_patching_at_a_csv_scope_opens_a_moved_experiment_where_normalization_says(tmp_path):
+    # Owner decision 4 (2026-11-02): normalization.experiment_root/masks_root. Old main had no such
+    # setting: run_patching opened the run where it recorded the experiment, refusing a moved one.
+    from cellpatcher import run_patching
+    from cellpatcher.config import NormalizationConfig
+
+    run = _clean_run(tmp_path, axes="YX", shape=(16, 20), mask_types=("Cells",))
+    moved, moved_masks = tmp_path / "moved" / "experiment", tmp_path / "moved" / "masks"
+    moved.parent.mkdir()
+    shutil.move(run.experiment, moved)
+    shutil.move(run.masks, moved_masks)
+    (path,) = sorted((moved / "ctrl" / "rep1").glob("a.*"))
+    config = CellPatcherConfig(mode="grid")
+    config.grid.tile_size, config.common.extract_arrays = 8, True
+    config.common.condition, config.common.biological_repeat = "ctrl", "rep1"
+    config.normalization = NormalizationConfig(
+        enabled=True, scope="image", plane_histograms=str(run.output / "plane_histograms.csv")
+    )
+    meta = [{"image_file": path.name, "source_relative_path": path.relative_to(moved).as_posix()}]
+    with pytest.raises(PreprocessingCheckError, match="4 images changed or missing since the run"):
+        run_patching(images=[tifffile.imread(path)], config=config, image_metadata=meta)
+    config.normalization.experiment_root, config.normalization.masks_root = str(moved), str(moved_masks)
+    result = run_patching(images=[tifffile.imread(path)], config=config, image_metadata=meta)
+    assert len(result.patch_arrays) == 4 and all(array.dtype == np.float32 for array in result.patch_arrays)
+    # A folder or tree run is told where the experiment is by its arguments, not by these settings.
+    file_config = _cell_config(run)
+    file_config.normalization.experiment_root = str(moved)
+    with pytest.raises(ValueError, match=r"normalization.experiment_root=.*the image folder or root"):
+        run_patching_condition_repeat_tree(moved, mask_root_path=moved_masks, config=file_config)
+
+
 def test_a_copied_experiment_is_checked_where_it_is_read(tmp_path):
     # CP-2a closes a CP-1 gap: with a copy of the experiment (the original in place), the run
     # was opened at the original, and the copy's masks were read without any check. A mask
@@ -133,7 +164,7 @@ def test_an_opened_run_is_not_reused_once_a_mask_or_another_image_changed(tmp_pa
     # Former code (CP-1): cached_statistics kept the opened run for the session, keyed on the
     # table and manifest; a mask, or an image not patched, changed after the first open was
     # not checked again. Now every call opens the run again (cellpatcher.run_session).
-    from cellpatcher.normalization import cached_statistics
+    from cellpatcher.run_open import cached_statistics
 
     run = _clean_run(tmp_path, axes="YX", shape=(16, 20), mask_types=("Cells",))
     table = run.output / "plane_histograms.csv"

From f41a638ae0217eb19fb6d2dceb38548b12bd6181 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 2 Nov 2026 08:20:41 +0000
Subject: [PATCH 13/23] CP-2b docs: the removals, run_config.json version 2 and
 the owner decisions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fixes what this PR makes false, and nothing for CP-3: the CHANGELOG entry
(with the breaking removals), configuration_reference.md (file runs, common
and normalization tables, matching, delivery, images.csv, OME-Zarr,
run_config.json), AGENTS.md §4/§5, normalization_contract.md §4/§12/§13,
normalization.md, the validate_image_and_mask_folders example in
api_examples.md, and docstrings and the in-memory mask message that named
removed functions or mask files.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G3qp9AxjpGPw9xfWAUJNqc
---
 AGENTS.md                          | 95 +++++++++++++++---------------
 docs/api_examples.md               |  5 +-
 docs/configuration_reference.md    | 58 ++++++++----------
 docs/normalization.md              |  6 +-
 docs/normalization_contract.md     | 14 +++--
 notebooks/CellPatcher/CHANGELOG.md | 49 ++++++++++++++-
 src/cellpatcher/io.py              | 14 ++---
 src/cellpatcher/orchestration.py   |  6 +-
 src/cellpatcher/statistics.py      |  9 ++-
 9 files changed, 150 insertions(+), 106 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 46339ed..88db218 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -186,16 +186,28 @@ CellPatcher-specific conventions:
   with `RunInputs.read_plane`/`read_mask` (`cellpatcher.run_reading`) in one
   canonical layout per run (T, Z, C, then Y, X). No CellPatcher-side axis,
   pairing or calibration logic is used for them; `common.image_axes`/`mask_axes`
-  other than `"YX"`, `mask_source="ngff_labels"`, `mask_label_name` and labels
-  other than `"single"` are refused with a migration message (CP-2b removes
-  them for file runs). The run is opened once per call and kept for that call
-  only (`cellpatcher.run_session`).
+  other than `"YX"`, labels other than `"single"` and
+  `normalization.experiment_root`/`masks_root` are refused with a migration
+  message. The run is opened once per call and kept for that call only
+  (`cellpatcher.run_session`). Since CP-2b no file is read or paired by
+  CellPatcher itself: `validate_image_and_mask_folders(..., preprocessing_run=)`
+  returns the run's pairing, lazy delivery of a file run's patches is
+  `iter_run_patch_arrays` (`cellpatcher.run_delivery`, through `RunInputs`),
+  and `patch_array`/`iter_patch_arrays` take arrays only. `run_config.json` is
+  version 2 (`cellpatcher.run_config_file`): `run_config_version` and a
+  `preprocessing` section (the run, its manifest's SHA-256, a file run's array
+  layout); a file run records no `image_axes`/`mask_axes`/labels; readers
+  refuse other versions. Grid/whole-FOV folder runs accept `mask_folder_path`
+  (where the run's masks folder is now), and `normalization.experiment_root`/
+  `masks_root` say where a moved experiment is for `run_patching` at a CSV
+  scope (owner decisions of 2026-11-02).
 * `image_axes`/`mask_axes` are explicit and axis-aware (see `axes.py`) for
-  in-memory arrays and lazy delivery from a path.
-  Image/mask pairing is the preprocessing brick's `find_masks`, called by
-  `io.pair_masks` (issue #45, owner decision 2026-10-30): TIFF masks named
-  `<image>_<type>.tif` or `<type>/<image>.tif`; `matching.mask_type` picks
-  the type. CellPatcher has no pairing rule of its own; the former matching
+  in-memory arrays only (canonical, Y before X; a mask with X first is refused).
+  Image/mask pairing is the preprocessing run's (its `find_masks`; issue #45,
+  owner decision 2026-10-30): TIFF masks named
+  `<image>_<type>.tif` or `<type>/<image>.tif`, or an OME-Zarr image's label
+  image; `matching.mask_type` picks the type. CellPatcher has no pairing rule
+  of its own (`io.pair_masks` was removed in CP-2b); the former matching
   options (`strategy`, `mask_suffixes`, `case_sensitive`,
   `ignore_unrequested_masks`) and matchers (`find_candidate_matches`, ...)
   were removed in v0.1.1 (D86, owner decision 2026-10-31): the options are
@@ -249,40 +261,23 @@ preprocessing run (`common.preprocessing_run`, opened with `RunInputs`; see §4
 `docs/configuration_reference.md`, "File runs read through the preprocessing
 run"): the images, their labels and `position_id`, their roles and their masks
 are the run's. A folder mask and a label image of one type for one image are
-refused by the preprocessing run (`duplicate_mask`, rc1). The rest of this
-paragraph describes discovery and pairing as `validate_image_and_mask_folders`
-and lazy delivery from paths still do them (until CP-2b), and as file runs did
-before v0.2.0. CellPatcher reads image files, and (for `cell` mode) matching label/mask
-files, directly from user-provided folders. Images are found with the
-preprocessing brick's `discover_experiment` (`io.discover_images`; owner
-decision of 2026-10-30, issue #45): TIFF files and OME-Zarr images. PNG, JPEG,
-BMP, GIF, NumPy and microscope-format images (`.czi`, `.nd2`, `.lif`, ...;
-`io.UNSUPPORTED_IMAGE_EXTENSIONS`) are refused by name, never skipped (exported
-`.npy` patches are still written and read back). OME-Zarr images are folders ending
-in `.zarr`, read from level 0 of their only image, with their axes from the
-OME-NGFF metadata put into `common.image_axes` by role (`io.read_image`);
-discovery never enters them, and `img.ome.zarr` pairs with masks named like
-`img_cells.tif` or `cells/img.tif`. With `common.mask_source="ngff_labels"`, the masks of OME-Zarr
-images are their own OME-NGFF label images (`common.mask_label_name`,
-`io.read_ngff_mask`, contract §4) instead of a mask folder. Matching is
-paired by the preprocessing brick's `find_masks` (`io.pair_masks`, used by
-`validate_image_and_mask_folders` and both run entry points; issue #45): a
-mask is a TIFF file `<mask type>/<image's folders>/<image name>.tif` or
-`<image's folders>/<image name>_<mask type>.tif` in a mask folder outside the
-image root, the image name being its `position_id` (D85);
-`config.matching.mask_type` picks the type (None: the only one). Its header
-checks (preprocessing v0.3.2) are refused for the type used and ignored for the
-other types; CellPatcher also checks masks with its own axes on reading, and
-refuses `common.mask_axes` that disagree with the axes a mask's header names
-(`io.refuse_mask_header_axes`, read with preprocessing `inspect_image`; a ZYX mask
-declared TYX would read Z slices as time points). `common.image_axes` is checked
-the same way against each TIFF image's header (`io.refuse_image_header_axes`) in
-folder and tree runs (every leaf before any runs) and in lazy delivery from files,
-which also checks mask files; OME-Zarr images are matched by role instead. Mask
-files with a channel (C) axis or without axis metadata are refused, never
-guessed, and `common.mask_axes` with a `C` is refused for mask-folder masks
-(owner decision of 2026-10-30): users save one mask type per file
-(`<image>_cells.tif`, `<image>_nuclei.tif`) and name a stack's Z/T axes.
+refused by the preprocessing run (`duplicate_mask`, rc1). Since CP-2b CellPatcher
+discovers, pairs and reads no file itself for any run: `validate_image_and_mask_folders`
+returns the run's recorded pairing and lazy delivery reads through the run
+(`iter_run_patch_arrays`). What the preprocessing run applied: images are found with
+its `discover_experiment` (TIFF files and OME-Zarr images; `io.discover_images` still
+wraps it for `discover_condition_repeat_folders`, refusing PNG, JPEG, BMP, GIF, NumPy
+and microscope-format images by name, `io.UNSUPPORTED_IMAGE_EXTENSIONS`), and masks are
+paired by its `find_masks`: a TIFF file `<mask type>/<image's folders>/<image name>.tif`
+or `<image's folders>/<image name>_<mask type>.tif` in a masks folder outside the
+experiment, the image name being its `position_id` (D85), or an OME-Zarr image's own
+label image (its type is its name); `config.matching.mask_type` picks the type (None:
+the only one). The run checks every image's and mask's axes against its header (design
+v0.4 §3; nothing is read transposed) and refuses masks with a channel axis or unnamed
+extra axes (one mask type per file, named Z/T axes). Removed in CP-2b:
+`common.mask_source`/`mask_label_name` (a config file holding their defaults still
+loads), `io.read_image`/`conform_axes`/`read_ngff_mask`, the header-axis checks
+(`io.refuse_image_header_axes`, `refuse_mask_header_axes`) and `planes.read_file_plane`.
 
 Two ways to point CellPatcher at input data:
 
@@ -326,7 +321,12 @@ Two ways to point CellPatcher at input data:
   (`cellpatcher.RUN_CONFIG_FILENAME`) with the full run config — every CSV
   row's `config_file` column names it — so a row plus that file fully
   determine how to reproduce the patch (coordinates, strategy parameters
-  including `random.seed`, extraction/resize settings, axes).
+  including `random.seed`, extraction/resize settings, axes). Version 2 since
+  v0.2.0 (CP-2b): `run_config_version: 2` and, when a preprocessing run was read,
+  `preprocessing` = {`run`, `manifest_sha256`, and for a folder or tree run
+  `layout` (`image`, `mask`)}; a folder or tree run records no
+  `common.image_axes`/`mask_axes`/labels (MorphoRelate's `common.image_axes`
+  check then reports "not checked"). Readers refuse versions other than 1 and 2.
 - For `run_patching_condition_repeat_tree`, one `patches.csv` +
   `run_config.json` pair per
   `<condition>/<biological_repeat>[/<technical_repeat>]/` output folder by
@@ -349,9 +349,8 @@ Two ways to point CellPatcher at input data:
   later, `position_id` (the one its patches carry, also for an image
   without patches; always filled since decision D45) and
   `n_regions`/`n_kept`/`n_normalized` (counts after the patch mode, the
-  filters and normalization) and `image_read_transposed` (the image's
-  header Y and X declared swapped, read transposed; v0.1.2 only, as
-  a swap is refused since v0.2.0). There is no
+  filters and normalization) (v0.1.2's last column `image_read_transposed`
+  was removed in v0.2.0, CP-2b). There is no
   `failed` status: a failing image stops the run with an error before any
   table is written. Every `patches.csv` row joins exactly one `images.csv`
   row on `condition`/`biological_repeat`/`technical_repeat`/`image_id`/
@@ -404,7 +403,7 @@ bricks (core dependencies, pinned tags in `setup.py`), CellPatcher:
   `run_manifest.json`, all required; `cellpatcher.statistics`) and runs the
   checks of contract §5;
 - splits Z/T stacks into planes (`common.z_policy`/`t_policy`) and reads
-  OME-Zarr images and OME-NGFF label masks (`common.mask_source`) (see
+  OME-Zarr images and OME-NGFF label masks through the preprocessing run (see
   "Inputs" above);
 - normalizes patches (`config.normalization`, `cellpatcher.normalization`)
   at the biological-repeat scope (across conditions, from the preprocessing
diff --git a/docs/api_examples.md b/docs/api_examples.md
index 982e6ab..742abd5 100644
--- a/docs/api_examples.md
+++ b/docs/api_examples.md
@@ -128,14 +128,15 @@ print(len(result.patches))  # 1
 
 ## Example 5 — Folder matching and loading
 
-Use this pattern when images and masks live in separate folders and need reliable pairing. The pairing is the preprocessing brick's (`morphobricks_preprocessing.find_masks`): masks are TIFF files named `<image name>_<mask type>.tif` or `<mask type>/<image name>.tif` (see [`config.matching`](configuration_reference.md)).
+Use this pattern to list the image/mask pairs of a preprocessing run. The pairing is the preprocessing run's (its `find_masks`; since v0.2.0 CellPatcher pairs nothing itself): masks are TIFF files named `<image name>_<mask type>.tif` or `<mask type>/<image name>.tif` (see [`config.matching`](configuration_reference.md)).
 
 ```python
 # ./masks holds img_01_cells.tif, img_01_nuclei.tif, ...: choose the type.
-# pairs is a dict[Path, Path]: {image_path: mask_path} for every image
+# pairs is a dict[Path, Path]: {image_path: mask_path} for every image of the run
 pairs = validate_image_and_mask_folders(
     image_folder_path="./images",
     mask_folder_path="./masks",
+    preprocessing_run="./images_MorphoBricks_Preprocessing",
     mask_type="cells",
 )
 
diff --git a/docs/configuration_reference.md b/docs/configuration_reference.md
index 9d088f7..2d7b20c 100644
--- a/docs/configuration_reference.md
+++ b/docs/configuration_reference.md
@@ -14,20 +14,21 @@ This document is the complete runtime configuration reference for `CellPatcherCo
 
 ---
 
-## File runs read through the preprocessing run (v0.2.0, CP-2a)
+## File runs read through the preprocessing run (v0.2.0, CP-2a and CP-2b)
 
 `run_patching_pipeline`, `run_patching_condition_repeat_tree` and `run_patching_from_folders` read files only through a clean preprocessing run (v0.4), `common.preprocessing_run`, with the preprocessing brick's `RunInputs` (design v0.4 §6). Without it they stop with `no_preprocessing_run` and the preprocessing command (`morphobricks-preprocessing check <experiment> --masks <masks folder>`, then `morphobricks-preprocessing run <experiment> --axes <roles> --masks <masks folder>`).
 
 - **Where the experiment is now.** The run is opened with `RunInputs.open(run, experiment_root=<image folder or root>, masks_root=<mask_folder_path or mask_root_path>)`; a masks folder left out is where the run recorded it. An experiment moved or copied since its run is checked and read where CellPatcher is given it: every image and mask must have the size and modification time the run recorded (copy with the times kept, e.g. `cp -p` or `shutil.copytree`), or the run is refused (`preprocessing_run_refused`, naming the files).
 - **Images.** The run's images (`RunInputs.fovs()`), sorted by path, read with `RunInputs.read_plane` in the roles the run recorded. Their arrays are in one canonical layout per run: T and Z when an image of the run has more than one plane along them, C when an image has a channel role, in that order, then Y and X (`ZCYX`, `TYX`, `CYX`, `YX`, ...). Nothing is read transposed; an image without one of these axes is its one plane along it. With plane policies only the chosen planes are read. An image added to the experiment after the run is not part of it, so not patched (a brick calls no `discover_experiment` for files); run preprocessing again to include it. **Known limitation:** nothing says so yet. Preprocessing will give bricks a check for images added after the run (a later preprocessing PR, not in v0.4.0rc1); CellPatcher will call it then, rather than discover images itself.
 - **Labels and `position_id`.** Each image's `condition`, `biological_repeat`, `technical_repeat` and `position_id` are the ones the run recorded, never parsed. `run_patching_pipeline` patches a run of one condition and biological repeat (any technical repeats); use the tree run for more.
+- **Masks folder in `grid`/`whole_fov` mode.** These modes read no masks; `mask_folder_path` (or `mask_root_path`) given with them only says where the run's masks folder is now, and its masks are checked there (owner decision of 2026-11-02; before CP-2b the folder run refused it).
 - **Masks.** Those the run paired (masks-folder TIFFs and the label images of OME-Zarr images; a label image's type is its name), read with `RunInputs.read_mask` (the brick checks their labels). `matching.mask_type` chooses the type; `None` takes the run's only type. `cell` mode always reads masks; `random` mode when a masks folder or `matching.mask_type` is given. Every image needs a mask of the type. The mask arrays follow one layout per run too (the T and Z any mask of the run has, then Y and X); a mask without one of them (a 2-D mask of a one-plane image, or a stated shared 2-D mask) has length 1 along it. A mask the run recorded without axes (rc1 records one whose header it could not use, e.g. X before Y) is refused. A folder mask and a label image of the same type for one image are refused by the preprocessing run (`duplicate_mask`), so no clean run has them.
 - **Normalization.** The CSV scopes read the run's own table (`normalization.plane_histograms` may be left unset, or must name it: `not_the_run_output`), design and image type.
-- **`run_config.json`** records `common.preprocessing_run` and, as `common.image_axes`/`mask_axes`, the layout the patches were read in.
-- **Migration.** For file runs, `common.image_axes`/`mask_axes` other than `"YX"`, `common.mask_source="ngff_labels"`, `common.mask_label_name`, and `common.condition`/`biological_repeat`/`technical_repeat` other than `"single"` are refused with a message saying what replaces them (CP-2b removes them for file runs). The axes and labels still describe in-memory arrays given to `run_patching`; `mask_source` and `mask_label_name` are not used there.
+- **`run_config.json`** (version 2, CP-2b; see "Deterministic reconstruction" below) records `run_config_version: 2` and a `preprocessing` section: the run (`run`), the SHA-256 of its `run_manifest.json` when the call opened it (`manifest_sha256`), and the `layout` (`image`, `mask`) the patches were read in. It does not record `common.image_axes`, `mask_axes` or the labels (the run's, not settings), so it loads back with `load_config` as a config a file run accepts.
+- **Migration.** For file runs, `common.image_axes`/`mask_axes` other than `"YX"`, `common.condition`/`biological_repeat`/`technical_repeat` other than `"single"` and `normalization.experiment_root`/`masks_root` are refused with a message saying what replaces them. The axes and labels still describe in-memory arrays given to `run_patching`. `common.mask_source` and `mask_label_name` were removed in CP-2b: `CommonConfig(mask_source=...)` is a `TypeError`; a config file holding their defaults still loads, one with another value is refused.
 - **Within one call** (`run_patching`, a folder or tree run) the run is opened once; nothing is kept beyond the call, so the next call checks every image and mask again (`cellpatcher.run_session`).
 
-Still read by CellPatcher until CP-2b: lazy delivery from a file path (`patch_array`/`iter_patch_arrays` with paths, using `common.image_axes`), and `validate_image_and_mask_folders` (`pair_masks`).
+**No file is read or paired by CellPatcher itself** (CP-2b). `validate_image_and_mask_folders(image_folder, mask_folder, *, preprocessing_run=, mask_type=)` returns the pairing the run recorded, opened where the folders are now. Lazy delivery of a file run's patches is `iter_run_patch_arrays(patches, config, *, experiment_root=, masks_root=)`, which reads each patch's plane with `RunInputs.read_plane` (its mask with `read_mask`) from the run's image at the patch's `source_relative_path`, and refuses a patch whose image or FOV key is not the run's; `patch_array`, `iter_patch_arrays` and `PatchTorchDataset` take arrays only (a path is a `TypeError`).
 
 ---
 
@@ -37,8 +38,8 @@ Shared settings that apply to every run, regardless of mode.
 
 | Field | Type | Default | Notes |
 |---|---|---|---|
-| `image_axes` | `str` | `"YX"` | Axes string for image arrays given to `run_patching` (e.g. `"YX"`, `"CYX"`, `"ZYX"`). Must include `Y` and `X`. Since v0.2.0 (CP-2a) folder and tree runs read the roles the preprocessing run recorded, refuse any other value than `"YX"`, and record the layout they read in `run_config.json`; the rest of this row is about lazy delivery from a file path. A TIFF image file's header is checked against it before any pixel is read, with the preprocessing brick's axis check (`review_axes`: `check_mapping` and `header_axis_issue`, design v0.4 §3): it may name what the header leaves open (a placeholder axis; the positional Y and X of a plain stack of pages, so a plain `QYX` stack may be declared `YXC`), never contradict an axis the metadata names. A Y/X swap (header `ZYX` declared `ZXY`, `axes_yx_swapped`) and a plain stack's Y and X declared X before Y (`axes_x_before_y`) are refused too: nothing is ever read transposed (since v0.2.0; v0.1.2 read a swapped image transposed). With a CSV normalization scope (`image`, `biological_repeat`), the axes must also give the roles the preprocessing run recorded (`check_sources`, `axis_mapping_mismatch`). Anything else (another order, another number of axes, an unreadable header) is refused naming the file. OME-Zarr images are matched by role instead (see "OME-Zarr images"). |
-| `mask_axes` | `str` | `"YX"` | Axes string for mask arrays given to `run_patching`. Must include `Y` and `X`. Since v0.2.0 (CP-2a) folder and tree runs read masks in the roles the preprocessing run recorded and refuse any other value than `"YX"`. Masks read from a mask folder (`mask_source="tiff_tree"`) cannot have a `C` axis: a `C` here is refused for folder and tree runs, since it would read a mask's other axes as label channels (owner decision of 2026-10-30). Save each label channel as its own mask type instead (`<image>_cells.tif`, `<image>_nuclei.tif`) and choose one with `matching.mask_type`. A TIFF mask file's header is checked as for `image_axes` (a Y/X swap is refused). CellPatcher takes a label plane's two dimensions as Y and X in their stored order, so any `mask_axes` with X before Y (`"XY"`, `"ZXY"`) is refused, for in-memory masks and OME-Zarr labels too (before v0.1.2 it was ignored for in-memory masks). The refusal says how to fix the masks: save each one with Y before X (its last two axes swapped, e.g. `numpy.swapaxes(mask, -1, -2)`) and declare those axes. Nothing is ever read transposed. |
+| `image_axes` | `str` | `"YX"` | Axes string for image arrays given to `run_patching` (e.g. `"YX"`, `"CYX"`, `"ZYX"`). Must include `Y` and `X`. Since v0.2.0 (CP-2a) folder and tree runs read the roles the preprocessing run recorded, refuse any other value than `"YX"`, and record the layout they read in `run_config.json`'s `preprocessing.layout` (CP-2b). Since CP-2b no file is read with these axes (lazy delivery takes arrays; see "File runs read through the preprocessing run"), so CellPatcher checks no file header against them: the preprocessing run checks each file's axes (design v0.4 §3; nothing is ever read transposed). |
+| `mask_axes` | `str` | `"YX"` | Axes string for mask arrays given to `run_patching`. Must include `Y` and `X`. Since v0.2.0 (CP-2a) folder and tree runs read masks in the roles the preprocessing run recorded and refuse any other value than `"YX"`. CellPatcher takes a label plane's two dimensions as Y and X in their stored order, so any `mask_axes` with X before Y (`"XY"`, `"ZXY"`) is refused (before v0.1.2 it was ignored for in-memory masks). The refusal says how to fix the masks: give each one with Y before X (its last two axes swapped, e.g. `numpy.swapaxes(mask, -1, -2)`) and declare those axes. Nothing is ever read transposed. |
 | `preprocessing_run` | `str \| None` | `None` | The output folder of the clean preprocessing run (v0.4) that folder and tree runs read their images, masks and labels through (see "File runs read through the preprocessing run"). Required for them; not used by in-memory `run_patching` (its CSV normalization reads `normalization.plane_histograms`). Since v0.2.0. |
 | `output_dir` | `str \| None` | `None` | Output folder path. Required when `export.enabled=True`; keep `None` for in-memory-only runs. |
 | `extract_arrays` | `bool` | `False` | When `True`, extracted patch arrays are returned in `PatchingResult.patch_arrays`. |
@@ -50,8 +51,6 @@ Shared settings that apply to every run, regardless of mode.
 | `z_index` | `int \| None` | `None` | Z plane for `z_policy="select"`. |
 | `t_policy` | `str` | `"keep"` | As `z_policy` for a T axis: `"keep"`, `"all"` (sets `t`, a `t<NNNN>` level of `patch_id`), `"first"` or `"select"`; no projections. With both split, planes come in T-then-Z order (`.../t0001/z002/...`). |
 | `t_index` | `int \| None` | `None` | Time point for `t_policy="select"`. |
-| `mask_source` | `str` | `"tiff_tree"` | Before v0.2.0, where folder and tree runs read masks; since CP-2a they read the masks the preprocessing run paired, and `"ngff_labels"` is refused with a migration message (a label image's type is its name: choose it with `matching.mask_type`). Former meaning: `"tiff_tree"`: a mask folder (or tree) mirroring the images, paired with the preprocessing brick's rule (`config.matching`). `"ngff_labels"`: the label image of each OME-Zarr image's own `labels` group (no mask folder; every image must be OME-Zarr). See "OME-Zarr images" below. |
-| `mask_label_name` | `str \| None` | `None` | Refused for folder and tree runs since CP-2a (use `matching.mask_type`). Former meaning: with `mask_source="ngff_labels"`, the label image to use (e.g. `"cells"`); may stay `None` when every image has exactly one. |
 | `object_set` | `str \| None` | `None` | Cell mode: the name of the object set (mask) written to the `object_set` column and to `patch_id`. `None`: named after the mask (see "Patch identity" below), `"mask"` when the mask gives no name. Letters, digits, `.`, `_`, `-` only. |
 
 **Masks with split planes:** a mask's Z or T axis with the image's length follows the image's planes (one label plane per image plane); a mask without that axis, or with length 1, is shared by every plane. Any other length is an error, and so is a Z projection with masks that follow the Z planes. Image ids stay one per source image, and every plane and channel patch of an image shares one `position_id`.
@@ -171,7 +170,7 @@ Controls whether and how patch arrays are written to disk.
 
 ## Finding images
 
-Images are found with the **MorphoBricks preprocessing brick's `discover_experiment`** (through `cellpatcher.io.discover_images`; issue #45, owner decision of 2026-10-30), in folder runs, tree runs and `validate_image_and_mask_folders`. CellPatcher has no folder walk of its own, so it patches the images the preprocessing brick measures and normalizes, under the same labels.
+Images are found with the **MorphoBricks preprocessing brick's `discover_experiment`** (through `cellpatcher.io.discover_images`; issue #45, owner decision of 2026-10-30) in `discover_condition_repeat_folders` and `list_supported_files`. Since v0.2.0 folder and tree runs patch the images their preprocessing run recorded and discover nothing (design v0.4 §6); the rules below are the brick's, which that run applied.
 
 - **Images are TIFF files** (`.tif`, `.tiff`, any case, optional `.ome`) **and OME-Zarr folders** (`.zarr`, usually `.ome.zarr`). Nothing else is an image.
 - **PNG, JPEG, BMP, GIF and NumPy (`.npy`) images are no longer read**, and microscope formats (`.czi`, `.nd2`, `.lif`, `.lsm`, `.ims`, `.vsi`, ...; `cellpatcher.io.UNSUPPORTED_IMAGE_EXTENSIONS`) never were. Such a file where images are found is refused with an error naming it, never skipped: convert it to TIFF or OME-Zarr, or move it out of the image folder. Other files (`.txt`, `.csv`, ...) are ignored, as before. Exported patches may still be written as `.npy` (`export.image_format`) and are read back by `read_array` and the Torch dataset.
@@ -185,7 +184,7 @@ Images are found with the **MorphoBricks preprocessing brick's `discover_experim
 
 ## `config.matching` (`MatchConfig`, which masks to pair)
 
-Images and masks are paired with the **MorphoBricks preprocessing brick's rule**: CellPatcher calls `morphobricks_preprocessing.find_masks` (through `cellpatcher.io.pair_masks`) and has no pairing rule of its own, so CellPatcher, the preprocessing brick and the bricks that use its discovery pair the same files (issue #45, owner decision of 2026-10-30).
+Images and masks are paired by the **preprocessing run** (its `find_masks`; issue #45, owner decision of 2026-10-30). Since v0.2.0 CellPatcher reads the pairing the run recorded (`RunInputs.read_mask`; `validate_image_and_mask_folders` returns it) and has no pairing of its own (`pair_masks` was removed in CP-2b), so every brick reads the same pairs. The layouts below are the brick's.
 
 A mask is a **TIFF file** (`.tif`, `.tiff`, any case, optional `.ome`) in the mask folder, in either layout (they may be mixed):
 
@@ -198,16 +197,9 @@ The image's folders are its path below the image folder (folder run: none) or th
 
 | Field | Type | Default | Notes |
 |---|---|---|---|
-| `mask_type` | `str \| None` | `None` | The mask type to use (`"cells"` for `img_cells.tif` or `cells/img.tif`, or a label image's name). Folder and tree runs (CP-2a): one of the types the preprocessing run recorded; `None` takes the run's only type and refuses a run with several. For `validate_image_and_mask_folders`: The types are the mask folder's: since v0.2.0 (preprocessing v0.4, which pairs an OME-Zarr image's own label images too) a label image is read only with `common.mask_source="ngff_labels"`, and a label image and a folder mask of the same type for one image are refused (`duplicate_mask`). |
+| `mask_type` | `str \| None` | `None` | The mask type to use (`"cells"` for `img_cells.tif` or `cells/img.tif`, or a label image's name). Folder and tree runs (CP-2a): one of the types the preprocessing run recorded; `None` takes the run's only type and refuses a run with several. `validate_image_and_mask_folders(..., mask_type=)` chooses the same way. A label image and a folder mask of the same type for one image are refused by the preprocessing run (`duplicate_mask`). |
 
-Refused, never resolved by a guess or silently skipped:
-
-- a mask that could belong to two images or two types (an image name that starts another image's name: `a_seg_mask.tif` with images `a` and `a_seg`);
-- a file in the mask folder that pairs with no image (including a mask named exactly like its image, `masks/img.tif`, and a non-TIFF mask such as `img_mask.npy`);
-- an image with no mask of the type used (in `cell` mode, and in `random` mode when a mask folder is given);
-- two mask types whose names differ only in case, or two masks of one image and type.
-
-`find_masks`'s header checks are refused for the masks of the type used and ignored for the other types, which are never read (owner decision, preprocessing v0.3.2): an unreadable mask (`unreadable_mask`), a mask with axes other than Y, X and Z/T axes its metadata names (`mask_not_2d`: a stack written without axes, or a channel axis, is refused; no axis is guessed. Save each label channel as its own mask type, for example `<image>_cells.tif` and `<image>_nuclei.tif`, and save a Z or T stack with its Z/T axes named, as an ImageJ hyperstack or an OME-TIFF. `common.mask_axes` with a `C` axis is refused for these masks), another Y/X size than its image (`mask_size_mismatch`), non-integer pixels (`mask_pixel_type`), and masks of the type used with different depth slices or time points for one image (`mask_planes_differ`; the same difference between two types, one of them unused, is ignored). CellPatcher also checks each mask against its image when it reads it, with `common.mask_axes`. System files (`._img.tif`, other names starting with `.`, `Thumbs.db`, `desktop.ini`, `__MACOSX`) are skipped in image and mask folders, as in the preprocessing brick.
+The preprocessing run refuses an ambiguous mask (one that could belong to two images or two types), a mask whose header it cannot use (no Y/X of its image, non-integer pixels, axes other than Y, X and named Z/T: save each label channel as its own mask type), and two masks of one type for one image; a file in the masks folder that pairs with no image is a warning in its report. CellPatcher refuses an image the run recorded no mask of the type for (in `cell` mode, and in `random` mode when masks are read), and reads each mask's labels through the brick's `check_labels`.
 
 **Former options (removed in v0.1.1).** `strategy`, `mask_suffixes`, `case_sensitive` and `ignore_unrequested_masks` (in `MatchConfig`, a `run_config.json`'s `matching` section, and as arguments of `validate_image_and_mask_folders`, `run_patching_pipeline`, `run_patching_condition_repeat_tree` and `run_patching_from_folders`) are refused by name with a `ValueError` saying to use `matching.mask_type`, whatever their value: an old `run_config.json` that holds them fails until they are removed from its `matching` section. `find_candidate_matches`, `filter_shared_matches`, `select_requested_masks`, `LEGACY_MATCHING_DEFAULTS` and `cellpatcher.io.image_stem` were removed with them (D86).
 
@@ -230,6 +222,7 @@ Normalization with the statistics of the preprocessing brick, following the [nor
 | `percentile` | `(float, float)` | `(1.0, 99.8)` | Low and high percentile for `"percentile"`, `0 ≤ low < high ≤ 100`. |
 | `scope` | `str` | `"image"` | Pixels the parameters come from: `"biological_repeat"` (one repeat group: the same biological repeat in every condition, technical repeats merged, as paired in the preprocessing brick's `experiment_design.csv`), `"image"` (all Z and T planes of the source image) or `"patch"` (the patch's own pixels). Per channel, except for `image_type="rgb"`. `"condition"` and `"technical_repeat"` were removed (October 2026) and are refused. |
 | `per_time_point` | `bool` | `False` | Normalize each time point separately (`t` joins the group). |
+| `experiment_root`, `masks_root` | `str \| None` | `None` | For `run_patching` at a CSV scope: where the run's experiment and masks folder are now, when moved since the run (owner decision of 2026-11-02); `None`: where the run recorded them. Folder and tree runs refuse them: their image folder/root and `mask_folder_path`/`mask_root_path` say it. Since v0.2.0 (CP-2b). |
 | `experiment_design` | `str \| None` | `None` | For `scope="biological_repeat"`: the preprocessing run's `experiment_design.csv`, which must be the one next to `plane_histograms` (`not_the_run_output` otherwise); `None` uses it. Every repeat group must be confirmed, the file must be the one the run's manifest records, and a run that recorded no design is refused (`missing_experiment_design`). |
 | `pooling` | `str` | `"pixels"` | For `scope="biological_repeat"`: `"pixels"` (each pixel counts once) or `"conditions"` (each condition of a repeat group weighs the same). |
 | `image_type` | `str` | `"fluorescence"` | `"fluorescence"` (each channel normalized separately) or `"rgb"`: colour images of three 8- or 16-bit channels, normalized with StarDist's percentile method, one offset and scale from the R, G and B pixels together (written for `C0`, `C1` and `C2`). `"rgb"` needs `method="percentile"` and `extraction.split_channels=False`. When the preprocessing manifest records an image type, this must be the same. |
@@ -245,15 +238,15 @@ Normalization with the statistics of the preprocessing brick, following the [nor
 | Normalized files (default) | `export.enabled=True` | float32 `.tif`/`.npy` |
 | Raw files plus parameters | `export.enabled=True`, `normalization.export_values="raw"`; read back with `cellpatcher.iter_exported_patches(csv)`/`load_exported_patch` or `ExportedPatchTorchDataset`, which normalize on load with each row's `Normalization_Offset_C<i>`/`Normalization_Scale_C<i>` columns (never recomputed; the `;`-separated `normalization_offset`/`normalization_scale` of earlier tables are read too) | Source dtype when the patch is only cropped; float32 raw values when resized or masked |
 | In memory, eager | `common.extract_arrays=True` | float32 arrays in `PatchingResult.patch_arrays`, within `memory_limit` |
-| In memory, lazy | Run with `extract_arrays=False` (the patches still record their normalization), then `cellpatcher.iter_patch_arrays(patches, images, config, masks=...)` or `patch_array(...)`; `PatchTorchDataset(images, patches, config=config)` is built on them | float32, one patch at a time |
+| In memory, lazy | Run with `extract_arrays=False` (the patches still record their normalization), then, for `run_patching`'s arrays, `cellpatcher.iter_patch_arrays(patches, images, config, masks=...)` or `patch_array(...)` (`PatchTorchDataset(images, patches, config=config)` is built on them), and for a folder or tree run `cellpatcher.iter_run_patch_arrays(patches, config)`, which reads one plane at a time through the preprocessing run | float32, one patch at a time |
 
 ```python
-from cellpatcher import iter_patch_arrays, list_supported_files, run_patching_condition_repeat_tree
+from cellpatcher import iter_run_patch_arrays, run_patching_condition_repeat_tree
 
-for leaf in run_patching_condition_repeat_tree(root, config=config):  # extract_arrays=False
-    images = list_supported_files(leaf.image_folder)  # paths: read one plane at a time
-    for patch, array in iter_patch_arrays(leaf.result.patches, images, config):
-        ...  # one normalized patch at a time
+leaves = run_patching_condition_repeat_tree(root, config=config)  # extract_arrays=False
+patches = [patch for leaf in leaves for patch in leaf.result.patches]
+for patch, array in iter_run_patch_arrays(patches, config):  # experiment_root=, masks_root= if moved
+    ...  # one normalized patch at a time
 ```
 
 **What happens** (contract §6–§9):
@@ -268,9 +261,9 @@ for leaf in run_patching_condition_repeat_tree(root, config=config):  # extract_
 
 **Recorded:** written after `source_relative_path` in `patches.csv`: `normalization_method` (e.g. `percentile 1-99.8`), `normalization_scope`, `normalization_group` (the repeat group label, `<source_relative_path>`, or `<source_relative_path>::<patch_id>` for the patch scope; `::t=<t>` with `per_time_point`) and `normalization_exact` (`true`/`false`), then one `Normalization_Offset_C<i>`/`Normalization_Scale_C<i>` pair per channel, grouped by channel (full-precision numbers from the normalization brick's `Parameters.to_columns()`; a split-channel patch fills only its own channel's pair). In memory, `PatchRegion.normalization_parameters` is the brick's `Parameters` (`offset`, `scale`, `channels`); `normalization_offset`/`normalization_scale` are deprecated read-only properties giving the former `;`-separated text. `run_config.json` gains the `normalization` section, a top-level `normalization_inputs` object (`plane_histograms_sha256`, `schema_version`, `manifest_used`, `manifest_version`, `preprocessing_version`, and for `biological_repeat` `experiment_design_file`/`experiment_design_sha256`) and `normalization_settings` (the brick's `NormalizationSettings.to_dict()`); a `run_config.json` without `normalization` loads with normalization off. With normalization, the images of a run must have the same number of channels.
 
-**In-memory runs:** `run_patching` normalizes too; for the CSV scopes each image needs `image_metadata=[{"source_relative_path": ...}]` and the right `common` labels (folder and tree runs fill both). The manifest's file checks run in folder and tree runs.
+**In-memory runs:** `run_patching` normalizes too; for the CSV scopes each image needs `image_metadata=[{"source_relative_path": ...}]` and the right `common` labels (folder and tree runs fill both). The run is opened where it recorded the experiment and masks folder, or where `normalization.experiment_root`/`masks_root` say they are now (an experiment moved since the run; owner decision of 2026-11-02). The manifest's file checks run in folder and tree runs.
 
-The `common.mask_source` and `common.mask_label_name` fields for OME-Zarr label masks (contract §4) exist since Milestone 2, and `cellpatcher.statistics` (loading `plane_histograms.csv`/`run_manifest.json`, contract §5 checks) since Milestone 1.
+`cellpatcher.statistics` (loading `plane_histograms.csv`/`run_manifest.json`, contract §5 checks) exists since Milestone 1.
 
 ---
 
@@ -388,9 +381,7 @@ Wherever `patches.csv` is written (`export.enabled=True` with `save_metadata_csv
 | `reason` | Empty for `processed`. For `no_patches`, the step that left none: `the patch mode generated no region in this image` (e.g. no labeled object in its mask, every object excluded by border or area), `the filters removed all <n> region(s)`, or `normalization discarded all <n> patch(es): they cannot be normalized from their own pixels` (decision D8). For `skipped`: `the image has no plane to patch along the axes split by z_policy/t_policy` (a Z or T axis of length 0 with `"all"`). |
 | `position_id` | The `position_id` every patch of the image carries in `patches.csv`, also for an image without patches: supplied via `image_metadata`, or the default of "Patch identity" above (one file is one position). Never empty since 2026-10-26. |
 | `n_regions`, `n_kept`, `n_normalized` | Regions the patch mode generated, those left by the filters, and those left by normalization (equal to `n_kept` without it), counted before `split_channels`; they tell the three `no_patches` reasons apart without reading `reason`. `0` for a skipped image. |
-| `image_read_transposed` | `true` when `common.image_axes` declared the image file's header Y and X swapped, so the image was read transposed (v0.1.2 only: since v0.2.0 a swap is refused, and folder and tree runs read every image through the preprocessing run, so it is always `false` for them, OME-Zarr images included); empty for an in-memory array. CP-2b removes the column. Since v0.1.2. |
-
-`position_id`, `n_regions`, `n_kept`, `n_normalized` and `image_read_transposed` were added after the first release of the table, as its last columns, so earlier columns keep their positions.
+`position_id`, `n_regions`, `n_kept`, `n_normalized` were added after the first release of the table, as its last columns, so earlier columns keep their positions. The last column of v0.1.2, `image_read_transposed`, was removed in v0.2.0 (CP-2b): since preprocessing v0.4 refuses every Y/X swap it was always `false` or empty.
 
 There is no `failed` status: an image that cannot be read, matched to a mask or patched stops the whole run with an error before any table is written, as before, so no image is ever left out silently.
 
@@ -398,9 +389,9 @@ There is no `failed` status: an image that cannot be read, matched to a mask or
 
 ### OME-Zarr images
 
-Since v0.2.0 (CP-2a) folder and tree runs read OME-Zarr images and their label images through the preprocessing run like any other image (see "File runs read through the preprocessing run"); this section describes `read_array`, `read_image` and lazy delivery from a path. With the `zarr` extra (`pip install "cellpatcher[zarr]"`), folders whose names end in `.zarr` (usually `.ome.zarr`) are images for `read_array` and lazy delivery (folder and tree runs take them from the preprocessing run). CellPatcher reads level 0 of the store's only image with the preprocessing brick's reader; a store with several images (positions, series or plate wells) is an error. The axes come from the OME-NGFF metadata and are matched to `common.image_axes` (or `mask_axes`) by role: a length-1 axis that the configured axes lack is dropped, a configured axis the store lacks is added with length 1, and the dimensions are reordered; any other mismatch is an error. Discovery never enters a store, and `img.ome.zarr` pairs with masks named like `img_cells.tif` or `cells/img.tif`. Without the extra, reading a store stops with the install command. OME-Zarr copies written by the preprocessing brick are not read: CellPatcher reads the source images.
+Since v0.2.0 (CP-2a) folder and tree runs read OME-Zarr images and their label images through the preprocessing run like any other image (see "File runs read through the preprocessing run"); this section describes `read_array` and discovery. With the `zarr` extra (`pip install "cellpatcher[zarr]"`), folders whose names end in `.zarr` (usually `.ome.zarr`) are images for `read_array`, which reads level 0 of the store's only image, in its stored axis order, with the preprocessing brick's reader; a store with several images (positions, series or plate wells) is an error. (`read_image`, which put a store into `common.image_axes` by role, was removed in CP-2b with lazy delivery from a path.) Discovery never enters a store, and `img.ome.zarr` pairs with masks named like `img_cells.tif` or `cells/img.tif`. Without the extra, reading a store stops with the install command. OME-Zarr copies written by the preprocessing brick are not read: CellPatcher reads the source images.
 
-**Masks from OME-NGFF labels (before v0.2.0; folder and tree runs now read the label images the preprocessing run paired, by type):** with `common.mask_source="ngff_labels"`, each OME-Zarr image's mask is its label image `common.mask_label_name` (from its `labels` group, OME-NGFF 0.4 and 0.5; the name may stay `None` when there is only one). Level 0 is read; its values must be integers, each dimension must equal the image's or have length 1, and a channel dimension must have length 1. It is then put into `common.mask_axes` by role, so a label Z or T axis with the image's length follows the image's planes and one of length 1 is shared (`z_policy`/`t_policy`). `mask_file` is written as `<image>.ome.zarr/labels/<name>`. A mask folder, or an image that is not OME-Zarr, is an error with this source.
+**Masks from OME-NGFF labels:** a folder or tree run reads the label images the preprocessing run paired, a label image's type being its name (`matching.mask_type`); `mask_file` is `<image>.ome.zarr/labels/<name>`. The former `common.mask_source="ngff_labels"`/`mask_label_name` were removed in v0.2.0 (CP-2b).
 
 ### Condition/biological-repeat folder trees
 
@@ -438,7 +429,8 @@ Output is identical whichever name is used; files are always written with `biolo
 Each exported `patches.csv` row, together with the `run_config.json` file it references via `config_file` (written alongside it whenever `export.enabled=True`; see `cellpatcher.RUN_CONFIG_FILENAME`), is enough to reconstruct the patch without re-deriving anything from code:
 
 - The row's own coordinates (`y0/y1/x0/x1`, `z0/z1`, `t`, `c`) and `output_height`/`output_width` fully describe the patch geometry and final exported array shape; `image_height`/`image_width`, the `pad_*` columns, `resized` and `output_axes` say, without the source image or the config, where the rectangle lies in its image, which pixels of the array are padding, whether the array was resampled and what its axes are.
-- `run_config.json` is the complete, serialized `CellPatcherConfig` for the run — strategy parameters (including `random.seed`), extraction/resize settings, matching strategy, and axes — everything needed to reproduce the same coordinates deterministically from the same inputs.
+- `run_config.json` is the complete, serialized `CellPatcherConfig` for the run — strategy parameters (including `random.seed`), extraction/resize settings, the mask type, and the axes of in-memory arrays — everything needed to reproduce the same coordinates deterministically from the same inputs.
+- Since v0.2.0 (CP-2b) it is **version 2**: `run_config_version: 2`, and when a preprocessing run was read (a folder or tree run, or a CSV normalization scope) a `preprocessing` section with the run (`run`), the SHA-256 of its `run_manifest.json` when the call opened it (`manifest_sha256`), which names the run's images, masks, roles and table exactly, and for a folder or tree run the `layout` (`image`, `mask`) of the arrays it built from the run's recorded roles (T, Z, C, then Y, X). A folder or tree run does not record `common.image_axes`, `mask_axes` or the labels (each patch's labels are in `patches.csv`). `load_config` and the exported-patch readers (`iter_exported_patches`, `load_exported_patch`, `ExportedPatchTorchDataset`) read versions 1 (no version: written before v0.2.0, or a config file) and 2, and refuse any other naming the version.
 
 ## Typed refusals
 
diff --git a/docs/normalization.md b/docs/normalization.md
index 0ea2013..5543f43 100644
--- a/docs/normalization.md
+++ b/docs/normalization.md
@@ -123,8 +123,8 @@ channels never share parameters (except the three channels of an RGB image).
   selected channels. A single-channel patch keeps the parameters of its channel in the image's
   group, so selecting channels never changes their values.
 - **OME-Zarr images** (folders ending in `.zarr`) are read like TIFF files; their masks can be a
-  mask folder or the label images inside them (`common.mask_source="ngff_labels"`, with
-  `common.mask_label_name`).
+  mask folder or the label images inside them, as the preprocessing run paired them (a label
+  image's type is its name: `matching.mask_type`).
 
 ## What is recorded
 
@@ -151,7 +151,7 @@ own settings (`normalization_settings`).
 | Normalized files (default) | `export.enabled=True`: float32 `.tif`/`.npy` files |
 | Raw files plus parameters (smaller, reversible) | `normalization.export_values="raw"`; read them back normalized with `cellpatcher.iter_exported_patches("patches.csv")` or `ExportedPatchTorchDataset`, which apply each row's offset and scale |
 | Arrays in memory | `common.extract_arrays=True` (stops above `normalization.memory_limit`, 4 GiB by default) |
-| One patch at a time (large datasets) | Run with `extract_arrays=False`, then `cellpatcher.iter_patch_arrays(patches, images, config)`; `PatchTorchDataset(images, patches, config=config)` for PyTorch |
+| One patch at a time (large datasets) | Run with `extract_arrays=False`, then `cellpatcher.iter_run_patch_arrays(patches, config)` for a folder or tree run (read through its preprocessing run), or `cellpatcher.iter_patch_arrays(patches, images, config)` for `run_patching`'s arrays; `PatchTorchDataset(images, patches, config=config)` for PyTorch (arrays) |
 
 All of these give the same arrays for the same settings.
 
diff --git a/docs/normalization_contract.md b/docs/normalization_contract.md
index 1586b76..a0f1cb6 100644
--- a/docs/normalization_contract.md
+++ b/docs/normalization_contract.md
@@ -96,7 +96,12 @@ memory limit is an error, even if the preprocessing brick read it in blocks.
 
 ## 4. Masks
 
-`common.mask_source` selects where masks come from:
+Since v0.2.0 folder and tree runs read the masks their preprocessing run paired (a label
+image's type is its name, chosen with `matching.mask_type`); `common.mask_source` and
+`mask_label_name`, which selected the source below before v0.2.0, were removed in CP-2b. The
+rules below are the ones the preprocessing run applies.
+
+Before v0.2.0, `common.mask_source` selected where masks come from:
 
 | Value | Masks | Matching |
 |---|---|---|
@@ -293,7 +298,7 @@ In memory, `PatchRegion.normalization_parameters` holds the brick's `Parameters`
 | Normalized files (default) | `export.enabled=True`, `normalization.export_values="normalized"` | float32 `.tif`/`.npy` |
 | Raw files plus parameters | `export.enabled=True`, `normalization.export_values="raw"` | Source dtype; the columns of §10 hold the parameters, and loaders normalize on load |
 | In memory, eager | `common.extract_arrays=True` | float32 arrays in `PatchingResult.patch_arrays` |
-| In memory, lazy | A NumPy iterator over patches (core) and `PatchTorchDataset` (torch extra) | float32, one patch at a time |
+| In memory, lazy | A NumPy iterator over patches (core: `iter_patch_arrays` for arrays, `iter_run_patch_arrays` for a folder or tree run, read through its preprocessing run) and `PatchTorchDataset` (torch extra, arrays) | float32, one patch at a time |
 
 - All modes give identical arrays for the same configuration.
 - Eager delivery estimates its memory first and stops above `normalization.memory_limit`,
@@ -311,6 +316,7 @@ In memory, `PatchRegion.normalization_parameters` holds the brick's `Parameters`
 | `enabled` | `bool` | `False` | Off keeps current behaviour exactly |
 | `plane_histograms` | `str \| None` | `None` | Path of `plane_histograms.csv` (§5) |
 | `manifest` | `str \| None` | `None` | The run's `run_manifest.json`, next to the CSV; `None` uses it, and another file is refused (§5) |
+| `experiment_root`, `masks_root` | `str \| None` | `None` | `run_patching` only: where the run's experiment and masks folder are now, if moved since the run; refused by folder and tree runs (since v0.2.0) |
 | `method` | `str` | `"percentile"` | §6 |
 | `percentile` | `tuple[float, float]` | `(1.0, 99.8)` | Low and high percentiles, `0 ≤ low < high ≤ 100` |
 | `clip` | `tuple[float, float] \| None` | `None` | Limits applied right after normalizing (by the brick's `NormalizationParameters.apply`), before masking and resizing; the same in eager, lazy, exported and raw-on-load delivery |
@@ -323,8 +329,8 @@ In memory, `PatchRegion.normalization_parameters` holds the brick's `Parameters`
 | `pooling` | `str` | `"pixels"` | §7: `"pixels"` or `"conditions"` |
 | `image_type` | `str` | `"fluorescence"` | §6: `"fluorescence"` (each channel separately) or `"rgb"` (R, G and B together, `"percentile"` only, `extraction.split_channels=False`); must equal the manifest's image type when it records one (§5) |
 
-`config.common` gains `mask_source` (`"tiff_tree"` or `"ngff_labels"`, default `"tiff_tree"`)
-and `mask_label_name` (`str | None`, default `None`) (§4), and `z_policy`/`t_policy`
+`config.common` gained `mask_source` and `mask_label_name` (§4; removed in v0.2.0, CP-2b), and
+`z_policy`/`t_policy`
 (`"keep"` by default, or `"all"`, `"first"`, `"select"`; Z also `"max"`, `"mean"`, `"sum"`)
 with `z_index`/`t_index` (`int | None`), which split Z and T in folder, tree and
 `run_patching` runs (§3; Milestone 2, decided October 2026).
diff --git a/notebooks/CellPatcher/CHANGELOG.md b/notebooks/CellPatcher/CHANGELOG.md
index f8dd0ac..a63debb 100644
--- a/notebooks/CellPatcher/CHANGELOG.md
+++ b/notebooks/CellPatcher/CHANGELOG.md
@@ -4,6 +4,52 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [Unreleased] - File-run removals and run_config.json version 2 (CP-2b)
+
+### Changed
+- `run_config.json` is version 2 (`run_config_version`). When a preprocessing run was read
+  it has a `preprocessing` section: the run's folder (`run`), the SHA-256 of its
+  `run_manifest.json` taken when the call opened it (`manifest_sha256`), and for a folder or
+  tree run the array `layout` (`image`, `mask`) built from the run's recorded roles. A folder
+  or tree run no longer records `common.image_axes`, `mask_axes` or its labels there (they are
+  the run's, not settings), so its `run_config.json` loads back as a config a file run accepts.
+  `load_config` and the exported-patch readers refuse any version but 1 (no version: written
+  before v0.2.0, or a plain config file) and 2.
+- `validate_image_and_mask_folders(image_folder, mask_folder, *, preprocessing_run=, mask_type=)`
+  returns the pairing the preprocessing run recorded (opened where the folders are now); it
+  pairs nothing itself, and refuses without a run (`no_preprocessing_run`). It moved to
+  `cellpatcher.file_runs` (still `cellpatcher.validate_image_and_mask_folders`).
+- New `iter_run_patch_arrays(patches, config, *, experiment_root=, masks_root=)`: lazy
+  delivery of a folder or tree run's patches, each plane read with `RunInputs.read_plane`
+  (masks with `read_mask`) from the image the run recorded at the patch's
+  `source_relative_path`, refusing another image or FOV key.
+- `run_patching_pipeline` (and `run_patching_from_folders`) accept `mask_folder_path` in `grid`
+  and `whole_fov` mode (owner decision of 2026-11-02): it says where the run's masks folder is
+  now; those masks are checked there, never read. Before, it was refused.
+- `normalization.experiment_root`/`masks_root` (owner decision of 2026-11-02): where the
+  experiment and masks folder of a moved experiment are now, for `run_patching` at the `image`
+  or `biological_repeat` scope. Folder and tree runs refuse them (their arguments say it).
+
+### Removed (breaking)
+- `patch_array`, `iter_patch_arrays` and `PatchTorchDataset` take arrays only: a file path is a
+  `TypeError` naming `iter_run_patch_arrays` (before, CellPatcher read it with
+  `common.image_axes` and its own header check).
+- `images.csv` loses its last column `image_read_transposed` (always `false` or empty since
+  preprocessing v0.4), and `ImageRecord` its field.
+- `common.mask_source` and `common.mask_label_name`: `CommonConfig(mask_source=...)` is a
+  `TypeError`; a config or `run_config.json` with their defaults still loads, one with another
+  value is refused naming `matching.mask_type`.
+- `cellpatcher.io`: `pair_masks`, `MaskPairing`, `read_image`, `conform_axes`,
+  `read_ngff_mask`, `refuse_image_header_axes`, `refuse_mask_header_axes`,
+  `refuse_header_axes`, `header_axes_disagreement`, `refuse_mask_channel_axis`,
+  `source_relative_path`, `discover_folder_images` and `validate_image_and_mask_folders` (moved,
+  above); `cellpatcher.planes`: `iter_file_planes`, `read_file_plane`; `cellpatcher.ids`:
+  `object_set_from_label_path`; `cellpatcher.pipeline`: `check_source_identities`,
+  `run_config_data` (now `cellpatcher.run_config_file`). `cached_statistics` moved from
+  `cellpatcher.normalization` to `cellpatcher.run_open`.
+- The notebook still imports `pair_masks` and `read_ngff_mask` and offers the removed
+  settings; it is updated in CP-3.
+
 ## [Unreleased] - File runs read through the preprocessing run (CP-2a)
 
 ### Changed
@@ -13,7 +59,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
   off (`no_preprocessing_run`, with the preprocessing command). The images patched are the
   run's, with their labels and `position_id` as it recorded them; images and masks are read
   with `RunInputs.read_plane`/`read_mask` in the roles it recorded, in one canonical layout per
-  run (T, Z, C, then Y, X), recorded in `run_config.json` as `common.image_axes`/`mask_axes`.
+  run (T, Z, C, then Y, X), recorded in `run_config.json` as `common.image_axes`/`mask_axes`
+  (in its `preprocessing.layout` since CP-2b).
   An image added to the experiment after the run is not patched, and nothing says so yet (known
   limitation, closed when CellPatcher calls the preprocessing check for added images, which is
   not in v0.4.0rc1).
diff --git a/src/cellpatcher/io.py b/src/cellpatcher/io.py
index fd52bb4..55d453d 100644
--- a/src/cellpatcher/io.py
+++ b/src/cellpatcher/io.py
@@ -525,10 +525,9 @@ def refuse_removed_matching(where: str, options) -> None:
 
 
 MASK_TRANSPOSE_HELP = (
-    "To fix the masks, save each one with Y before X, as its image is read: transpose its last "
-    "two axes, for example tifffile.imwrite(path, numpy.swapaxes(mask, -1, -2), "
-    "metadata={'axes': 'YX'}) ('ZYX' or 'TYX' for a stack), then set common.mask_axes to those "
-    "axes. Nothing is ever read transposed."
+    "To fix the masks, give each one with Y before X, as its image: transpose its last two axes, "
+    "for example numpy.swapaxes(mask, -1, -2), then set common.mask_axes to those axes ('YX', "
+    "or 'ZYX'/'TYX' for a stack). Nothing is ever read transposed."
 )
 
 
@@ -539,9 +538,10 @@ def refuse_transposed_mask_axes(mask_axes) -> None:
     and X in their stored order, so a mask declared with X first (``'XY'``,
     ``'ZXY'``) would be taken as if Y came first: the patches would not
     match their objects (on a square image without any error).
-    Refused, never ignored (owner decision of 31 October 2026), for in-memory
-    masks as for mask files; :data:`MASK_TRANSPOSE_HELP` says how to fix the
-    masks.
+    Refused, never ignored (owner decision of 31 October 2026). Only
+    in-memory masks are declared: a folder or tree run reads each mask in the
+    roles its preprocessing run recorded. :data:`MASK_TRANSPOSE_HELP` says how
+    to fix the masks.
     """
     if mask_axes is None:
         return
diff --git a/src/cellpatcher/orchestration.py b/src/cellpatcher/orchestration.py
index d888b38..4596b61 100644
--- a/src/cellpatcher/orchestration.py
+++ b/src/cellpatcher/orchestration.py
@@ -361,9 +361,9 @@ def run_patching_pipeline(
         Without ``common.preprocessing_run``, or when ``RunInputs`` refuses
         the run (an image or mask changed or missing, a run before v0.4).
     ValueError
-        For ``common.image_axes``/``mask_axes`` other than ``"YX"``,
-        ``mask_source``/``mask_label_name``, or labels other than
-        ``"single"``: file runs read these from the run (the message says so).
+        For ``common.image_axes``/``mask_axes`` other than ``"YX"``, labels
+        other than ``"single"``, or ``normalization.experiment_root``/``masks_root``:
+        file runs read these from the run and its arguments (the message says so).
     """
     config = _checked_config(config, overrides)
     refuse_removed_matching("run_patching_pipeline", removed_options)
diff --git a/src/cellpatcher/statistics.py b/src/cellpatcher/statistics.py
index 4a7894d..0c53146 100644
--- a/src/cellpatcher/statistics.py
+++ b/src/cellpatcher/statistics.py
@@ -330,8 +330,7 @@ def check_images(
     size and newest time), its recorded ``position_id`` is the one its name
     gives, and CellPatcher's axes give every axis the role the run recorded
     for the file. A TIFF image's axes are ``image_axes``; an OME-Zarr image's
-    are its own OME-NGFF axes, which CellPatcher puts into
-    ``common.image_axes`` by role (``io.read_image``), so both are checked.
+    are its own OME-NGFF axes (matched by role), so both are checked.
 
     Parameters
     ----------
@@ -383,9 +382,9 @@ def _checked_axes(mbp: ModuleType, root: Path, path: str, axes: str) -> str:
     """The axes CellPatcher reads *path* with, one letter per stored dimension.
 
     A TIFF image is read in ``common.image_axes``. An OME-Zarr image is read
-    in its own OME-NGFF axes, put into ``common.image_axes`` by role
-    (``io.read_image``), so those are the axes to compare with the run's
-    roles (an unreadable store gives no axes and fails the comparison).
+    in its own OME-NGFF axes, matched by role, so those are the axes to
+    compare with the run's roles (an unreadable store gives no axes and fails
+    the comparison).
     """
     if not path.lower().endswith(".zarr"):
         return normalize_axes(axes)

From 98ef356b8c4e7a25029c58ae841702bf546ea528 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 2 Nov 2026 08:24:19 +0000
Subject: [PATCH 14/23] =?UTF-8?q?CP-2b:=20annotate=20the=20rewritten=20in-?=
 =?UTF-8?q?memory=20delivery=20helpers=20(=C2=A79=20ANN)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G3qp9AxjpGPw9xfWAUJNqc
---
 src/cellpatcher/delivery.py | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

diff --git a/src/cellpatcher/delivery.py b/src/cellpatcher/delivery.py
index f5dfff9..ef20566 100644
--- a/src/cellpatcher/delivery.py
+++ b/src/cellpatcher/delivery.py
@@ -29,6 +29,7 @@
 from collections.abc import Iterator, Mapping, Sequence
 from pathlib import Path
 from types import SimpleNamespace
+from typing import TYPE_CHECKING
 
 import numpy as np
 
@@ -41,6 +42,10 @@
 from cellpatcher.resize import resize_patch
 from cellpatcher.run_config_file import delivery_config
 
+if TYPE_CHECKING:
+    from cellpatcher.config import CellPatcherConfig
+    from cellpatcher.planes import PlaneChoice
+
 
 def patch_axes(config, patch) -> str:
     """Axes of a patch's delivered array: the image's, without resolved Z/T planes or a split channel."""
@@ -200,12 +205,16 @@ def _splits_channel(config, patch, axes: str) -> bool:
     return bool(config.extraction.split_channels and patch.c is not None and "C" in axes)
 
 
-def _image_plane(image, choice, config):
+def _image_plane(image: np.ndarray, choice: PlaneChoice, config: CellPatcherConfig) -> tuple[np.ndarray, str]:
+    """Return the plane *choice* of an in-memory image, refusing a file path."""
     _refuse_file(image, "image")
     return apply_plane_choice(image, config.common.image_axes, choice)
 
 
-def _mask_plane(mask, choice, config):
+def _mask_plane(
+    mask: np.ndarray | None, choice: PlaneChoice, config: CellPatcherConfig
+) -> tuple[np.ndarray | None, str | None]:
+    """Return the mask plane for *choice* of an in-memory mask, refusing a file path or X before Y."""
     if mask is None:
         return None, None
     _refuse_file(mask, "mask")
@@ -214,7 +223,7 @@ def _mask_plane(mask, choice, config):
     return select_mask_plane(mask, normalize_axes(config.common.mask_axes, mask.ndim), choice)
 
 
-def _refuse_file(source, what: str) -> None:
+def _refuse_file(source: object, what: str) -> None:
     """Refuse a file path: since v0.2.0 files are read only through the preprocessing run (CP-2b)."""
     if isinstance(source, (str, os.PathLike)):
         raise TypeError(

From d0fad7c5e7c7d8f96530e795ae74764addfefe9c Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 2 Nov 2026 08:26:58 +0000
Subject: [PATCH 15/23] CP-2b: every run_config.json reader refuses an unknown
 version

read_patch_table (the reader MorphoRelate uses) reported any run_config.json
it could parse, and the exported-patch loaders checked the version only for
raw exports. Both now refuse a run_config_version other than 1 or 2 first.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G3qp9AxjpGPw9xfWAUJNqc
---
 src/cellpatcher/delivery.py | 4 +++-
 src/cellpatcher/export.py   | 7 +++++++
 tests/test_file_runs.py     | 8 ++++----
 3 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/src/cellpatcher/delivery.py b/src/cellpatcher/delivery.py
index ef20566..75f1734 100644
--- a/src/cellpatcher/delivery.py
+++ b/src/cellpatcher/delivery.py
@@ -40,7 +40,7 @@
 from cellpatcher.normalization import PatchNormalization, parameters_from_row
 from cellpatcher.planes import apply_plane_choice, patch_plane_choice, select_mask_plane
 from cellpatcher.resize import resize_patch
-from cellpatcher.run_config_file import delivery_config
+from cellpatcher.run_config_file import delivery_config, run_config_version
 
 if TYPE_CHECKING:
     from cellpatcher.config import CellPatcherConfig
@@ -166,6 +166,8 @@ def iter_exported_patches(metadata_file, *, root_dir=None) -> Iterator[tuple[dic
 
 def _normalize_on_load(row: Mapping, array, run_config: Mapping | None) -> np.ndarray:
     """Normalize a loaded patch file when its run exported raw values (else return it as stored)."""
+    if run_config is not None:
+        run_config_version(run_config, "run_config.json")
     settings = (run_config or {}).get("normalization") or {}
     if settings.get("export_values") != "raw":
         return array
diff --git a/src/cellpatcher/export.py b/src/cellpatcher/export.py
index c209ecd..529045f 100644
--- a/src/cellpatcher/export.py
+++ b/src/cellpatcher/export.py
@@ -279,6 +279,13 @@ def _read_run_config(csv_path: Path, names: set[str], problems: list[str]):
     if not isinstance(run_config, dict):
         problems.append(f"config file {path} holds a {type(run_config).__name__}, not the JSON object CellPatcher writes")
         return None
+    from cellpatcher.run_config_file import run_config_version
+
+    try:
+        run_config_version(run_config, f"config file {path}")
+    except ValueError as exc:
+        problems.append(str(exc))
+        return None
     return run_config
 
 
diff --git a/tests/test_file_runs.py b/tests/test_file_runs.py
index 5ae76fc..e4995fc 100644
--- a/tests/test_file_runs.py
+++ b/tests/test_file_runs.py
@@ -276,15 +276,13 @@ def test_the_run_config_records_the_run_and_its_manifest_and_loads_back_for_a_fi
 
 @pytest.mark.parametrize("version", [3, "2", None])
 def test_a_run_config_of_an_unknown_version_is_refused_by_every_reader(tmp_path, version):
-    from cellpatcher import iter_exported_patches
+    from cellpatcher import PatchTableError, iter_exported_patches, read_patch_table
     from cellpatcher.orchestration import load_config
 
     run = _clean_run(tmp_path, axes="YX", shape=(16, 20), mask_types=("Cells",))
     config = _cell_config(run)
     config.export.enabled, config.common.output_dir = True, str(tmp_path / "out")
-    config.normalization.enabled, config.normalization.scope = True, "image"
-    config.normalization.export_values = "raw"
-    run_patching_condition_repeat_tree(run.experiment, config=config, combine_metadata=True)
+    run_patching_condition_repeat_tree(run.experiment, config=config, combine_metadata=True)  # files as delivered
     path = tmp_path / "out" / "run_config.json"
     path.write_text(json.dumps({**json.loads(path.read_text(encoding="utf-8")), "run_config_version": version}))
     refusal = rf"run_config_version {version!r}; this CellPatcher reads versions 1, 2"
@@ -292,6 +290,8 @@ def test_a_run_config_of_an_unknown_version_is_refused_by_every_reader(tmp_path,
         load_config(path)
     with pytest.raises(ValueError, match=refusal):
         list(iter_exported_patches(tmp_path / "out" / "patches.csv"))
+    with pytest.raises(PatchTableError, match=refusal):
+        read_patch_table(tmp_path / "out" / "patches.csv")
 
 
 def test_another_table_than_the_run_s_is_refused(tmp_path):

From e61dd6e357d5210280485891ae7576cc2c1e63c9 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 2 Nov 2026 08:27:17 +0000
Subject: [PATCH 16/23] CP-2b docs: read_patch_table refuses an unknown
 run_config version too

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G3qp9AxjpGPw9xfWAUJNqc
---
 docs/configuration_reference.md    | 2 +-
 notebooks/CellPatcher/CHANGELOG.md | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/configuration_reference.md b/docs/configuration_reference.md
index 2d7b20c..0acd844 100644
--- a/docs/configuration_reference.md
+++ b/docs/configuration_reference.md
@@ -430,7 +430,7 @@ Each exported `patches.csv` row, together with the `run_config.json` file it ref
 
 - The row's own coordinates (`y0/y1/x0/x1`, `z0/z1`, `t`, `c`) and `output_height`/`output_width` fully describe the patch geometry and final exported array shape; `image_height`/`image_width`, the `pad_*` columns, `resized` and `output_axes` say, without the source image or the config, where the rectangle lies in its image, which pixels of the array are padding, whether the array was resampled and what its axes are.
 - `run_config.json` is the complete, serialized `CellPatcherConfig` for the run — strategy parameters (including `random.seed`), extraction/resize settings, the mask type, and the axes of in-memory arrays — everything needed to reproduce the same coordinates deterministically from the same inputs.
-- Since v0.2.0 (CP-2b) it is **version 2**: `run_config_version: 2`, and when a preprocessing run was read (a folder or tree run, or a CSV normalization scope) a `preprocessing` section with the run (`run`), the SHA-256 of its `run_manifest.json` when the call opened it (`manifest_sha256`), which names the run's images, masks, roles and table exactly, and for a folder or tree run the `layout` (`image`, `mask`) of the arrays it built from the run's recorded roles (T, Z, C, then Y, X). A folder or tree run does not record `common.image_axes`, `mask_axes` or the labels (each patch's labels are in `patches.csv`). `load_config` and the exported-patch readers (`iter_exported_patches`, `load_exported_patch`, `ExportedPatchTorchDataset`) read versions 1 (no version: written before v0.2.0, or a config file) and 2, and refuse any other naming the version.
+- Since v0.2.0 (CP-2b) it is **version 2**: `run_config_version: 2`, and when a preprocessing run was read (a folder or tree run, or a CSV normalization scope) a `preprocessing` section with the run (`run`), the SHA-256 of its `run_manifest.json` when the call opened it (`manifest_sha256`), which names the run's images, masks, roles and table exactly, and for a folder or tree run the `layout` (`image`, `mask`) of the arrays it built from the run's recorded roles (T, Z, C, then Y, X). A folder or tree run does not record `common.image_axes`, `mask_axes` or the labels (each patch's labels are in `patches.csv`). `load_config`, `read_patch_table` and the exported-patch readers (`iter_exported_patches`, `load_exported_patch`, `ExportedPatchTorchDataset`) read versions 1 (no version: written before v0.2.0, or a config file) and 2, and refuse any other naming the version.
 
 ## Typed refusals
 
diff --git a/notebooks/CellPatcher/CHANGELOG.md b/notebooks/CellPatcher/CHANGELOG.md
index a63debb..d51f03c 100644
--- a/notebooks/CellPatcher/CHANGELOG.md
+++ b/notebooks/CellPatcher/CHANGELOG.md
@@ -13,8 +13,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
   tree run the array `layout` (`image`, `mask`) built from the run's recorded roles. A folder
   or tree run no longer records `common.image_axes`, `mask_axes` or its labels there (they are
   the run's, not settings), so its `run_config.json` loads back as a config a file run accepts.
-  `load_config` and the exported-patch readers refuse any version but 1 (no version: written
-  before v0.2.0, or a plain config file) and 2.
+  `load_config`, `read_patch_table` and the exported-patch readers refuse any version but 1 (no
+  version: written before v0.2.0, or a plain config file) and 2.
 - `validate_image_and_mask_folders(image_folder, mask_folder, *, preprocessing_run=, mask_type=)`
   returns the pairing the preprocessing run recorded (opened where the folders are now); it
   pairs nothing itself, and refuses without a run (`no_preprocessing_run`). It moved to

From 001f059ea78ae89a2a08b0615d3a1d39c3a440a0 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 2 Nov 2026 09:13:11 +0000
Subject: [PATCH 17/23] CP-2b review: refuse a run_manifest.json that changes
 during the run

run_config.json records the manifest's SHA-256 taken when the call opened the
run. A manifest rewritten after that (preprocessing run again on the same
output folder) was recorded as if unchanged. Now the SHA-256 is checked again
when run_config.json is written (before the file is created, so a refusal
leaves no file and no export), and a second open in the same call refuses a
manifest changed since the first. Regression tests for these two and for the
existing "changed while it was opened" branch, which had none.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G3qp9AxjpGPw9xfWAUJNqc
---
 src/cellpatcher/orchestration.py   |  3 +-
 src/cellpatcher/pipeline.py        |  3 +-
 src/cellpatcher/run_config_file.py |  7 +++-
 src/cellpatcher/run_open.py        | 33 +++++++++++++++++-
 tests/test_file_runs.py            | 56 ++++++++++++++++++++++++++++++
 5 files changed, 98 insertions(+), 4 deletions(-)

diff --git a/src/cellpatcher/orchestration.py b/src/cellpatcher/orchestration.py
index 4596b61..7cb7f94 100644
--- a/src/cellpatcher/orchestration.py
+++ b/src/cellpatcher/orchestration.py
@@ -563,9 +563,10 @@ def _patch_leaves(
 
 def _write_combined_metadata(config: CellPatcherConfig, output_dir: Path, results: list[ConditionRepeatResult]) -> None:
     """Write one run_config.json, one patches.csv and one images.csv covering every leaf of a tree run."""
+    data = run_config_data(config)  # before the file is created: a refusal leaves none
     output_dir.mkdir(parents=True, exist_ok=True)
     with (output_dir / RUN_CONFIG_FILENAME).open("w", encoding="utf-8") as f:
-        json.dump(run_config_data(config), f, indent=2, default=str)
+        json.dump(data, f, indent=2, default=str)
 
     all_patches = []
     for leaf_result in results:
diff --git a/src/cellpatcher/pipeline.py b/src/cellpatcher/pipeline.py
index 41855f7..bbb88d4 100644
--- a/src/cellpatcher/pipeline.py
+++ b/src/cellpatcher/pipeline.py
@@ -631,8 +631,9 @@ def _finish_result(
         out_dir.mkdir(parents=True, exist_ok=True)
         if config.export.save_run_config:
             config_path = out_dir / RUN_CONFIG_FILENAME
+            data = run_config_data(config)  # before the file is created: a refusal leaves none
             with config_path.open("w", encoding="utf-8") as f:
-                json.dump(run_config_data(config), f, indent=2, default=str)
+                json.dump(data, f, indent=2, default=str)
             for patch in patches:
                 patch.config_file = RUN_CONFIG_FILENAME
 
diff --git a/src/cellpatcher/run_config_file.py b/src/cellpatcher/run_config_file.py
index fbf8a88..fed2bb1 100644
--- a/src/cellpatcher/run_config_file.py
+++ b/src/cellpatcher/run_config_file.py
@@ -6,7 +6,8 @@
 - ``run``: the run's output folder, as given (``common.preprocessing_run``, or the folder of
   ``normalization.plane_histograms`` for a CSV scope of ``run_patching``);
 - ``manifest_sha256``: the SHA-256 of its ``run_manifest.json`` when this call opened it, which
-  names the run's images, masks, roles and table exactly;
+  names the run's images, masks, roles and table exactly (a manifest changed since is refused
+  when the file is written: :func:`cellpatcher.run_open.refuse_changed_manifest`);
 - for a folder or tree run, ``layout``: the order of the arrays CellPatcher built from the roles
   the run recorded (T, Z, C, then Y, X; ``image`` and ``mask``), which delivers exported patches.
 
@@ -39,6 +40,7 @@
     WholeFOVConfig,
 )
 from cellpatcher.normalization import CSV_SCOPES, normalization_inputs, run_settings
+from cellpatcher.run_open import refuse_changed_manifest
 from cellpatcher.run_session import recalled
 
 RUN_CONFIG_VERSION = 2
@@ -63,6 +65,8 @@ def run_config_data(config: CellPatcherConfig) -> dict:
     RuntimeError
         If the preprocessing run read was not opened in this call (an internal error: its
         manifest's SHA-256 is recorded when it is opened).
+    PreprocessingCheckError
+        If the run's ``run_manifest.json`` changed since this call opened it.
     """
     data: dict[str, Any] = {"run_config_version": RUN_CONFIG_VERSION, **asdict(config)}
     preprocessing = _preprocessing_section(config)
@@ -93,6 +97,7 @@ def _preprocessing_section(config: CellPatcherConfig) -> dict | None:
     sha256 = recalled("manifest_sha256", run)
     if sha256 is None:
         raise RuntimeError(f"The preprocessing run {run} was not opened in this call, so it cannot be recorded.")
+    refuse_changed_manifest(run, sha256)
     section: dict[str, Any] = {"run": str(run), "manifest_sha256": sha256}
     if file_run:
         section["layout"] = {"image": common.image_axes, "mask": common.mask_axes}
diff --git a/src/cellpatcher/run_open.py b/src/cellpatcher/run_open.py
index 9ef2f08..a01b49d 100644
--- a/src/cellpatcher/run_open.py
+++ b/src/cellpatcher/run_open.py
@@ -15,7 +15,7 @@
 from pathlib import Path
 from typing import TYPE_CHECKING
 
-from cellpatcher.run_session import remember, session_statistics
+from cellpatcher.run_session import recalled, remember, session_statistics
 
 if TYPE_CHECKING:
     from morphobricks_normalization import PlaneRecord
@@ -177,6 +177,8 @@ def open_run(
     roots = [Path(root).expanduser() if root is not None else None for root in (experiment_root, masks_root)]
     try:
         before = _manifest_sha256(folder)
+        if recalled("manifest_sha256", folder) not in {None, before}:
+            raise RunInputsError("its run_manifest.json changed since this call first opened it.")
         inputs = RunInputs.open(folder, *roots)
         if _manifest_sha256(folder) != before:
             raise RunInputsError("its run_manifest.json changed while it was opened.")
@@ -204,6 +206,35 @@ def open_run(
     return inputs
 
 
+def refuse_changed_manifest(output_folder: str | os.PathLike, opened_sha256: str) -> None:
+    """Refuse a run whose ``run_manifest.json`` changed since this call opened it.
+
+    ``run_config.json`` records the manifest's SHA-256 taken at the open; a manifest rewritten
+    during the run (preprocessing run again on the same output folder) no longer names what was
+    read, so nothing is recorded.
+
+    Raises
+    ------
+    PreprocessingCheckError
+        ``preprocessing_run_refused`` when the manifest's SHA-256 is not *opened_sha256*.
+    """
+    from morphobricks_preprocessing.validation import error
+
+    from cellpatcher.statistics import PreprocessingCheckError
+
+    folder = Path(output_folder).expanduser()
+    if _manifest_sha256(folder) != opened_sha256:
+        raise PreprocessingCheckError([
+            error(
+                "preprocessing_run_refused",
+                f"The preprocessing run in {folder} cannot be used: its run_manifest.json changed during this "
+                "CellPatcher run, so the run read is no longer the one in that folder.",
+                [str(folder)],
+                "Wait until preprocessing has finished writing its run, then run CellPatcher again.",
+            )
+        ])
+
+
 def _manifest_sha256(folder: Path) -> str | None:
     """Return the SHA-256 of the run's ``run_manifest.json`` (recorded in ``run_config.json``), None if absent."""
     from morphobricks_preprocessing import MANIFEST_FILENAME, file_sha256
diff --git a/tests/test_file_runs.py b/tests/test_file_runs.py
index e4995fc..a9239b6 100644
--- a/tests/test_file_runs.py
+++ b/tests/test_file_runs.py
@@ -274,6 +274,62 @@ def test_the_run_config_records_the_run_and_its_manifest_and_loads_back_for_a_fi
     ]
 
 
+def _touch_manifest(run):
+    """Rewrite the run's run_manifest.json with one more trailing newline: same content, another SHA-256."""
+    path = run.output / "run_manifest.json"
+    path.write_bytes(path.read_bytes() + b"\n")
+
+
+def test_a_manifest_changed_while_the_run_is_opened_is_refused(tmp_path, monkeypatch):
+    from morphobricks_preprocessing.run_inputs import RunInputs
+
+    run = _clean_run(tmp_path, axes="YX", shape=(16, 20), mask_types=("Cells",))
+    original = RunInputs.open.__func__
+
+    def open_and_touch(cls, *args, **kwargs):
+        inputs = original(cls, *args, **kwargs)
+        _touch_manifest(run)
+        return inputs
+
+    monkeypatch.setattr(RunInputs, "open", classmethod(open_and_touch))
+    with pytest.raises(PreprocessingCheckError, match="run_manifest.json changed while it was opened"):
+        run_patching_condition_repeat_tree(run.experiment, config=_cell_config(run))
+
+
+def test_a_manifest_changed_during_the_run_is_refused_before_run_config_is_written(tmp_path, monkeypatch):
+    # run_config.json records the manifest's SHA-256 taken at the open; a manifest rewritten
+    # after it (preprocessing run again on the same folder) would make it name another run.
+    import cellpatcher.file_runs as file_runs
+
+    run = _clean_run(tmp_path, axes="YX", shape=(16, 20), mask_types=("Cells",))
+    original = file_runs.run_layout
+
+    def layout_and_touch(fovs):
+        _touch_manifest(run)
+        return original(fovs)
+
+    monkeypatch.setattr(file_runs, "run_layout", layout_and_touch)
+    config = _cell_config(run)
+    config.export.enabled, config.common.output_dir = True, str(tmp_path / "out")
+    with pytest.raises(PreprocessingCheckError, match="run_manifest.json changed during this CellPatcher run"):
+        run_patching_condition_repeat_tree(run.experiment, config=config)
+    assert not list((tmp_path / "out").rglob("run_config.json"))
+    assert not list((tmp_path / "out").rglob("patches.csv"))
+
+
+def test_a_second_open_in_one_call_refuses_a_manifest_changed_since_the_first(tmp_path):
+    from cellpatcher.run_open import open_run
+    from cellpatcher.run_session import statistics_session
+
+    run = _clean_run(tmp_path, axes="YX", shape=(16, 20), mask_types=("Cells",))
+    with statistics_session():
+        open_run(run.output)
+        open_run(run.output)  # the same manifest: opened again
+        _touch_manifest(run)
+        with pytest.raises(PreprocessingCheckError, match="changed since this call first opened it"):
+            open_run(run.output)
+
+
 @pytest.mark.parametrize("version", [3, "2", None])
 def test_a_run_config_of_an_unknown_version_is_refused_by_every_reader(tmp_path, version):
     from cellpatcher import PatchTableError, iter_exported_patches, read_patch_table

From ca77cff157fe872c33379a87bc4f789fe98ca7bd Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 2 Nov 2026 09:13:29 +0000
Subject: [PATCH 18/23] CP-2b review: import file_runs from cellpatcher in the
 manifest test (ruff PLR0402)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G3qp9AxjpGPw9xfWAUJNqc
---
 tests/test_file_runs.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/test_file_runs.py b/tests/test_file_runs.py
index a9239b6..38ed3d5 100644
--- a/tests/test_file_runs.py
+++ b/tests/test_file_runs.py
@@ -299,7 +299,7 @@ def open_and_touch(cls, *args, **kwargs):
 def test_a_manifest_changed_during_the_run_is_refused_before_run_config_is_written(tmp_path, monkeypatch):
     # run_config.json records the manifest's SHA-256 taken at the open; a manifest rewritten
     # after it (preprocessing run again on the same folder) would make it name another run.
-    import cellpatcher.file_runs as file_runs
+    from cellpatcher import file_runs
 
     run = _clean_run(tmp_path, axes="YX", shape=(16, 20), mask_types=("Cells",))
     original = file_runs.run_layout

From 00d5c4b339d1ae9ff5ed3eddaf63247d38356c6f Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 2 Nov 2026 09:13:53 +0000
Subject: [PATCH 19/23] CP-2b review: PatchTorchDataset refuses a file path
 when it is built

The path refusal of patch_array reached PatchTorchDataset only when an item
was loaded, inside a DataLoader worker, although its constructor checks its
inputs up front. Images and masks are now checked in the constructor, with
the same TypeError naming iter_run_patch_arrays. Regression test (needs torch).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G3qp9AxjpGPw9xfWAUJNqc
---
 src/cellpatcher/torch_dataset.py | 10 +++++++++-
 tests/test_torch_dataset.py      | 10 ++++++++++
 2 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/src/cellpatcher/torch_dataset.py b/src/cellpatcher/torch_dataset.py
index d8a0c72..33564cc 100644
--- a/src/cellpatcher/torch_dataset.py
+++ b/src/cellpatcher/torch_dataset.py
@@ -9,7 +9,7 @@
 from cellpatcher._deprecation import upgrade_legacy_repeat_column
 from cellpatcher.axes import axis_index, normalize_axes, require_spatial_axes
 from cellpatcher.config import CellPatcherConfig, CommonConfig, ExtractionConfig
-from cellpatcher.delivery import _normalize_on_load, patch_array, patch_axes
+from cellpatcher.delivery import _normalize_on_load, _refuse_file, patch_array, patch_axes
 from cellpatcher.io import read_array
 from cellpatcher.export import sanitize_filename
 
@@ -142,6 +142,10 @@ def __init__(
     ):
         """Patches cut lazily from in-memory images, one per item.
 
+        *images* (and *masks*) are arrays: a file path is a ``TypeError`` here, since a folder or
+        tree run's files are read only through its preprocessing run
+        (:func:`cellpatcher.iter_run_patch_arrays`).
+
         Each item is built with :func:`cellpatcher.delivery.patch_array`, so it
         equals the patch eager delivery gives: normalized with the patch's
         recorded parameters when it has them (``config.normalization``). Pass
@@ -155,6 +159,8 @@ def __init__(
             self._images = [images]
         if len(self._images) == 0:
             raise ValueError("images must contain at least one image.")
+        for image in self._images:  # at construction, not in a DataLoader worker
+            _refuse_file(image, "image")
 
         self._patches = list(patches)
         if config is None:
@@ -179,6 +185,8 @@ def __init__(
                 self._masks = list(masks)
             else:
                 self._masks = [masks]
+            for mask in self._masks:
+                _refuse_file(mask, "mask")
             if len(self._masks) != len(self._images):
                 raise ValueError("When masks are provided, number of masks must match number of images.")
             self._mask_lookup = {f"image_{idx:04d}": mask for idx, mask in enumerate(self._masks)}
diff --git a/tests/test_torch_dataset.py b/tests/test_torch_dataset.py
index 28bfa1f..3067f67 100644
--- a/tests/test_torch_dataset.py
+++ b/tests/test_torch_dataset.py
@@ -555,3 +555,13 @@ def test_real_tiff_fixture_cell_apply_mask_torch_dataset():
     sample = ds[0]
     assert tuple(sample["image"].shape) == (3, 32, 32)
     assert "label_id" in sample
+
+
+def test_a_file_path_is_refused_when_the_dataset_is_built(tmp_path):
+    # CP-2b: PatchTorchDataset takes arrays only. Old main read a path itself (common.image_axes
+    # and its own header check) when an item was loaded, inside a DataLoader worker.
+    patch = PatchRegion(patch_id="p", image_id="image_0000", mode="whole_fov", y0=0, y1=4, x0=0, x1=4)
+    with pytest.raises(TypeError, match=r"got the path .*img.tif.*iter_run_patch_arrays"):
+        PatchTorchDataset([tmp_path / "img.tif"], [patch])
+    with pytest.raises(TypeError, match=r"masks of run_patching as arrays; got the path .*m.tif"):
+        PatchTorchDataset([np.zeros((4, 4))], [patch], masks=[str(tmp_path / "m.tif")])

From 35874de093b354c90bc01adb35d2e8b11cd2216c Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 2 Nov 2026 09:14:42 +0000
Subject: [PATCH 20/23] CP-2b review: keep the in-memory half of the removed
 swapped-mask delivery test

test_lazy_delivery_refuses_a_mask_declared_swapped covered a mask file with a
swapped header; its file half is now test_lazy_delivery_refuses_a_mask_file,
but nothing covered lazy delivery refusing an array mask declared 'XY' any
more. Test only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G3qp9AxjpGPw9xfWAUJNqc
---
 tests/test_declared_axes.py | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/tests/test_declared_axes.py b/tests/test_declared_axes.py
index 9a1b845..b8d59e0 100644
--- a/tests/test_declared_axes.py
+++ b/tests/test_declared_axes.py
@@ -127,6 +127,20 @@ def test_lazy_delivery_refuses_a_mask_file(tmp_path):
         patch_array(patch, image, config, mask=tmp_path / "m.tif")
 
 
+def test_lazy_delivery_refuses_an_in_memory_mask_declared_swapped():
+    # The in-memory half of the removed test_lazy_delivery_refuses_a_mask_declared_swapped (its
+    # file half is test_lazy_delivery_refuses_a_mask_file): an array mask with X before Y.
+    from cellpatcher.delivery import patch_array
+
+    image, labels, _ = make_synthetic_cell_image_and_labels(shape=(32, 32))
+    config = _cell_config("YX", "YX")
+    patch = run_patching(images=[image], masks=[labels], config=config, image_metadata=named([image])).patches[0]
+    config.common.mask_axes = "XY"
+    config.extraction.apply_mask = True
+    with pytest.raises(ValueError, match=r"common.mask_axes='XY' puts X before Y"):
+        patch_array(patch, image, config, mask=labels)
+
+
 def _cell_config(image_axes, mask_axes, output_dir=None):
     config = CellPatcherConfig(mode="cell")
     config.cell.patch_size = 6

From 44e6c74f85c9bc8cd36b098dec0a81c04c2577c4 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 2 Nov 2026 09:16:16 +0000
Subject: [PATCH 21/23] CP-2b review docs: the notebook breakage, the
 downstream items and the manifest refusal

The CHANGELOG now says plainly that CellPatcher's own notebook does not work
until CP-3 (no shim, owner decision of 2026-11-02), that the check for images
added after the run is wired once preprocessing v0.4.0rc2 provides it, and
names the downstream items for the brick migrations (MorphoRelate's axes
check, MorphoEmbed's PatchTorchDataset, fiberfeatures' reference
patch_config.json). It also records this review's two fixes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G3qp9AxjpGPw9xfWAUJNqc
---
 docs/configuration_reference.md    |  2 +-
 notebooks/CellPatcher/CHANGELOG.md | 30 +++++++++++++++++++++++++-----
 2 files changed, 26 insertions(+), 6 deletions(-)

diff --git a/docs/configuration_reference.md b/docs/configuration_reference.md
index 0acd844..9c3e6b7 100644
--- a/docs/configuration_reference.md
+++ b/docs/configuration_reference.md
@@ -430,7 +430,7 @@ Each exported `patches.csv` row, together with the `run_config.json` file it ref
 
 - The row's own coordinates (`y0/y1/x0/x1`, `z0/z1`, `t`, `c`) and `output_height`/`output_width` fully describe the patch geometry and final exported array shape; `image_height`/`image_width`, the `pad_*` columns, `resized` and `output_axes` say, without the source image or the config, where the rectangle lies in its image, which pixels of the array are padding, whether the array was resampled and what its axes are.
 - `run_config.json` is the complete, serialized `CellPatcherConfig` for the run — strategy parameters (including `random.seed`), extraction/resize settings, the mask type, and the axes of in-memory arrays — everything needed to reproduce the same coordinates deterministically from the same inputs.
-- Since v0.2.0 (CP-2b) it is **version 2**: `run_config_version: 2`, and when a preprocessing run was read (a folder or tree run, or a CSV normalization scope) a `preprocessing` section with the run (`run`), the SHA-256 of its `run_manifest.json` when the call opened it (`manifest_sha256`), which names the run's images, masks, roles and table exactly, and for a folder or tree run the `layout` (`image`, `mask`) of the arrays it built from the run's recorded roles (T, Z, C, then Y, X). A folder or tree run does not record `common.image_axes`, `mask_axes` or the labels (each patch's labels are in `patches.csv`). `load_config`, `read_patch_table` and the exported-patch readers (`iter_exported_patches`, `load_exported_patch`, `ExportedPatchTorchDataset`) read versions 1 (no version: written before v0.2.0, or a config file) and 2, and refuse any other naming the version.
+- Since v0.2.0 (CP-2b) it is **version 2**: `run_config_version: 2`, and when a preprocessing run was read (a folder or tree run, or a CSV normalization scope) a `preprocessing` section with the run (`run`), the SHA-256 of its `run_manifest.json` when the call opened it (`manifest_sha256`), which names the run's images, masks, roles and table exactly (a manifest that changes during the call is refused, and no `run_config.json` is written), and for a folder or tree run the `layout` (`image`, `mask`) of the arrays it built from the run's recorded roles (T, Z, C, then Y, X). A folder or tree run does not record `common.image_axes`, `mask_axes` or the labels (each patch's labels are in `patches.csv`). `load_config`, `read_patch_table` and the exported-patch readers (`iter_exported_patches`, `load_exported_patch`, `ExportedPatchTorchDataset`) read versions 1 (no version: written before v0.2.0, or a config file) and 2, and refuse any other naming the version.
 
 ## Typed refusals
 
diff --git a/notebooks/CellPatcher/CHANGELOG.md b/notebooks/CellPatcher/CHANGELOG.md
index d51f03c..1bce3cd 100644
--- a/notebooks/CellPatcher/CHANGELOG.md
+++ b/notebooks/CellPatcher/CHANGELOG.md
@@ -10,7 +10,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - `run_config.json` is version 2 (`run_config_version`). When a preprocessing run was read
   it has a `preprocessing` section: the run's folder (`run`), the SHA-256 of its
   `run_manifest.json` taken when the call opened it (`manifest_sha256`), and for a folder or
-  tree run the array `layout` (`image`, `mask`) built from the run's recorded roles. A folder
+  tree run the array `layout` (`image`, `mask`) built from the run's recorded roles. A manifest
+  that changes during the call (while it is opened, between two opens, or before
+  `run_config.json` is written) is refused, and no `run_config.json` is left. A folder
   or tree run no longer records `common.image_axes`, `mask_axes` or its labels there (they are
   the run's, not settings), so its `run_config.json` loads back as a config a file run accepts.
   `load_config`, `read_patch_table` and the exported-patch readers refuse any version but 1 (no
@@ -32,8 +34,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ### Removed (breaking)
 - `patch_array`, `iter_patch_arrays` and `PatchTorchDataset` take arrays only: a file path is a
-  `TypeError` naming `iter_run_patch_arrays` (before, CellPatcher read it with
-  `common.image_axes` and its own header check).
+  `TypeError` naming `iter_run_patch_arrays` (`PatchTorchDataset` refuses it when it is built;
+  before, CellPatcher read it with `common.image_axes` and its own header check).
 - `images.csv` loses its last column `image_read_transposed` (always `false` or empty since
   preprocessing v0.4), and `ImageRecord` its field.
 - `common.mask_source` and `common.mask_label_name`: `CommonConfig(mask_source=...)` is a
@@ -47,8 +49,26 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
   `object_set_from_label_path`; `cellpatcher.pipeline`: `check_source_identities`,
   `run_config_data` (now `cellpatcher.run_config_file`). `cached_statistics` moved from
   `cellpatcher.normalization` to `cellpatcher.run_open`.
-- The notebook still imports `pair_masks` and `read_ngff_mask` and offers the removed
-  settings; it is updated in CP-3.
+
+### Known breakage until CP-3
+- **CellPatcher's own notebook (`notebooks/CellPatcher/CellPatcher.ipynb`) does not work after
+  this change.** Its import cell fails: it still imports `pair_masks`, `read_ngff_mask` and
+  `cellpatcher.normalization.cached_statistics`, and it offers the removed settings. It is
+  rewritten in CP-3, the next PR; no compatibility shim is added meanwhile (owner decision of
+  2026-11-02). Use the Python API until then.
+- Not in this change: CellPatcher does not yet call preprocessing's check for images added to
+  the experiment after its run. It is wired in once preprocessing v0.4.0rc2 provides it.
+
+### Downstream: for the brick migrations
+- **MorphoRelate** (`io/cellpatcher.py`): `check_image_axes` reads `common.image_axes` from
+  `run_config.json`; a folder or tree run's version 2 file has none, so it reports "not
+  checked" (no error). Its migration should take the axes from the preprocessing run (or
+  `preprocessing.layout`). `read_patch_table` now refuses an unknown `run_config_version`.
+- **MorphoEmbed** (`provider_crops.py`): `PatchTorchDataset([image], ...)` is fine with an
+  array; a path is now a `TypeError` when the dataset is built.
+- **fiberfeatures**: `data/experiment_001/reference/patch_config.json` still holds
+  `mask_source`/`mask_label_name` at their defaults. It loads with `load_config`, but
+  `CommonConfig(**common)` on it is a `TypeError`; a regenerated reference loses both keys.
 
 ## [Unreleased] - File runs read through the preprocessing run (CP-2a)
 

From 01390bbee13821a45beb18a1c5b3968447dbd59e Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 2 Nov 2026 09:17:33 +0000
Subject: [PATCH 22/23] =?UTF-8?q?CP-2b=20review:=20annotate=20the=20functi?=
 =?UTF-8?q?ons=20this=20PR=20changed=20(=C2=A79=20ANN)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

patch_array, iter_patch_arrays and _normalize_on_load (their contract or body
changed here), load_config, refuse_transposed_mask_axes, _read_run_config and
Normalizer.for_config. Annotations only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G3qp9AxjpGPw9xfWAUJNqc
---
 src/cellpatcher/delivery.py      | 17 +++++++++++++----
 src/cellpatcher/export.py        |  2 +-
 src/cellpatcher/io.py            |  2 +-
 src/cellpatcher/normalization.py |  2 +-
 src/cellpatcher/orchestration.py |  2 +-
 5 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/src/cellpatcher/delivery.py b/src/cellpatcher/delivery.py
index 75f1734..1fb73a1 100644
--- a/src/cellpatcher/delivery.py
+++ b/src/cellpatcher/delivery.py
@@ -26,7 +26,7 @@
 import csv
 import json
 import os
-from collections.abc import Iterator, Mapping, Sequence
+from collections.abc import Iterable, Iterator, Mapping, Sequence
 from pathlib import Path
 from types import SimpleNamespace
 from typing import TYPE_CHECKING
@@ -45,6 +45,7 @@
 if TYPE_CHECKING:
     from cellpatcher.config import CellPatcherConfig
     from cellpatcher.planes import PlaneChoice
+    from cellpatcher.types import PatchRegion
 
 
 def patch_axes(config, patch) -> str:
@@ -57,7 +58,9 @@ def patch_axes(config, patch) -> str:
     return axes
 
 
-def patch_array(patch, image, config, *, mask=None) -> np.ndarray:
+def patch_array(
+    patch: PatchRegion, image: np.ndarray, config: CellPatcherConfig, *, mask: np.ndarray | None = None
+) -> np.ndarray:
     """Rebuild one patch's array from its source image, as the pipeline delivers it.
 
     Parameters
@@ -87,7 +90,13 @@ def patch_array(patch, image, config, *, mask=None) -> np.ndarray:
     return _finish_patch(patch, plane, axes, mask_plane, mask_axes, config)
 
 
-def iter_patch_arrays(patches, images: Sequence, config, *, masks: Sequence | None = None) -> Iterator[tuple]:
+def iter_patch_arrays(
+    patches: Iterable[PatchRegion],
+    images: Sequence,
+    config: CellPatcherConfig,
+    *,
+    masks: Sequence | None = None,
+) -> Iterator[tuple]:
     """Yield ``(patch, array)`` for every patch, one at a time (lazy delivery).
 
     Parameters
@@ -164,7 +173,7 @@ def iter_exported_patches(metadata_file, *, root_dir=None) -> Iterator[tuple[dic
         yield row, load_exported_patch(row, root_dir=root, run_config=run_configs[name])
 
 
-def _normalize_on_load(row: Mapping, array, run_config: Mapping | None) -> np.ndarray:
+def _normalize_on_load(row: Mapping, array: np.ndarray, run_config: Mapping | None) -> np.ndarray:
     """Normalize a loaded patch file when its run exported raw values (else return it as stored)."""
     if run_config is not None:
         run_config_version(run_config, "run_config.json")
diff --git a/src/cellpatcher/export.py b/src/cellpatcher/export.py
index 529045f..1049837 100644
--- a/src/cellpatcher/export.py
+++ b/src/cellpatcher/export.py
@@ -254,7 +254,7 @@ def _typed(text: str, kind: type, optional: bool, column: str):
     raise TypeError(f"no reader for {column} ({kind})")
 
 
-def _read_run_config(csv_path: Path, names: set[str], problems: list[str]):
+def _read_run_config(csv_path: Path, names: set[str], problems: list[str]) -> dict | None:
     """The ``run_config.json`` the rows' ``config_file`` names (relative to the CSV's folder), or None."""
     import json
 
diff --git a/src/cellpatcher/io.py b/src/cellpatcher/io.py
index 55d453d..afe5676 100644
--- a/src/cellpatcher/io.py
+++ b/src/cellpatcher/io.py
@@ -531,7 +531,7 @@ def refuse_removed_matching(where: str, options) -> None:
 )
 
 
-def refuse_transposed_mask_axes(mask_axes) -> None:
+def refuse_transposed_mask_axes(mask_axes: str) -> None:
     """Refuse ``common.mask_axes`` that put X before Y: CellPatcher cannot read a mask transposed.
 
     The cell and random strategies take a label plane's two dimensions as Y
diff --git a/src/cellpatcher/normalization.py b/src/cellpatcher/normalization.py
index eee9b53..1ad0109 100644
--- a/src/cellpatcher/normalization.py
+++ b/src/cellpatcher/normalization.py
@@ -457,7 +457,7 @@ def __init__(self, config, statistics: PlaneStatistics | None, repeat_groups: di
         self._groups: dict[tuple, object] = {}
 
     @classmethod
-    def for_config(cls, config) -> Normalizer | None:
+    def for_config(cls, config: CellPatcherConfig) -> Normalizer | None:
         """The run's normalizer, or None when ``config.normalization.enabled`` is False.
 
         Validates the settings, loads the statistics for a CSV scope (and,
diff --git a/src/cellpatcher/orchestration.py b/src/cellpatcher/orchestration.py
index 7cb7f94..b32b87b 100644
--- a/src/cellpatcher/orchestration.py
+++ b/src/cellpatcher/orchestration.py
@@ -204,7 +204,7 @@ def save_config_for_mode(mode: str, path) -> Path:
     return out
 
 
-def load_config(path) -> CellPatcherConfig:
+def load_config(path: str | os.PathLike) -> CellPatcherConfig:
     """Load a :class:`~cellpatcher.CellPatcherConfig` from a JSON file.
 
     The file is typically created by :func:`save_default_config` or

From e0137b1edbf5f7a8b45595eb1d57f6955e7436ad Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 2 Nov 2026 09:18:07 +0000
Subject: [PATCH 23/23] CP-2b review: test the version 2 run_config.json of an
 in-memory run

Only a file run's preprocessing section was tested. An in-memory run at a CSV
scope records the run and its manifest's SHA-256 without a layout and keeps
common.image_axes and its labels; at the patch scope it has no section. Test
only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G3qp9AxjpGPw9xfWAUJNqc
---
 tests/test_file_runs.py | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/tests/test_file_runs.py b/tests/test_file_runs.py
index 38ed3d5..0686fa8 100644
--- a/tests/test_file_runs.py
+++ b/tests/test_file_runs.py
@@ -274,6 +274,36 @@ def test_the_run_config_records_the_run_and_its_manifest_and_loads_back_for_a_fi
     ]
 
 
+def test_an_in_memory_run_records_the_run_its_csv_scope_read_and_keeps_its_axes(tmp_path):
+    # run_config.json version 2 for run_patching: a CSV scope records the run its table came from
+    # and the manifest's SHA-256, without a layout (the arrays are the caller's, in common.image_axes).
+    from cellpatcher import run_patching
+    from cellpatcher.config import NormalizationConfig
+
+    run = _clean_run(tmp_path, axes="YX", shape=(16, 20), mask_types=("Cells",))
+    (path,) = sorted((run.experiment / "ctrl" / "rep1").glob("a.*"))
+    config = CellPatcherConfig(mode="grid")
+    config.grid.tile_size, config.common.extract_arrays = 8, True
+    config.common.condition, config.common.biological_repeat = "ctrl", "rep1"
+    config.export.enabled = True
+    meta = [{"image_file": path.name, "source_relative_path": path.relative_to(run.experiment).as_posix()}]
+    for scope, out in (("image", tmp_path / "csv"), ("patch", tmp_path / "patch")):
+        config.common.output_dir = str(out)
+        config.normalization = NormalizationConfig(
+            enabled=True, scope=scope, plane_histograms=str(run.output / "plane_histograms.csv") if scope == "image" else None
+        )
+        run_patching(images=[tifffile.imread(path)], config=config, image_metadata=meta)
+    csv_scope = json.loads((tmp_path / "csv" / "run_config.json").read_text(encoding="utf-8"))
+    assert csv_scope["run_config_version"] == 2
+    assert csv_scope["preprocessing"] == {
+        "run": str(run.output),
+        "manifest_sha256": hashlib.sha256((run.output / "run_manifest.json").read_bytes()).hexdigest(),
+    }
+    assert (csv_scope["common"]["image_axes"], csv_scope["common"]["condition"]) == ("YX", "ctrl")
+    patch_scope = json.loads((tmp_path / "patch" / "run_config.json").read_text(encoding="utf-8"))
+    assert patch_scope["run_config_version"] == 2 and "preprocessing" not in patch_scope
+
+
 def _touch_manifest(run):
     """Rewrite the run's run_manifest.json with one more trailing newline: same content, another SHA-256."""
     path = run.output / "run_manifest.json"