polygonize: add return type annotation (#2148)

[brendancol]

Summary

• Add a Union return annotation to polygonize() covering all five return_type modes (numpy tuple, awkward tuple, geopandas GeoDataFrame, spatialpandas GeoDataFrame, geojson dict). Optional-dependency types live under TYPE_CHECKING and are referenced as forward strings, so importing xrspatial.polygonize still works without geopandas/spatialpandas/awkward installed.
• Expand the docstring Returns section to spell out each per-return_type shape instead of the previous one-line "in a format determined by return_type" deferral.
• Update .claude/sweep-api-consistency-state.csv with the 2026-05-19 polygonize pass record.

Closes #2148.

Why

polygonize was the only public vector/raster conversion function in xrspatial without a return type annotation. Siblings sieve, contours, rasterize, clip_polygon all declare one. Static type checkers, IDE hover help, and Sphinx autodoc all saw polygonize(...) with an unspecified return type while the docstring documented the per-mode shapes.

Found by /sweep-api-consistency 2026-05-19.

Out of scope (documented in sweep state)

• HIGH cross-module rename: polygonize uses connectivity (int 4|8) while sieve uses neighborhood (int 4|8) for the identical rook/queen pixel-connectivity concept. Industry convention (GDAL, rasterio.features.sieve) favours connectivity; the deprecation shim belongs in sieve.py, not in polygonize, so it is out of scope for this polygonize-scoped sweep branch.
• LOW cross-cutting: raster (polygonize/sieve/clip_polygon) vs agg (contours and many older modules) for the input DataArray. Library-wide drift, not filed per-module per sweep template.

Test plan

• pytest xrspatial/tests/test_polygonize.py -x -q -> 114 passed, 13 skipped (unchanged)
• inspect.signature(polygonize).return_annotation resolves to the expected Union
• Runtime smoke test: numpy + cupy paths still return the documented shapes for all five return_type modes
• No optional dependency now required at import time (TYPE_CHECKING guards)