zonal: guard unbounded allocation in stats(return_type='xarray.DataArray') (#2523)

[brendancol]

Summary

• _stats_numpy xarray.DataArray return path allocated np.full((n_stats, values.size), nan) (float64) with no memory check; n_stats is user-controlled via stats_funcs and values.size scales with the input raster.
• Added _check_stats_dataarray_memory(n_stats, values_shape) that reuses the existing _available_memory_bytes() helper and raises MemoryError before the allocation when the buffer would exceed 50% of available RAM.
• Follows the same pattern as the unbounded-allocation guards in cost_distance (cost_distance: missing memory guard on CuPy backend #1262), kde (kde: unbounded width/height allocation in numpy and cupy backends #1287), mahalanobis (mahalanobis: unbounded float64 allocations on numpy and cupy backends #1288), multispectral (true_color allocates ~17 bytes/pixel of working memory with no guard #1291), resample (Guard resample() against unbounded scale_factor / target_resolution #1295), sieve (sieve(): numpy and cupy backends have no memory guard #1296), etc.

Closes #2523. Found by deep-sweep-security-zonal-2026-05-27.

Test plan

• New unit test test_stats_dataarray_return_type_memory_guard_2523 mocks _available_memory_bytes and asserts both the guard fires and the normal path still produces a correct xr.DataArray
• Full xrspatial/tests/test_zonal.py suite passes (126 tests)

[brendancol]

PR Review: zonal: guard unbounded allocation in stats(return_type='xarray.DataArray')

Blockers

None.

Suggestions

None.

Nits

• xrspatial/zonal.py:2025-2027: n_cells = 1; for s in values_shape: n_cells *= int(s) works fine, but int(np.prod(values_shape)) would match the style of _regions_dask (line 2047). Cosmetic.

What looks good

• Guard runs before the np.full(...) call on line 506, so it fires before the allocation, not after.
• Reuses the existing _available_memory_bytes() helper and the required > 0.5 * available threshold. Matches sieve.py, mahalanobis.py, dasymetric.py, and _regions_dask.
• Error message names the call site (stats(return_type='xarray.DataArray')), reports required vs available GB, and lists three concrete mitigations: reduce stats_funcs, use a smaller raster, or switch to return_type='pandas.DataFrame'.
• Regression test mocks _available_memory_bytes to a 100-byte budget, asserts the guard fires, and verifies the normal path still produces a correct xr.DataArray.
• Other backends do not hit this code path. _stats_cupy and the dask backends always return a DataFrame, and the top-level stats() only assembles the xarray result after the numpy backend has returned the (n_stats, H, W) ndarray, so the guard sits in the right place.
• Sweep state CSV updated.

Checklist

• Guard fires before the allocation
• Error message is specific and actionable
• Threshold pattern matches sibling modules (cost_distance, kde, mahalanobis, dasymetric, sieve)
• Regression test with synthetic limit
• pytest xrspatial/tests/test_zonal.py -x -q passes (126/126)