Tracking: gain-map encode pipeline Phases 1–4 (docs/gainmap-pipeline-scope-2026-06-08.md)

The scope doc fully designs gain-map/HDR delivery through the codec-agnostic encode path; the decode side has largely landed (`GainMapRender` intent + `reconstructs_hdr` capability, #23/e43d4b1 — zenjpeg and heic adapters honor it). This issue tracks the remaining phases:

- **Phase 0 — prove native HDR**: tests that PQ/HLG CICP + high-bit-depth pixels round-trip through the existing color-emit path for AVIF/JXL/PNG; confirm `Metadata.content_light_level`/`mastering_display` reach each native encoder.
- **Phase 1 — the contract (additive)**: `GainMapEncodeSource` (gain-map *pixels* + `GainMapInfo`, mirroring `DecodedGainMap` as an input), `EncodeJob::with_gain_map` (provided no-op default), HDR emit policy (`Native`/`GainMap`/`Auto`), capability-contract clarification, testkit `check_gain_map_*` conformance checks.
- **Phase 2 — per-codec composition**: implement `with_gain_map` in zenjpeg (→ ultrahdr assemble), zenavif (→ zenavif-serialize tmap), zenjxl (when the jhgm box is exposed). Note: zencodecs already carries per-codec `encode_with_precomputed_gainmap` glue in `codecs/{jpeg,avif_enc,jxl_enc}.rs` — that glue should sink into the codec adapters once the trait method exists.
- **Phase 3 — framework convenience**: `encode_hdr(job, hdr_pixels, policy)` + lift the tonemap/gain-map-fit math to ultrahdr-core so codecs only compose.
- **Phase 4 — transcode round-trip**: decode `Components` → `GainMapEncodeSource` → `with_gain_map`, with a testkit cross-path check.

Decode-side residual while in here: zenavif and zenjxl codec adapters show no `GainMapRender` handling (zenjpeg/heic do) — wire `ReconstructHdr`/`Components` or decline honestly per the doc's fallback semantics.