Require explicit opt-in on experimental and internal-only GeoTIFF paths (PR 4 of epic #2340) #2352

Reason or Problem

Epic #2340 places several GeoTIFF code paths in the Experimental and Internal-only tiers. Today, only some of them are gated behind an explicit opt-in kwarg. The rest still accept a default call, which is at odds with the release contract: a caller cannot tell from the call site whether they are signing up for an unstable surface.

The two writer codec gates are in place (allow_experimental_codecs for LERC/J2K/JPEG2000/LZ4, allow_internal_only_jpeg for JPEG-in-TIFF). The read side has no equivalent gate, and several writer attrs-driven paths (gdal_metadata_xml, extra_tags) pass through without an opt-in.

Proposal

For each path on the audit list below, default behavior raises a ValueError whose message names the missing kwarg, the feature, and points at the release-contract tier. The opt-in flag lets the call through unchanged. Add a regression test under xrspatial/geotiff/tests/ per path that pins the no-flag failure.

Paths to audit (from xrspatial/geotiff/_attrs.py::SUPPORTED_FEATURES):

Experimental:

• LERC decode -> allow_experimental_codecs=True
• JPEG2000 / J2K decode -> allow_experimental_codecs=True
• LZ4 decode -> allow_experimental_codecs=True
• gdal_metadata_xml writer -> allow_experimental_codecs=True
• extra_tags writer -> allow_experimental_codecs=True

Internal-only:

• JPEG-in-TIFF decode -> allow_internal_only_jpeg=True

Already gated (pinning tests only):

• LERC/J2K/JPEG2000/LZ4 encode (covered by test_supported_features_tiers_2137.py)
• JPEG-in-TIFF encode
• GPU read / write (gpu=True is itself the opt-in)
• allow_rotated reader
• allow_unparseable_crs reader

Each gate fires at the read or write entry point, before any IO or decode work. The error message follows the existing shape used by the writer codec gate so the messages stay consistent across the read and write sides:

compression='lerc' is experimental on the read side too: cross-backend numerical parity is not claimed and reader support across GDAL versions is uneven. Pass allow_experimental_codecs=True to open_geotiff / read_geotiff_dask / read_geotiff_gpu to opt in, or open the file with a stable lossless codec source. See SUPPORTED_FEATURES tier 'experimental' (epic #2340).

Stakeholders and Impacts

Touches xrspatial/geotiff/__init__.py, xrspatial/geotiff/_reader.py, xrspatial/geotiff/_backends/, and xrspatial/geotiff/_writers/eager.py / gpu.py. Adds one new kwarg surface on the readers (allow_experimental_codecs, allow_internal_only_jpeg) and one on the writer entry points for the rich-tag passthrough. Existing callers that hit an experimental decode path will see a rejection with an actionable message and a named flag.

Out of scope:

• Docstring rewrites for the public API (PR 3).
• SUPPORTED_FEATURES tier audit (PR 1).
• Docs page or feature-tier table (PR 2).
• Unsupported-combination errors (PR 5).

Drawbacks

The read side gains a new failure mode for files that previously decoded silently. The opt-in kwarg fixes the call site in one line and the rejection message names the flag, so the migration path is mechanical.

Alternatives

• Warn instead of raise. The epic places these paths in Experimental and Internal-only; a warning would not deliver on the "experimental requires explicit opt-in" promise.
• Bundle the codec decode gate into PR 5 (unsupported combinations). PR 5 is about combinations that should fail outright; this PR is about combinations that should work once the caller opts in.

Additional Notes or Context

Parent epic: #2340. PR 4 of 6. Sibling issues: #2346 (docstrings), #2347 (docs page), #2348 (SUPPORTED_FEATURES audit), #2349 (unsupported combinations).