[guijacquemet]

What changed

Stage 1 design PR 11 (design section 3 "Run" and "Explicit refusal of heterogeneous runs at Stage 1"). Related to issue 170 (canonical channels recorded in the manifest); it does not close it.

With a published morphobricks.toml in the output folder, run:

• reads it with the strict reader on the exact bytes it hashes; a refusal is reported with the Spec code, table path and a plain message;
• refuses units that declare more than one channel layout with R_HETEROGENEOUS_LAYOUT_NOT_ENABLED (layouts and units named; nothing processed);
• runs the physical R_* checks against the folder and image headers (these were not wired into the run before);
• records experiment_description in run_manifest.json: SHA-256 of the file, section digests, which units' image type was header-verified, status of every declared mask file (checked / not yet checked, with images having a mask out of images), and morphobricks.records.jsonl copied unchanged.

The mask step (masks command, describe_masks) checks each declared mask's representation: a binary mask with more than two values is R_MASK_CONTRADICTS_REPRESENTATION (CLI exits 1, MaskStepResult.issues). What it checked is written to mask_representation.json, each file bound to the fingerprint it had when read, so a new batch is not yet checked again. Publication and the run read no mask pixels.

Owner Q1: a run without a description is the v0.4 run (byte-identical outputs, no new manifest key) and issues a UserWarning.

Conformance P04, P05, P11, P28 are in tests/test_spec_run_description.py (added to the Spec gate's expected modules).

Why

The notebook and later stages need the run to carry the confirmed description and to stop on layouts it cannot process yet.

Regression tests

tests/test_spec_run_description.py (9 tests) and tests/test_run_description.py (10). Run against origin/main code the Spec file gives 9 failures; for example test_p04_heterogeneous_layouts_are_refused_and_nothing_is_processed[v04] fails because the old run writes the output (assert not True), and v05/v06/v17 give only different_channel_counts, not the Spec code.

Checks

python tools/check.py: ruff and code rules clean; 4170 passed, 4 skipped, 0 failed. The 4 skips are environmental (case-sensitive file system x3, running as root x1), none Spec or parity. The v0.4.0 parity suite (tests/test_parity_v0_4_0.py) passed.

Not done here (needs a decision or is outside this PR)

• The global channel_names_differ and different_channel_counts checks are not yet replaced by per-unit checks for described runs (P26 aliases); they still run, so a described run with differing header spellings is refused loudly, not accepted wrongly.
• spec_commit is not in the manifest entry: the package holds no pinned Spec commit (only the tests' PIN.toml).
• The notebook's mask card ignores MaskStepResult.issues; the notebook is a later PR.

---

Generated by Claude Code