fix(gfql): explicit polars-gpu runs the Cypher OLAP fast paths on GPU or raises - #1979

Fixes #1824

The rule being implemented

Owner ruling: auto may switch modes; an explicit engine selection may not. An explicitly requested engine either runs as requested or raises — it is never silently run somewhere else and reported as the requested engine.

What was broken (verified on current master, af494becc)

The issue's line references have moved. Re-read against master:

So the collect-routing half of #1824 had landed — but gfql.lazy.collect picks its engine from active_target(), and the fast-path routes never set that target to GPU:

• gfql_unified.py:1373 was a function named _fast_path_execution_target_ignoring_requested_engine that returned ExecutionTarget.CPU unconditionally ("Not GPU until every fast-path arm is GPU-or-decline");
• _apply_connected_match_join's two-star arms (_connected_join_two_star_fast_grouped_count, _connected_join_two_star_fast_rows, and the fused lane behind them) were a second call site that was never wrapped in a target at all.

Result: every fast-path-served OLAP shape collected on CPU polars while the caller had asked for — and any benchmark would label — GPU.

AUTO can now reach POLARS_GPU — the issue's premise is partially refuted

Engine.py:34 still says "Explicit opt-in only — AUTO never selects it", and resolve_engine never returns POLARS_GPU for AUTO. But gfql_unified.py:2298/2323/2426 (the owner-directed cuDF arm, 2026-08-02) re-enters gfql() with engine=_AUTO_CUDF_ROUTE_ENGINE == 'polars-gpu' when every bound frame is cuDF and the GPU target probes usable. So a resolved POLARS_GPU no longer proves the user typed it.

Testing the resolved engine is still exactly right, and still exactly the owner's rule: that arm wraps its recursion in except NotImplementedError -> legacy CUDF path, so the mode switch happens in the AUTO layer (allowed) while the inner run stays GPU-or-raise (required). Values are unchanged either way — see the evidence below.

The fix

One shared seam rather than per-site edits, so the ~5 lazy collect sites cannot drift apart:

• _fast_path_execution_target(engine) — GPU iff the requested engine is polars-gpu, CPU otherwise.
• _run_fast_path_on_requested_target(engine, run) — runs a fast-path arm under that target and returns (result, reason). On the GPU target a non-GPU-executable plan surfaces as NotImplementedError (via lazy._gpu_raise) and becomes a decline, so the generic route — itself GPU-or-raise — answers. On the CPU target an NIE stays a real error.

Both call sites now go through it: _try_fast (same_path / row_pipeline arms) and _apply_connected_match_join's two two-star arms.

Evidence

Measured on a real GPU (RTX 3080 Ti, cudf 25.10, cudf-polars-cu12 25.10 + polars 1.32.3), on the fused two-star lane — the graph-benchmark q7 anatomy:

Values identical in every cell.

Red at merge-base: the new pins were re-run at af494becc with one shim line (_fast_path_execution_target = _fast_path_execution_target_ignoring_requested_engine) and everything else byte-identical — 9 failed / 26 passed with the GPU stack, 8 failed / 26 passed / 1 skipped on a CPU-only box (the real-GPU pin skips). Green here: 35 passed (GPU), 34 passed + 1 skipped (CPU-only).

Per-site mutation (all non-vacuous): target decision forced back to CPU -> 9 red; _try_fast site unwrapped -> 2 red; connected-join grouped-count arm unwrapped -> 3 red; connected-join rows arm unwrapped -> 2 red.

Failure-set comparison: bin/test-polars.sh (serial) at merge-base and at this head, same box, same env — identical failure SETS in both directions (5 pre-existing, unrelated: 3 cuDF degree-consult, 1 viz categorical, 1 dask coercion). 7304 passed here vs 7286 at master (the delta is the new pins).

polars / auto unchanged: covered by the identical failure sets above; by the CPU-target and NIE-is-a-real-error pins parametrized over polars and auto; and by an explicit A/B of engine='auto' on a cuDF graph (the arm that routes through POLARS_GPU) against cudf and pandas — byte-identical results at master and at this head.

bin/ci_comment_density_guard.py, bin/lint.sh, bin/typecheck.sh all rc=0. Correctness only; no performance measurements were run. Expect polars-gpu to get slower on these shapes — the old numbers were CPU numbers wearing a GPU label.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AjbKuKheqDu78oapRT5AYm