release: v10.16.0 — JP3DDecoder partial-decode discoverable convenience overloads

[SureshKViswanathan]

Summary

• Adds three convenience overloads on JP3DDecoder — decode(_:resolutionLevel:), decode(_:region:), decode(_:region:resolutionLevel:) — that surface the JP3D partial-decode pipelines behind the canonical JP3DDecoder type. The underlying pipelines (v10.18-research partial-resolution + v10.13.0 K+ROI composition) have been production-default since v10.10.0; the gap was discoverability — consumers had to know to either construct a JP3DDecoderConfiguration(resolutionLevel:) or switch to JP3DROIDecoder.
• The overloads are thin wrappers — they construct a transient inner decoder / JP3DROIDecoder with the requested options and delegate. No hot-path code changes; same pipelines run underneath.
• MINOR per RELEASING.md — additive public API only, no signature changes, no perf change on existing paths, codestream bytes byte-identical to v10.15.0.

Speedups surfaced (existing pipelines)

Workload	Full decode	New convenience	Pipeline source
Thumbnail at level 1 (small-mid JP3D)	1.0×	2.2-3.1× faster	v10.18-research P2
ROI ~1/4 spatial extent	1.0×	3.4-4.1× faster	v10.18-research P3+P6
K=1 + ROI 1/4 extent	1.0×	both savings stack	v10.13.0 K+ROI matrix

Correctness gate (release mode)

• V10_28_JP3DDecoderPartialOverloadsParityTests 6/6 PASS (bit-exact: all three overloads byte-identical to existing JP3DDecoderConfiguration + JP3DROIDecoder usage; no-op level (0) bit-exact to decode(_:); negative level clamped; outer-configuration propagation verified)
• swift test --filter JP3D regression 528/528 PASS (519 pre-existing + 9 new = 2 V10_27 probe + 6 V10_28 parity + 1 pre-existing skip)
• J2KMedicalCorpusEncodePerformanceTests 2/2 PASS
• J2KMedicalCorpusPerformanceTests 2/2 PASS
• J2KStrictCrossCodecValidationTests 3/3 PASS

Mandatory commit gate: 7/7 PASS release mode.

Companion probe — encoder preWarm wash

The natural symmetric ship to v10.15.0's JP3DDecoder.preWarm would have been JP3DEncoder.preWarm. V10_27 cold-start probe (research diagnostic, on this RC) measured the leftover encoder-specific cold cost AFTER JP3DDecoder.preWarm(includeWarmupDispatch: true):

Fixture	Path A (cold)	Path B (after decoder preWarm)	Path C (warm median)	(B - C)
128×128×16	57.56 ms	8.10 ms	8.01 ms	+0.10 ms
256×256×16	77.18 ms	26.89 ms	28.14 ms	−1.25 ms

Both fixtures show < 3 ms leftover — the existing decoder preWarm's warmup-dispatch (a real synthetic 256² encode+decode) already amortises encoder Metal init via J2KMetalSession.processShared. A dedicated encoder preWarm would be a no-op API. Per feedback_no_half_releases.md, NOT shipped.

Test plan

• Mandatory pre-release gate (release mode)
• JP3D regression sweep (528/528 PASS)
• New V10_28 parity tests (bit-exact for all three overloads)
• V10_27 encoder cold-start probe (documents the wash decision)
• README.md updated (Current Version + Previous Release + new Release Status paragraph) per feedback_readme_mandatory_per_release.md
• getVersion() constant bumped 10.9.2 → 10.16.0 (had drifted across 8 releases)

🤖 Generated with Claude Code