geotiff: reject writes whose crs and crs_wkt attrs disagree (#1987 PR 1)

First fail-closed slice for issue #1987. The framework PR (#2006)
landed the error hierarchy and the validator-hook registry; this PR
wires the first check.

Behaviour today
---------------
``to_geotiff`` / ``_write_vrt_tiled`` / ``write_geotiff_gpu`` all
consult ``data.attrs.get('crs')`` first and fall back to
``data.attrs.get('crs_wkt')`` only when the EPSG attr is missing.
When the two attrs encode different CRSes the writer silently emits
the EPSG and drops the WKT, producing a TIFF whose on-disk CRS does
not match what the DataArray advertised.

Change
------
* ``_validation.py`` gains ``_check_write_conflicting_crs``: when
  both attrs are populated and neither is suppressed by an explicit
  ``crs=`` kwarg, the check canonicalises each via pyproj and raises
  ``ConflictingCRSError`` if they disagree. ``ConflictingCRSError``
  is exported from ``xrspatial.geotiff`` already (the framework PR
  added it to ``_errors.py``).
* The check is registered at module load via
  ``register_write_metadata_check``. Tests that need to scope around
  it can call ``unregister_write_metadata_check`` in a fixture.
* The three write entry points (``to_geotiff``,
  ``_write_vrt_tiled``, ``write_geotiff_gpu``) now call
  ``validate_write_metadata`` with a context dict carrying
  ``crs_kwarg``, ``attrs_crs``, and ``attrs_crs_wkt``.

Soft preconditions kept lenient
-------------------------------
* No pyproj installed -> no-op (the writer's own WKT-fallback path
  decides what happens; pyproj is otherwise listed in setup.cfg).
* Either attr unparseable -> no-op (sibling
  ``UnparseableCRSError`` PR will catch those).
* Caller passes ``crs=`` explicitly -> short-circuit, since the
  kwarg overrides both attrs for this write.

Round-trip safety
-----------------
The reader emits ``attrs['crs']`` and ``attrs['crs_wkt']`` whenever
the file has a CRS, so a typical ``open_geotiff -> to_geotiff`` pair
hits the check with both attrs set. They derive from the same on-disk
CRS, so pyproj equality passes and the write proceeds. The
end-to-end ``test_read_back_roundtrip_does_not_raise`` pins this.

Tests
-----
14 new tests in ``test_conflicting_crs_write_1987.py`` cover:
* registration in the write-side hook registry
* exception-class hierarchy (ValueError + GeoTIFFAmbiguousMetadataError)
* disagreement raises
* agreement passes (EPSG int + WKT, EPSG string + WKT)
* only-one-attr-set cases pass
* explicit ``crs=`` kwarg bypasses the check
* ``crs=0`` corner does not mask the existing kwarg validation
* unparseable WKT defers to the (future) ``UnparseableCRSError``
* end-to-end read-back round-trip

Full geotiff test suite passes (2993 tests, no regressions).

Author: brendancol

CHANGELOG.md

@@ -12,6 +12,7 @@
 - Decode TIFF predictor=3 un-transpose by file byte order so big-endian floating-point TIFFs read back exactly
 - Default internal `_vrt.read_vrt` `missing_sources` to `'raise'` so an unreadable VRT source no longer produces a silent zero-fill hole on integer rasters; pass `missing_sources='warn'` to opt back into the previous lenient behaviour (#1843)
 - Deprecate read-side emission of matplotlib colormap-derived attrs (cmap, colormap_rgba) on palette TIFFs; the writer cannot set Photometric=3 so they do not round-trip. Construct ListedColormap from attrs['colormap'] in caller code. These attrs still emit for now but trigger a DeprecationWarning. Removal planned for a future release. (#1984)
+- Reject writes whose `attrs['crs']` and `attrs['crs_wkt']` resolve to different CRSes (after pyproj canonicalisation) instead of silently emitting the EPSG and dropping the WKT. The new `ConflictingCRSError` (subclass of `ValueError` and `GeoTIFFAmbiguousMetadataError`) names the offending attrs; pass `crs=` explicitly to override both attrs and bypass the check. Read-back DataArrays carrying both attrs continue to round-trip because the reader's two attrs derive from the same on-disk CRS. (#1987)
 
 
 ### Version 0.9.9 - 2026-05-05

xrspatial/geotiff/_validation.py

@@ -26,6 +26,7 @@
 import numpy as np
 
 from ._coords import _BAND_DIM_NAMES
+from ._errors import ConflictingCRSError
 from ._runtime import _TIME_DIM_NAMES, _X_DIM_NAMES, _Y_DIM_NAMES
 
 
@@ -433,3 +434,83 @@ def validate_write_metadata(context: Mapping[str, Any] | None = None) -> None:
     # Snapshot for the same reason as the read hook above.
     for check in tuple(_WRITE_METADATA_CHECKS):
         check(ctx)
+
+
+# ---------------------------------------------------------------------------
+# Conflicting crs / crs_wkt write check (issue #1987 PR 1)
+# ---------------------------------------------------------------------------
+
+
+def _check_write_conflicting_crs(context: Mapping[str, Any]) -> None:
+    """Refuse writes whose ``attrs['crs']`` and ``attrs['crs_wkt']`` disagree.
+
+    The legacy writer consults both attrs (``crs`` takes priority; the
+    WKT is a fallback). When the two encode different CRSes, the writer
+    silently emits the EPSG and drops the WKT, producing a TIFF whose
+    on-disk CRS does not match what the caller's DataArray advertised.
+
+    This check runs whenever both attrs are populated. It canonicalises
+    each via :mod:`pyproj` and raises :class:`ConflictingCRSError` if
+    they do not match. A read-back DataArray that legitimately carries
+    both attrs (the reader emits both when the file has a CRS) passes
+    because the two derive from the same on-disk CRS.
+
+    Soft preconditions kept lenient:
+
+    * ``pyproj`` not installed -> no-op (downstream paths handle the
+      missing dependency).
+    * Either attr unparseable -> no-op (a sibling check in this issue's
+      series, :class:`UnparseableCRSError`, will refuse those on its
+      own PR).
+
+    Context keys consumed:
+
+    * ``crs_kwarg`` -- the value of the explicit ``crs=`` writer kwarg.
+      When this is not ``None`` the kwarg overrides both attrs, so the
+      attrs disagreement does not affect this write and the check
+      short-circuits.
+    * ``attrs_crs`` -- the value of ``data.attrs.get('crs')``.
+    * ``attrs_crs_wkt`` -- the value of ``data.attrs.get('crs_wkt')``.
+
+    All keys are optional; absence is treated as "nothing to compare".
+    """
+    if context.get('crs_kwarg') is not None:
+        return
+    crs_attr = context.get('attrs_crs')
+    crs_wkt_attr = context.get('attrs_crs_wkt')
+    if crs_attr is None or not crs_wkt_attr:
+        return
+    try:
+        from pyproj import CRS as _PyProjCRS
+    except ImportError:
+        return
+    try:
+        crs_from_attr = _PyProjCRS.from_user_input(crs_attr)
+        crs_from_wkt = _PyProjCRS.from_wkt(crs_wkt_attr)
+    except Exception:
+        return
+    if crs_from_attr.equals(crs_from_wkt):
+        return
+    # Truncate the WKT in the message; full WKTs are 1-3 kB and would
+    # make the error unreadable. The user's attrs still carry the full
+    # string so they can introspect it directly.
+    wkt_excerpt = crs_wkt_attr if len(crs_wkt_attr) <= 60 else (
+        crs_wkt_attr[:57] + '...'
+    )
+    raise ConflictingCRSError(
+        f"attrs['crs']={crs_attr!r} and attrs['crs_wkt']={wkt_excerpt!r} "
+        f"resolve to different CRSes after pyproj canonicalisation. The "
+        f"writer would silently pick attrs['crs'] and drop the WKT, so "
+        f"the on-disk CRS would not match what the DataArray advertises. "
+        f"Reconcile the two attrs (drop the stale one, or pass the "
+        f"intended CRS explicitly via the ``crs=`` kwarg, which overrides "
+        f"both attrs) and retry. See issue #1987."
+    )
+
+
+# Active by default: the conflicting-CRS write check is registered at
+# import time so every entry point that calls ``validate_write_metadata``
+# enforces the rule. Tests that need to scope around the check should
+# use ``unregister_write_metadata_check(_check_write_conflicting_crs)``
+# in a fixture rather than mutating the registry directly.
+register_write_metadata_check(_check_write_conflicting_crs)

xrspatial/geotiff/_writers/eager.py

@@ -44,6 +44,7 @@
     _validate_3d_writer_dims,
     _validate_nodata_arg,
     _validate_tile_size_arg,
+    validate_write_metadata,
 )
 from .._writer import write
 from .gpu import write_geotiff_gpu
@@ -270,6 +271,18 @@ def to_geotiff(data: xr.DataArray | np.ndarray,
 
     _validate_nodata_arg(nodata)
 
+    # Issue #1987 ambiguous-metadata checks. Today only the
+    # conflicting-crs/crs_wkt write check is registered; other cases
+    # land in follow-up PRs. The hook is a no-op when no check is
+    # registered, so this call is safe even if every check is later
+    # unregistered for a specific entry point.
+    _attrs = getattr(data, 'attrs', None) or {}
+    validate_write_metadata({
+        'crs_kwarg': crs,
+        'attrs_crs': _attrs.get('crs'),
+        'attrs_crs_wkt': _attrs.get('crs_wkt'),
+    })
+
     # Up-front validation: catch bad compression names before they reach
     # any of the deeper write paths (streaming, GPU, VRT, COG) where the
     # error surfaces from _compression_tag with a less obvious traceback.
@@ -785,6 +798,17 @@ def _write_vrt_tiled(data, vrt_path, *, crs=None, nodata=None,
     full array in RAM.
     """
     _validate_nodata_arg(nodata)
+
+    # Issue #1987 ambiguous-metadata checks; mirrors the call in
+    # ``to_geotiff`` so the dask-VRT write path enforces the same
+    # crs/crs_wkt consistency rule.
+    _attrs = getattr(data, 'attrs', None) or {}
+    validate_write_metadata({
+        'crs_kwarg': crs,
+        'attrs_crs': _attrs.get('crs'),
+        'attrs_crs_wkt': _attrs.get('crs_wkt'),
+    })
+
     # Validate compression_level against codec-specific range
     if compression_level is not None:
         level_range = _LEVEL_RANGES.get(compression.lower())

xrspatial/geotiff/_writers/gpu.py

@@ -29,6 +29,7 @@
     _validate_3d_writer_dims,
     _validate_nodata_arg,
     _validate_tile_size_arg,
+    validate_write_metadata,
 )
 
 
@@ -261,6 +262,15 @@ def write_geotiff_gpu(data: xr.DataArray | cupy.ndarray | np.ndarray,
     # keep parity with the public to_geotiff entry point.
     _validate_tile_size_arg(tile_size)
     _validate_nodata_arg(nodata)
+
+    # Issue #1987 ambiguous-metadata checks; mirrors ``to_geotiff`` so the
+    # GPU writer enforces the same crs/crs_wkt consistency rule.
+    _attrs = getattr(data, 'attrs', None) or {}
+    validate_write_metadata({
+        'crs_kwarg': crs,
+        'attrs_crs': _attrs.get('crs'),
+        'attrs_crs_wkt': _attrs.get('crs_wkt'),
+    })
     if max_z_error < 0:
         raise ValueError(
             f"max_z_error must be >= 0, got {max_z_error}")