geotiff: `gpu` keyword has three incompatible value spaces across the public API

[brendancol]

Summary

The gpu keyword argument on the public xrspatial.geotiff reader/writer functions accepts three different value spaces depending on which function you call:

• open_geotiff(..., gpu=False) — bool. Truthy routes to read_geotiff_gpu.
• read_vrt(..., gpu=False) — bool. Truthy uploads to CuPy.
• to_geotiff(..., gpu=None) — bool | None. None auto-detects from the input, truthy forces GPU.
• read_geotiff_gpu(..., gpu='auto') — str literal, accepts only 'auto' or 'strict'. Controls failure mode when a GPU decode stage raises.

The read_geotiff_gpu case is the one that bites users: the name gpu= reads like "use GPU", but the values actually control the strict-vs-fallback policy when the GPU path itself fails. Calling read_geotiff_gpu(path, gpu=True) — the obvious mental model after using open_geotiff(path, gpu=True) — raises ValueError: gpu must be 'auto' or 'strict', got True.

Why this matters

Anyone who learns the API from open_geotiff and then drops down to the explicit read_geotiff_gpu for stricter semantics gets the ValueError on the first call. The kwarg shares a name across four public functions but carries three different meanings.

Proposed fix

Rename the read_geotiff_gpu parameter to something that describes what it actually controls — for example on_gpu_failure='auto' or gpu_failure='auto'. Add a deprecation shim that:

1. Accepts both gpu= (old) and the new name.
2. Raises TypeError if both are passed.
3. Emits DeprecationWarning if only gpu= is passed, then forwards.
4. Updates the docstring and tests.

This is a breaking-change-with-shim path; the rename has to land with the deprecation in the same release.

Found during the geotiff API consistency sweep (Cat 1, HIGH).