Add VRT support contract docs (#2368)

README.md

@@ -150,6 +150,8 @@ In the GIS world, rasters are used for representing continuous phenomena (e.g. e
 
 Native GeoTIFF and Cloud Optimized GeoTIFF reader/writer. No GDAL required.
 
+VRT is supported as a conservative advanced feature for simple GeoTIFF mosaics, not as a full GDAL VRT replacement. See the [VRT support matrix](docs/source/reference/geotiff.rst#vrt-support-matrix-issue-2321) for the supported subset and what is out of scope.
+
 | Name | Description | NumPy | Dask | CuPy GPU | Dask+CuPy GPU | Cloud |
 |:-----|:------------|:-----:|:----:|:--------:|:-------------:|:-----:|
 | [open_geotiff](xrspatial/geotiff/__init__.py) | Read GeoTIFF / COG / VRT | ✅️ | ✅️ | ✅️ | ✅️ | ✅️ |

docs/source/reference/geotiff.rst

@@ -198,6 +198,8 @@ with spatial coords on both axes but no explicit transform raises
 Multi-row / multi-column writes are unaffected. 1x1 inputs still
 require ``attrs['transform']`` because neither axis has a step.
 
+.. _reference.geotiff.vrt_support_matrix:
+
 VRT support matrix (issue #2321)
 ================================
 

xrspatial/geotiff/__init__.py

@@ -389,8 +389,8 @@ def open_geotiff(source: str | BinaryIO, *,
     - Default: NumPy eager read
 
     VRT files are auto-detected by extension. The supported VRT subset
-    is narrow on purpose (issue #2321; epic #2340). See the "VRT
-    support matrix" section in ``docs/source/reference/geotiff.rst``
+    is narrow on purpose (issue #2321; epic #2340; epic #2342). See the
+    "VRT support matrix" section in ``docs/source/reference/geotiff.rst``
     and the audited matrix in
     ``docs/source/reference/release_gate_geotiff.rst`` for the
     canonical contract. In short:

xrspatial/geotiff/_backends/vrt.py

@@ -170,7 +170,9 @@ def read_vrt(source: str, *,
     reprojection VRTs, arbitrary resampling beyond the tested subset,
     mixed CRS / resolution / dtype / band metadata without an opt-in,
     nested VRTs, complex source / mask band / alpha band structures,
-    full GDAL VRT parity.
+    full GDAL VRT parity. The conservative-feature framing is from epic
+    #2342; the canonical contract is the "VRT support matrix" section
+    in the geotiff reference docs.
 
     The VRT's source GeoTIFFs are read via windowed reads and assembled
     into a single array.

xrspatial/geotiff/_vrt.py

@@ -1175,6 +1175,40 @@ def read_vrt(vrt_path: str, *, window=None,
     Returns
     -------
     (np.ndarray, VRTDataset) tuple
+
+    Notes
+    -----
+    The VRT path is a conservative advanced feature scoped to simple
+    GeoTIFF mosaics rather than full GDAL VRT parity. See epic #2342
+    and the "VRT support matrix" section of the geotiff reference
+    docs (issue #2321) for the canonical contract.
+
+    *Supported:*
+
+    * Simple GDAL VRT mosaics backed by GeoTIFF sources.
+    * Compatible source CRS, dtype, transform orientation, pixel size,
+      band count, and band layout.
+    * Windowed reads where source and destination windows map cleanly.
+    * Lazy / dask reads over the same supported subset.
+    * Explicit nodata handling.
+    * Mixed-band nodata rejection by default. Opt-ins are documented on
+      the kwargs that enable them (e.g. ``band_nodata='first'`` on
+      ``open_geotiff``).
+    * ``missing_sources='raise'`` is the default. ``'warn'`` is an
+      explicit opt-in for partial mosaics.
+
+    *Not supported.* The reader fails closed (rather than silently
+    flattening) on any of the following:
+
+    * Full GDAL VRT compatibility.
+    * Warped / reprojection VRTs.
+    * Nested VRTs.
+    * Arbitrary resampling semantics beyond the implemented and tested
+      subset.
+    * Mixed CRS, mixed dtype, mixed resolution, or mixed band metadata
+      unless explicitly supported.
+    * Complex mask, alpha, or source semantics that are not represented
+      in the GeoTIFF attrs contract.
     """
     from ._reader import PixelSafetyLimitError, read_to_array