[guijacquemet]

Summary

Fixes #35.

• masks.py: new check_labels(pixels, name) raises ValueError when a mask holds a negative value; read_mask calls it.
• mask_scan.py: piece_counts and pair_counts call it too, so 0 is always the background (it can only be dropped as "the smallest value" once negatives are refused).
• cli.py: the masks command catches the ValueError from scan_masks, prints it with the mask's path and exits 1. No report is written.
• Docs: contract §15.1 and user guide §5/§9 say that objects have positive labels and that a negative label is refused when the pixels are read.

Why

At v0.3.1, if an int16 mask held -1, 0 and 3, piece_counts returned the labels [-1, 0, 3]. That made the background an object, and the mask kinds, object counts and mask_relationships.json came out wrong with no warning. The header check cannot see pixel values, so a signed dtype is still accepted there. The refusal happens when the pixels are read. This follows the existing rule that a mask which is not 2D when read raises an error.

Notes for review

• The refusal is a ValueError, not a ValidationIssue, because the header-only find_masks never reads pixels.
• Error codes and the manifest are unchanged.

Tests

• New regression tests:
  • tests/test_mask_scan.py::test_negative_labels_are_refused_never_read_as_objects
  • tests/test_masks.py::test_masks_command_refuses_negative_labels
• Both fail on main ("DID NOT RAISE ValueError" and exit code 0 instead of 1). On main, piece_counts of the -1/0/3 mask returns [-1, 0, 3].
• Full suite (Python 3.13, zarr 3.4.2, notebook extra installed): 1053 passed, 1 skipped. The skip is test_discovery.py:472: running as root ignores file modes. On main the same environment gives 1051 passed, 1 skipped.
• ruff check . and ruff format --check . are clean.
• Not run: Windows, macOS, Python 3.11 / zarr 2.18.

---

Generated by Claude Code

[guijacquemet]

Merged main (#42, #43) in: check_labels now runs on the plane #43's read_mask reads, so docstrings, contract §15 and the CLI comment describe both refusals, and both sides' tests are kept. I added a regression test showing that negative labels in a later time point of a TYX mask are refused. 1075 passed, 1 skipped (test_discovery.py:472, root), ruff clean, CI 7/7 green on b8a1998. Merging.

---

Generated by Claude Code