[guijacquemet]

Stacked on #211 (base is claude/z-projection-core, so the diff shows only this PR; GitHub retargets it to main when #211 is merged and its branch deleted).

What changed

Second PR of the plan for #176 (design: MorphoFeature docs/restart/designs/pp176-z-projection-design-2026-11-07.md; owner answers of 2026-11-07). The conversion record learns to hold a projection. Nothing writes one yet.

• RECORD_VERSION = "3". New record-level projection (null, or {method, z_range}), the entry action projected, and a per-entry projection object (new pure module projection_record.py, ProjectionEntry): source_relative_path, source_content_sha256, source_z_axis ({letter, index} or null), source_z_size, z_range (slices actually used), method, source_dtype, output_dtype, dtype_rule, rounding, nan_policy (propagate), dropped_sizes ({"Z": {value, unit, source} | null}), significant_bits_dropped.
• Strict reading. A projected entry is refused when its keys are not exactly these, its slice range does not fit its Z size, a stack has no Z axis, its output type or rounding is not what the dtype table of Z projection 1/6: the pure arithmetic (part of #176) #211 gives for its (input type, method, slice count), or the source SHA-256 is missing. A record is refused when a projected entry has no record projection (and the reverse), or an entry's method or range is not the record's (an excluded image stays a plain copied entry). A version 2 record may not hold a projection field.
• Reuse key: CopyEntry.same_plan now includes the projection (everything except the source content SHA-256, which the write computes), so another method or range into the same tree is copy_differs once the writer exists, and an identical rerun reuses.
• Compatibility: version 2 records are still read (as trees without a projection); version 1 is still refused; a reader that knows only version 2 refuses version 3 (its check is !=). Every new record is version 3, projection: null when nothing was projected.
• Docs: contract §17 ("Projected copies" row, record version 3 text), plan §12 question 77 (owner decision), AGENTS repo map, CHANGELOG. The user-guide message codes come with the PR that first emits them (PR 3), so no code is documented that nothing can print yet.

Regression test

tests/test_projection_record.py (33 tests): v3 round trip; a tree without a projection is version 3 with null; a version 2 record is still read; a version 2 record cannot hold a projection; versions 1, 4 and missing are refused; every field of the projection changes the reuse key and the content SHA-256 does not; 20 contradiction cases are refused (missing or extra keys, wrong method or rounding, range outside the stack, output type not the table's, sum that could not be exact, and so on). tests/test_convert_integrity.py now expects record version "3".

• On the old code (the tip of Z projection 1/6: the pure arithmetic (part of #176) #211): the module fails at collection, ImportError: cannot import name 'PROJECTED' from 'morphobricks_preprocessing.conversion_record' (1 error, 0 tests run).
• On this branch: 33 passed.

Checks

python tools/check.py: Ruff, formatting and code rules clean; 4284 passed, 4 skipped, 2 warnings. The base (#211) gives 4251 passed, 4 skipped, 2 warnings; the difference is the 33 new tests. The 4 skips are the pre-existing ones (case-insensitive file system x3, file modes x1).

Series: 1 pure module (#211), 2 record v3 (this PR), 3 plan and write, 4 CLI, 5 run side, 6 notebook card.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Scma6W3LC11s3qjXHZuGDm