Reject mixed-tier VRT child sources under stable_only=True (epic #2342)

[brendancol]

Summary

The release-gate test test_release_gate_negative_mixed_tier_vrt_children pins a promise from epic #2342: when a caller asks for stable-only sources and a VRT child uses an experimental codec, the reader must name the offending child and the opt-in flag. The knob does not exist yet, so the test is xfail(strict=False) today.

Proposed change

Add stable_only: bool = False to open_geotiff, read_geotiff_dask, read_geotiff_gpu, and read_vrt. When True, the VRT capability validator rejects any source whose codec tier in SUPPORTED_FEATURES is not stable. The rejection raises a GeoTIFFAmbiguousMetadataError subclass that names the offending source path and the allow_experimental_codecs opt-in, and cites the release-contract docs.

Scope

• Fires at graph-build / eager-read setup time so the failure surfaces before any pixel decode.
• Non-VRT call sites with stable_only=True are a no-op; the per-source codec gate already covers them via _validate_read_codec_optin.
• Default behaviour (stable_only=False) is unchanged.

Acceptance

• test_release_gate_negative_mixed_tier_vrt_children flips from xfail to a regular pass.
• A GeoTIFFAmbiguousMetadataError subclass names the source path and the allow_experimental_codecs opt-in.
• The kwarg threads through every public read entry point in the canonical position from _CANONICAL_ORDER.

Related

• Epic Epic: Conservative VRT support contract for GeoTIFF release #2342.
• Precedent: PR Reject non-finite/fractional int GDAL_NODATA on read (#2441) #2442 (typed error + opt-in kwarg + canonical-order entry for allow_invalid_nodata).