PP-4: manifest version 2, row keys, per-file plain-stack confirmation

AGENTS.md

@@ -86,8 +86,16 @@ src/morphobricks_preprocessing/
   validation.py     ValidationIssue (severity, code, message, paths, action), error()/warning() builders
   axes.py           AxisMapping (role per dimension), prefill, check_mapping, review_axes (one mapping
                     applied to every file, missing axes as singletons only when confirmed)
+  axis_review.py    review_axes and check_mapping (moved from axes.py in PP-4)
+  fingerprint.py    Fingerprint (size, mtime) and RowKey: when a file's rows are reused (D5);
+                    confirm_axes/unchanged_confirmation (a confirmation of the files as they are)
+  recorded_sizes.py RecordedSize: pixel sizes by role with unit and source (manifest v2)
+  narrow_ranges.py  NarrowRange (moved from manifest.py)
+  sources.py        check_sources (moved from manifest.py in PP-4)
+  mask_record.py    the manifest's masks entry with fingerprints and roles (manifest v2)
   axis_check.py     the axis check (contract §2): header_axis_issue, axis_disagreements,
-                    likely_axis_cause, check_header_axes; AXIS_ERROR_CODES, AXIS_CHECK_CODES
+                    likely_axis_cause, check_header_axes, ConfirmedAxes (a confirmation covers
+                    only its files as fingerprinted, plain_stack_not_confirmed); AXIS_ERROR_CODES, AXIS_CHECK_CODES
   planes.py         plane-by-plane reader (iter_planes, read_plane, read_sample_plane), table rows as
                     XYC planes whose channels are read one at a time (iter_xyc_planes, XycPlane),
                     memory estimate,
@@ -100,6 +108,7 @@ src/morphobricks_preprocessing/
   run/              the run (a package since PP-3; `morphobricks_preprocessing.run` re-exports
                     its public names): preflight.py (Preflight, preflight, sample_planes),
                     pipeline.py (run_experiment, incremental), result.py (RunResult),
+                    entries.py (manifest entries, new/changed/unchanged by RowKey),
                     reuse.py (which earlier rows are reused), rows.py (a file's rows and their
                     pixel checks), publish.py (staged outputs, published together)
   report.py         plain-language summaries shared by CLI and notebook, group statistics tables

docs/plan.md

@@ -1071,3 +1071,14 @@ Raised during review; to be decided before the milestones that need them:
     `pooling` and `records` modules); and `check_declared_axes` with
     `declared_axes_transposed`, removed rather than deprecated because they read a Y/X swap
     transposed, which v0.4 forbids. Breaking for v0.4.0.*
+47. What does manifest version 2 record, and when is a row reused (design v0.4 §1, §3, §6;
+    PP-4)?
+    *Decided (1 November 2026, owner, design revision 4): `manifest_version` "2"; per file
+    `roles` and `axes_from` (`header` or `confirmed`) are required, with `pixel_sizes` by role
+    (value, unit, source); per mask `size`, `mtime_ns`, `roles`, `axes_from` and `shared`; an
+    optional `conversion_record_sha256`. A version 1 manifest gives no reusable row. A row is
+    reused only when its `RowKey` (fingerprint, labels, axes, roles, `axes_from`, read path and
+    the row-changing settings) is the earlier run's. A plain stack's confirmation covers only
+    the files it was given for (`ConfirmedAxes`); a new or changed plain stack is
+    `plain_stack_not_confirmed` until confirmed again (audit 2 B-1). Breaking: every v1 run is
+    recomputed.*

docs/user_guide.md

@@ -542,6 +542,8 @@ continues.
 | `axes_not_named` | Warning | The metadata of some images does not name their axes (a plain stack of pages, `IYX` or `QYX`), so which dimension is depth, time or channel comes only from the roles you confirm. The images are read with them, and the roles are recorded as confirmed by you. Check the roles with the preview. Before segmenting these images in other tools, consider saving named-axis copies (OME-TIFF), so every tool reads the same axes. |
 | `axes_yx_swapped` | Error | The roles you confirmed give the Y and X the image header names the other way round, so the images are not read (never transposed). The message names the likely cause. Two fixes: correct the axes (if the header is right, choose its roles), or convert (save named-axis copies with your roles, then run preprocessing on the copies). |
 | `axes_contradict_header` | Error | The roles you confirmed contradict the axes the image header names (for example the header says channels, C, and you chose time, T). The images are not read under a contradicted declaration. The message names the likely cause, often the tool that saved the files: tifffile labels a 3-D stack saved with `imagej=True` or `ome=True` as `CYX`, and an ImageJ stack of slices reads as depth even for a time-lapse. The same two fixes as `axes_yx_swapped`. |
