Make VRT tiled writes atomic to avoid poisoned partial output (#2669)

[brendancol]

Closes #2669

What changed

• _write_vrt_tiled now stages tiles in a temp directory and renames it into place atomically once every tile is written. On any failure during tile writing the staging dir is removed, so the final *_tiles directory is never created and a retry starts from a clean slate. Before this, a failed write left a partial *_tiles directory behind, and the next attempt hit the "directory already contains files" guard and failed immediately.
• On the dask streaming path, each tile task's outcome is captured rather than letting dask.compute abort on the first error while sibling threads are still writing into the staging dir. The first failure is re-raised after all writes settle, so cleanup no longer races in-flight worker threads.

Backend coverage

• numpy and cupy (eager): covered, transactional staging + rename.
• dask+numpy and dask+cupy (streaming): covered, with the settle-before-cleanup barrier.

Test plan

• Successful tiled .vrt write produces the tile directory plus a readable VRT.
• A numpy write that fails partway leaves no *_tiles dir, no .vrt, no staging dir, and a retry succeeds.
• A dask write that fails partway cleans up the same way and retries (ran 5x for the threaded race).
• Full geotiff suite passes (6025 passed, 81 skipped).

[brendancol]

PR Review: Make VRT tiled writes atomic to avoid poisoned partial output (#2669)

Blockers (must fix before merge)

None.

Suggestions (should fix, not blocking)

• xrspatial/geotiff/_writers/eager.py:1436 -- os.replace(staging_dir, tiles_dir) onto a pre-existing empty tiles_dir is not portable. The old code called os.makedirs(tiles_dir, exist_ok=True), so a pre-existing empty tiles dir was tolerated and reused. On POSIX, os.replace over an empty target dir works, but on Windows replacing an existing directory raises even when it is empty. The leftover-state guard at line 1185 only rejects a non-empty tiles dir, so an empty one slips through to the rename. Suggest removing an empty pre-existing tiles_dir (os.rmdir) just before the replace, or documenting POSIX-only support for that edge case.

Nits (optional improvements)

• xrspatial/geotiff/_writers/eager.py:1424 -- raise r re-raises the captured exception but rebinds the traceback to this line. The original tile-write traceback is preserved on r, so this is acceptable; just noting the stack will point at the barrier rather than the failing tile.

What looks good

• Staging-dir-plus-atomic-rename is the right shape for the fix, and the same-parent-dir placement keeps the rename atomic.
• The dask race was caught and handled correctly: capturing each task outcome so dask.compute runs every task to completion before re-raising means cleanup no longer races in-flight writer threads. The test runs this path repeatedly to flush out the race.
• Tests cover the three real paths: clean write, numpy mid-write failure with retry, dask mid-write failure with retry. They assert no staging dir, no tiles dir, and no VRT remain after failure, and that a retry succeeds.
• Temp filenames carry the issue number, per project convention.
• The leftover-state guard comment now explains why a retry after failure is no longer blocked.

Checklist

• Algorithm matches reference/paper: n/a (IO transaction fix)
• All implemented backends produce consistent results: yes (numpy/cupy eager, dask streaming)
• NaN handling is correct: unchanged by this PR
• Edge cases covered by tests: failure-and-retry covered; pre-existing empty tiles dir not covered
• Dask chunk boundaries handled correctly: unchanged; tile grid still from chunks
• No premature materialization or unnecessary copies: yes
• Benchmark exists or not needed: not needed (no perf-path change beyond the existing threaded compute)
• README feature matrix updated: n/a (no new public API)
• Docstrings present and accurate: yes

[brendancol]

Follow-up review (after commit 9c5deaa)

Disposition of prior findings

• Suggestion (eager.py rename): fixed. The rename now drops a pre-existing empty tiles_dir with os.rmdir before os.replace, so promotion works on Windows too. A test covers the empty-dir reuse case (test_preexisting_empty_tiles_dir_is_reused).
• Nit (raise r traceback): dismissed. raise r re-raises the captured exception with its original __traceback__ intact, so the failing tile's stack is preserved; no change needed.

Remaining

No blockers, suggestions, or nits. The write/vrt suites pass (1517 passed, 1 skipped).