IO Support Matrix

Intent

Define which formats are GPU-native targets, which are acceptable hybrid paths, and which remain explicit fallback adapters.

Request Signals

• io support matrix

• format classification

• gpu native format

• hybrid path

• fallback format

Open First

• docs/architecture/io-support-matrix.md

• docs/architecture/io-arrow.md

• docs/architecture/io-files.md

Verify

• uv run python scripts/check_docs.py --check

Risks

• Compatibility formats becoming the design center instead of GeoArrow and GeoParquet.

• Missing explicit fallback events on legacy GDAL formats hides work that bypasses the GPU stack.

Decision

• GeoArrow is the canonical GPU-native interchange format.

• GeoParquet is the canonical GPU-native persisted format.

• WKB is a hybrid compatibility bridge.

• GeoJSON and Shapefile are explicit hybrid pipelines.

• Untargeted GDAL formats remain fallback-only until justified.

Matrix

Format	Default Path	Read	Write	GPU Canonical
GeoArrow	GPU-native	GPU-native	GPU-native	yes
GeoParquet	GPU-native	GPU-native	hybrid	yes
WKB	hybrid	hybrid	hybrid	no
GeoJSON	hybrid	GPU geometry + CPU properties	hybrid	no (geometry GPU-accelerated)
Shapefile	hybrid	hybrid	hybrid	no
GDAL legacy	fallback	fallback	fallback	no

Performance Notes

• Most serious IO throughput work should center on GeoArrow and GeoParquet.

• Compatibility formats must not become the design center.

• Hybrid paths are acceptable when transport or container parsing is host-heavy but geometry decode, filtering, or encode can still move toward GPU stages.