[guijacquemet]

Fixes #72, fixes #73, fixes #94

Before-audit batch A (triage 2026-11-02): OME-Zarr axes and calibration. Design v0.4 §2, §3 and §9 apply: nothing guessed, nothing silent.

Summary (by module)

• axes.py: new ome_zarr_mapping. Every OME-Zarr image is matched by the roles its OME-NGFF axes declare, including one whose axis letters equal the mapping's. With the same arrangement, any confirmed role that is not the declared letter for that axis is refused ("contradicted"). file_mapping_for uses it, so the consumer path has the same policy ([Audit/Scientific integrity] OME-Zarr with matching axis letters can be processed under contradictory confirmed roles #72).

• axis_review.py: review_axes resolves files in _resolve_files and builds the OME-Zarr error in _ome_zarr_issues. Contradicted images get ome_zarr_axes_mismatch, naming each one, e.g. declared ZYX, confirmed TYX: ctrl/a.ome.zarr. They never reach file_mappings, so they are never read ([Audit/Scientific integrity] OME-Zarr with matching axis letters can be processed under contradictory confirmed roles #72).

• zarr_input.py: the version is read before the axes, and ngff_axes(axes, version) refuses (NgffError → unreadable_ome_zarr) ([Audit/Scientific integrity] Missing axes metadata in NGFF 0.4/0.5 can silently default 5D images to TCZYX #73):

  • every OME-NGFF 0.1 or 0.2 store, whatever it contains: "re-save it as OME-NGFF 0.4 or later" (owner decision, 2026-11-02; no spec-default t, c, z, y, x);
  • a 0.3, 0.4 or 0.5 store without axes, and a store without axes that states no version or another one (no confirmation path);
  • axes that are not a list.

  The blanket except Exception + debug log around the sizes is removed ([Sad Catapella B6][Scientific QA] Malformed explicit NGFF coordinate transforms are silently treated as unknown calibration #94).

• ngff_scale.py (new, pure): read_scale returns the level or image scale together with plain-language problems: transformations not a list; a type other than scale, translation or identity; two scales; a scale stored in a file (path); not one number per axis; a value that is not a list of numbers; an X/Y/Z/T value that is not a positive finite number ([Sad Catapella B6][Scientific QA] Malformed explicit NGFF coordinate transforms are silently treated as unknown calibration #94).

• physical_sizes.py: new PhysicalSizes.invalid (the reason; not part of equality). ngff_physical_sizes records it instead of returning a bare PhysicalSizes() ([Sad Catapella B6][Scientific QA] Malformed explicit NGFF coordinate transforms are silently treated as unknown calibration #94).

• pixel_size_checks.py / dataset.py: new warning invalid_physical_calibration, naming every image with its reason, also when all images are malformed. It is computed on the resolved sizes and goes once every size the malformed calibration leaves unknown is stated in calibration.csv; a time step cannot be stated there, so a lost time step of a time series stays named. In PIXEL_SIZE_CODES and CONSISTENCY_CODES, kept in discovery_report.json ([Sad Catapella B6][Scientific QA] Malformed explicit NGFF coordinate transforms are silently treated as unknown calibration #94).

• Docs: contract §2, §8, §11; user guide; plan question 60 (decided); AGENTS.md.

Owner decisions (2026-11-02), recorded in plan question 60

1. [Audit/Scientific integrity] OME-Zarr with matching axis letters can be processed under contradictory confirmed roles #72: the code is ome_zarr_axes_mismatch, not the axis-check codes, which offer conversion (an OME-Zarr image cannot be converted). A Q axis never gets a role.
2. [Audit/Scientific integrity] Missing axes metadata in NGFF 0.4/0.5 can silently default 5D images to TCZYX #73: OME-NGFF 0.1/0.2 stores are refused (the PR first kept TCZYX for 5-D arrays; changed in review). Stores without axes are refused, with no confirmation path.
3. [Sad Catapella B6][Scientific QA] Malformed explicit NGFF coordinate transforms are silently treated as unknown calibration #94: a warning, not an error. The image is uncalibrated with the reason, and the warning goes once the sizes are stated in calibration.csv.

Review (independent reviewer)

Commits: 718e8b5, 8fdf7de (merge of main with #126), eeae9d0, 67bdea5 (merge of main with #127).

• Owner decision implemented: 0.1/0.2 refusal, with regression tests: a 5-D store, with and without axes, through open_ngff, inspect_image and preflight. ngff_axes loses its unused ndim parameter.
• Finding (fixed): invalid_physical_calibration disappeared once X and Y (and Z) were stated, even when the malformed scale had also lost the time step of a time series. The time step cannot be stated, so the loss became silent. The new _lost_roles check fixes this; 4 parametrised cases; the T case fails on e0e6c20.
• Merge with main (PP-11c: conversion integrity (copy SHA-256, metadata epochs, exact CLI sizes) #126): one PP-11c test wrote a zyx store into an experiment confirmed ZYX → ZXY. That is exactly the [Audit/Scientific integrity] OME-Zarr with matching axis letters can be processed under contradictory confirmed roles #72 contradiction, now refused. The store is now tzyx with one time point, matched by role, so the test still checks the reuse of a changed chunk.
• Verified in code:
  • file_mapping_for and review_axes are the only resolvers, and the preview, sources, preflight and notebook all use file_mapping_for;
  • the version is read before the axes;
  • every malformed case gives invalid with a specific reason, and no silent fallback is left (no broad except on the scale path).
• Valid stores are unchanged. End to end, a 0.4 and a 0.5 store were run (run_experiment, 2 conditions × 2 images, CZYX, calibrated) on main 8db1f4a and on this branch: run_manifest.json and discovery_report.json differ only in paths, mtimes and timestamps, and plane_histograms.csv is byte-identical.

Tests

• tests/test_ngff_axes_calibration.py: 35 tests. On main 8db1f4a, 30 fail and 5 pass (the controls).
• Full gate on 67bdea5 (uv venv, Python 3.11, .[dev,notebook,zarr], zarr 3.1.6, running as root): python tools/check.py passed:
  • ruff check clean, ruff format 181 files;
  • pytest 1831 passed, 1 skipped (test_discovery.py:665, permissions ignored as root: expected), 1 warning;
  • code rules passed.

Code standards (§9), measured

• Largest file touched: physical_sizes.py 684 lines (baselined, 706 → 684). New ngff_scale.py 113 lines; zarr_input.py 439.
• Largest function touched: review_axes 67 executable lines (baselined, 106 → 67). New functions are all 40 lines or fewer.
• Highest complexity among touched functions: _resolve_files 10. Then read_scale and ngff_axes 8; ngff_physical_sizes and _level0 7.
• Parameters: at most 4.
• CI green on all 7 jobs (lint; Ubuntu, Windows, macOS × Python 3.11, 3.13).
• Ratchet: the baseline only shrinks; # noqa 79 → 78 (ANN 54 → 53); no new exemption.

https://claude.ai/code/session_01G3qp9AxjpGPw9xfWAUJNqc

---

Generated by Claude Code

[guijacquemet]

Independent review: merged as 7f55ba1 (merge commit). The branch was auto-deleted on merge and has been restored at the PR head, 67bdea5.

Owner decisions implemented (2026-11-02)

• OME-NGFF 0.1/0.2 stores are refused (unreadable_ome_zarr) whatever they contain, with "re-save it as OME-NGFF 0.4 or later". No spec-default t, c, z, y, x remains (718e8b5).
• Stores without axes stay refused, with no confirmation path.
• Malformed calibration stays a warning.
• ome_zarr_axes_mismatch is kept.

All of these are recorded in plan question 60.

Findings fixed

• 718e8b5: invalid_physical_calibration disappeared once X and Y were stated in calibration.csv, even when the malformed scale had also lost a time series' time step. A time step cannot be stated there, so that loss was silent. The warning now stays until every lost size is stated. Regression test added; it fails on e0e6c20.
• eeae9d0: after merging main, a PP-11c: conversion integrity (copy SHA-256, metadata epochs, exact CLI sizes) #126 test put a zyx store into an experiment confirmed ZYX → ZXY. That is the [Audit/Scientific integrity] OME-Zarr with matching axis letters can be processed under contradictory confirmed roles #72 contradiction, now correctly refused. The store was given its own arrangement (tzyx, T = 1) so the test still covers the reuse of a changed chunk.

Verified in code

• Every OME-Zarr image goes through ome_zarr_mapping, whatever its letters, in both review_axes and file_mapping_for. Preview, sources, preflight and the notebook all use file_mapping_for.
• ZYX→TYX, ZXY and QYX→CYX are refused and never reach file_mappings, so they are never read.
• The version is read before the axes. 0.3, 0.4 and 0.5 stores without axes are refused.
• Each malformed calibration case gives a specific reason in PhysicalSizes.invalid. The broad except is gone.
• Valid stores are unchanged. End to end with valid 0.4 and 0.5 stores (CZYX, calibrated, 2 conditions × 2 images), main 8db1f4a and this branch give the same run_manifest.json and discovery_report.json apart from paths, mtimes and timestamps, and a byte-identical plane_histograms.csv.
• New tests: 30 of the 35 in test_ngff_axes_calibration.py fail on main 8db1f4a.

Gate on 67bdea5 (uv venv, Python 3.11, .[dev,notebook,zarr], root)

• ruff check clean; ruff format: 181 files already formatted.
• pytest: 1831 passed, 1 skipped (test_discovery.py:665, root, expected).
• code rules passed.
• CI green on all 7 jobs.

§9 figures

• Largest file touched: physical_sizes.py, 684 lines (baselined, down from 706).
• Largest function: review_axes, 67 executable lines (baselined, down from 106). New functions are 40 lines or fewer.
• Highest complexity: _resolve_files, 10.
• At most 4 parameters.
• # noqa count 79 → 78; the baseline only shrinks.

Issues #72, #73 and #94 are closed.

---

Generated by Claude Code