Explicit Fallback Surfaces

Request Signals

  • fallback

  • cpu fallback

  • unsupported predicate

  • unsupported geometry mix

  • diagnostics

  • runtime visibility

Open First

  • docs/architecture/fallbacks.md

  • docs/architecture/runtime.md

  • src/vibespatial/runtime/fallbacks.py

  • src/vibespatial/predicates/binary.py

  • src/vibespatial/spatial/query.py

Verify

  • uv run pytest tests/test_geopandas_fallbacks.py

  • uv run pytest tests/upstream/geopandas/tests/test_sindex.py -q

  • uv run pytest tests/upstream/geopandas/tests/test_array.py -k "contains or within or intersects"

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

Risks

  • Silent host execution makes it impossible to tell whether a GPU path exists.

  • Warning-based fallback can pollute upstream behavior if used as the only visibility channel.

  • Fallback logs are not useful if they omit the surface and the reason.

Intent

Make host-only predicate and spatial-query execution observable without changing GeoPandas-compatible behavior.

Decision

Use a lightweight fallback-event log instead of warnings as the primary observability channel.

Current policy:

  • fallback surfaces record surface, requested, selected, reason, and detail

  • the GeoPandas shim exposes get_fallback_events() and clear_fallback_events()

  • explicit gpu requests in repo-owned kernels still fail loudly

  • auto / GeoPandas-facing host paths record fallback events whenever they stay on CPU because the GPU path is unavailable or unsupported

Current Surfaces

Fallback events are currently recorded for:

  • GeoPandas-facing binary predicates routed through array.GeometryArray._binary_method

  • sindex.query

  • sindex.nearest

  • distance_owned – element-wise distance GPU-to-CPU fallback

  • geometry_array_dwithin – dwithin GPU-to-CPU fallback

Observability Contract

Fallback visibility must be:

  • machine-readable in code

  • narrow enough for repo-local tests

  • quiet enough to avoid changing upstream warning behavior

That is why the event log is preferred over unconditional warnings.

Consequences

  • unsupported GPU paths are now observable in code without changing result semantics

  • repo-local tests can assert fallback behavior directly

  • later GPU rollouts can shrink fallback-event volume surface by surface instead of relying on manual inspection