+| `axes_x_before_y` | Error | The roles you confirmed put X before Y (for example a plain stack confirmed `TXY`). Reading them would transpose every plane, and nothing is ever read transposed. Save the images again with Y before X, or as OME-TIFF copies with Y before X; if the roles are wrong, correct them. |
+| `plain_stack_not_confirmed` | Error | Some images that do not name their axes (plain stacks) are new or changed since you confirmed the axis roles, so the confirmation does not cover them: a plain stack's roles are your statement about the images you checked, and are never applied to others. Check their roles with the preview and confirm them again (on the command line: give `--axes`). |
 | `missing_xy_axis`, `duplicate_axis_role` | Error | X/Y missing or a role used twice. Correct the axis roles. |
 | `unassigned_axis` | Error | A dimension with several planes has no role. Choose Z, C or T. |
 | `unsupported_axis` | Error | A position or tile dimension. Export each position separately. |

pyproject.toml

@@ -125,7 +125,9 @@ baseline = "tools/code_rules_baseline.json"
 "morphobricks_preprocessing._io" = "io"
 "morphobricks_preprocessing.axes" = "pure"
 "morphobricks_preprocessing.axis_check" = "pure"
+"morphobricks_preprocessing.axis_review" = "pure"
 "morphobricks_preprocessing.mask_checks" = "pure"
+"morphobricks_preprocessing.mask_record" = "io"
 "morphobricks_preprocessing.notebook_axes" = "ui"
 "morphobricks_preprocessing.cli" = "ui"
 "morphobricks_preprocessing.dataset" = "pure"
@@ -134,6 +136,9 @@ baseline = "tools/code_rules_baseline.json"
 "morphobricks_preprocessing.image_type" = "pure"
 "morphobricks_preprocessing.intensity" = "io"
 "morphobricks_preprocessing.manifest" = "io"
+"morphobricks_preprocessing.fingerprint" = "io"
+"morphobricks_preprocessing.narrow_ranges" = "pure"
+"morphobricks_preprocessing.recorded_sizes" = "pure"
 "morphobricks_preprocessing.mask_scan" = "io"
 "morphobricks_preprocessing.masks" = "io"
 "morphobricks_preprocessing.metadata" = "io"
@@ -142,8 +147,10 @@ baseline = "tools/code_rules_baseline.json"
 "morphobricks_preprocessing.physical_sizes" = "io"
 "morphobricks_preprocessing.planes" = "io"
 "morphobricks_preprocessing.report" = "pure"
+"morphobricks_preprocessing.sources" = "io"
 "morphobricks_preprocessing.run" = "orchestration"
 "morphobricks_preprocessing.run.pipeline" = "orchestration"
+"morphobricks_preprocessing.run.entries" = "io"
 "morphobricks_preprocessing.run.preflight" = "io"
 "morphobricks_preprocessing.run.publish" = "io"
 "morphobricks_preprocessing.run.result" = "pure"

src/morphobricks_preprocessing/__init__.py

@@ -14,13 +14,11 @@
     AxisMapping,
     AxisReview,
     axis_length_ranges,
-    check_mapping,
     declared_mapping,
     file_mapping_for,
     prefill_experiment_mapping,
     prefill_mapping,
     reference_axes,
-    review_axes,
 )
 from .axis_check import (
     AXIS_CHECK_CODES,
@@ -29,6 +27,7 @@
     header_axis_issue,
     likely_axis_cause,
 )
+from .axis_review import check_mapping, review_axes
 from .dataset import (
     CONSISTENCY_CODES,
     BalanceCell,
@@ -100,7 +99,6 @@
     ManifestFormatError,
     RunManifest,
     RunSettings,
-    check_sources,
     file_sha256,
     read_manifest,
     source_fingerprint,
@@ -174,6 +172,7 @@
 )
 from .report import GroupSummary, group_summaries
 from .run import Preflight, RunResult, SamplePlane, preflight, run_experiment, sample_planes
+from .sources import check_sources
 from .validation import Severity, ValidationIssue, has_errors
 from .zarr_input import (
     NgffError,