test(gfql): classify engine availability instead of swallowing every failure

The first version of this file's engine probe wrapped a smoke query in a bare
`except Exception: return False`. Two things went wrong with that, both found by
trying rather than by argument (on the sibling #1788/#1790 parametrization):

  * a probe that runs THE SHAPE UNDER TEST disarms its own file — reverting a
    production guard made the probe raise and every parameter reported SKIPPED
    instead of failing;
  * a probe that swallows EVERYTHING is worse — a transient
    `MemoryError: ... cudaErrorMemoryAllocation` in a fresh GPU container
    silently dropped cuDF from a run that otherwise passed, and a skipped GPU
    parameter reads as evidence of passing.

So the check now CLASSIFIES: a missing module skips, a recognisable GPU-stack
error skips WITH ITS TEXT QUOTED in the reason, and any other failure
propagates. The smoke query stays a plain traversal, never the shape under test.

GPU receipts — dgx GB10, `graphistry/test-rapids-official:26.02-gfql-polars`,
`docker run --gpus all`, cuDF 26.02.01 / polars 1.35.2: 43 passed, 0 skipped
(this file plus the #1793 suite), repeated.

The marker list is duplicated from the copy landing in `polars_test_utils.py`
alongside the #1788/#1790 parametrization; collapse to one definition once both
land. Kept duplicated for now so the two PRs stay independently mergeable.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015YsqAZQLbqjSDrYSFz2GoB

Author: lmeyerov

CHANGELOG.md

@@ -24,7 +24,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - **Seeded typed-hop property projection keeps its fast path through DISTINCT / ORDER BY / SKIP / LIMIT**: those trailing row ops are plain frame operations, so the fast path now delegates them to the canonical chain instead of declining the whole query.
 
 ### Changed
-- **Row execution context: `clear_row_exec_context` NULLs rather than restores, and that is now pinned rather than assumed** (tests + comments only; zero runtime delta — no production line changed). Review of #1793 asked whether the exit should RESTORE what the graph carried on entry instead of nulling, since `attach_row_exec_context` INHERITS on the way in (a `None` argument keeps what `g` already carries). Settled as NULL, for three reasons now each carried by a test: (1) `clear` is pure — it returns `g.bind()` and never writes through to the object it was handed, so an outer scope that set the field still has it afterwards and there is no caller state to save; that is what separates this from #1786, which WAS an in-place write onto the caller's own graph, and restore is the fix for a mutation. (2) The only channel restore would change is the RETURN value, and putting the seed back there IS the second half of #1786 — measured, a seed hand-restored onto a result changes the answer of the next query run on that result (7 → 2 → 1 rows). (3) No execution frame inherits a context it did not set: instrumenting `attach` over `graphistry/tests/compute` recorded 3907 calls and zero inheriting ones (53 entered on a graph already carrying a seed, but each was handed the identical `start_nodes` parameter, so the frame still owns the value), because the cross-segment `WITH` seed travels as the explicit `start_nodes` PARAMETER and never through the graph field. The new `test_exec_context_scoping.py` re-runs that ownership measurement as an assertion, so a future path that starts relying on inheritance reopens the decision loudly instead of silently losing an outer value. Mutation-checked in the deciding direction: implementing save/restore at all three attach sites fails 4 of the new tests on every runnable engine, while the existing #1793 suite passes unchanged — i.e. those tests could not distinguish the two designs and this file can.
+- **Row execution context: `clear_row_exec_context` NULLs rather than restores, and that is now pinned rather than assumed** (tests + comments only; zero runtime delta — no production line changed). Review of #1793 asked whether the exit should RESTORE what the graph carried on entry instead of nulling, since `attach_row_exec_context` INHERITS on the way in (a `None` argument keeps what `g` already carries). Settled as NULL, for three reasons now each carried by a test: (1) `clear` is pure — it returns `g.bind()` and never writes through to the object it was handed, so an outer scope that set the field still has it afterwards and there is no caller state to save; that is what separates this from #1786, which WAS an in-place write onto the caller's own graph, and restore is the fix for a mutation. (2) The only channel restore would change is the RETURN value, and putting the seed back there IS the second half of #1786 — measured, a seed hand-restored onto a result changes the answer of the next query run on that result (7 → 2 → 1 rows). (3) No execution frame inherits a context it did not set: instrumenting `attach` over `graphistry/tests/compute` recorded 3907 calls and zero inheriting ones (53 entered on a graph already carrying a seed, but each was handed the identical `start_nodes` parameter, so the frame still owns the value), because the cross-segment `WITH` seed travels as the explicit `start_nodes` PARAMETER and never through the graph field. The new `test_exec_context_scoping.py` re-runs that ownership measurement as an assertion, so a future path that starts relying on inheritance reopens the decision loudly instead of silently losing an outer value. Mutation-checked in the deciding direction: implementing save/restore at all three attach sites fails 4 of the new tests on every runnable engine, while the existing #1793 suite passes unchanged — i.e. those tests could not distinguish the two designs and this file can. Engine-parametrized over pandas/cuDF/polars/polars-gpu from a fixed list plus a classified availability check (a missing module skips, a recognisable GPU-stack error skips with its text quoted, and any other failure propagates — a silently skipped GPU parameter reads as evidence of passing); GPU receipts on dgx GB10 / cuDF 26.02.01 / `docker run --gpus all`: 43 passed, 0 skipped.
 - **`is_lazy` is a type predicate, so the polars engine's eager/lazy split is checked instead of asserted**: `dtypes.is_lazy` decides WHICH member of the two-member `PolarsFrame` union a frame is, but it was declared `-> bool`, so that answer was discarded at the call boundary — an eager-only attribute (`.height`, `.columns`, `.schema`) reached after a lazy guard was unprovable, and the native polars chain closed the gap with `cast("pl.DataFrame", frame)`. A cast is not a type: it re-asserts, unchecked, the exact fact the predicate had just established, once per call site, and a wrong one surfaces as a production `AttributeError` rather than a CI error. `is_lazy` is now declared `-> TypeIs["pl.LazyFrame"]` (PEP 742), which narrows the *negative* branch as well as the positive — the eager side is the one that needed it, so `TypeGuard` would not have done — and the cast is gone. Four previously untyped chain-combine helpers (`_semi`, `_combine_edges`, `_apply_node_names`, and the `_known_empty` guard) now carry real signatures: `_semi`'s two frames share the `PolarsT` TypeVar because polars joins do not mix eagerness, and the two combine helpers take the `_LazyShim` collect-once duck-type they are actually called with. Typing `_apply_node_names` also retired a `getattr(next_step, "edges_empty", None)` — the shim declares that tri-state in `__slots__`, so a typo is now a checker error instead of a silent `None` that would have re-armed the very cardinality gate the guard disarms. Internal only: no runtime behaviour, no public API, and the `TypeIs` import is `TYPE_CHECKING`-only, so no new runtime dependency floor.
 - **GFQL execution context is declared rather than attached at runtime**: the private `_gfql_*` per-execution fields (index policy and registry, row-pipeline base graph, carried seed nodes, edge aliases, shortest-path backend, and the indexed-bindings handoff) are now declared on `Plottable` with defaults on `PlotterBase`, instead of being set with `setattr` and read back with `getattr(..., default)`. No public API or behaviour change; internal call sites are typed, and hand-rolled `Plottable` stand-ins must now construct the full context.
 

graphistry/tests/compute/gfql/test_exec_context_scoping.py

@@ -38,15 +38,18 @@
 plumbing, but the shapes below are exercised on all four engines because the two attach/clear
 pairs are duplicated across the generic chain and the native polars chain. No CI lane runs cuDF
 or polars-gpu (``ci-gpu.yml`` is hard-disabled and does not install the ``polars`` extra), so
-those two parameters report SKIPPED on CI — visibly, via a runtime probe, never as a silent
-pass. They are exercised out of band on the dgx GPU box against
+those two parameters report SKIPPED on CI — visibly, with the reason quoted, never as a silent
+pass. The availability check CLASSIFIES rather than swallows: a missing module skips, a
+recognisable GPU-stack error skips with its text quoted, and any other failure propagates,
+because a silently skipped GPU parameter reads as evidence of passing. They are exercised out
+of band on the dgx GPU box against
 ``graphistry/test-rapids-official:26.02-gfql-polars`` (``docker run --gpus all`` — omitting
 ``--gpus all`` FABRICATES failures rather than skipping).
 """
 from __future__ import annotations
 
 from functools import lru_cache
-from typing import Any, List, Tuple
+from typing import Any, List, Optional, Tuple
 
 import pandas as pd
 import pytest
@@ -101,26 +104,61 @@ def _seed(engine: str) -> Any:
     return _frame(engine, pd.DataFrame({"id": [0]}))
 
 
-@lru_cache(maxsize=None)
-def _engine_runnable(engine: str) -> bool:
-    """Probe by RUNNING the smallest version of what these tests do.
+#: Substrings that identify a broken/absent GPU STACK rather than a product defect. Matched
+#: against ``type(ex).__name__: str(ex)``, lowercased. Deliberately narrow — anything not
+#: listed is treated as a REAL failure, because guessing wrong in that direction produces a
+#: silently green GPU lane. (Duplicated from the copy landing in `polars_test_utils.py`
+#: alongside the #1788/#1790 engine parametrization; collapse to one definition once both land.)
+_GPU_ENVIRONMENT_MARKERS = (
+    "libnvrtc", "libcuda", "libcudart", "nvrtc", "cuinit",
+    "no cuda-capable device", "cuda driver", "cuda runtime",
+    "cuda_error", "cudaerror", "driver version",
+    "gpu engine requested",  # polars' own message when cudf_polars is absent
+)
+
 
-    Cheaper probes do not discriminate on a box with cudf/cudf_polars importable but no working
-    CUDA runtime — frame construction and simple ops all succeed there and the suite then dies
-    inside the first real kernel. So the probe is an actual boundary-call run.
+@lru_cache(maxsize=None)
+def _engine_skip_reason(engine: str) -> Optional[str]:
+    """``None`` => this engine MUST run here; a string => a stated, checkable skip reason.
+
+    Two traps, both established by trying rather than by argument:
+
+    * An IMPORT-only check does not discriminate on a box where cudf / cudf_polars import
+      against an incomplete CUDA runtime — construction and simple ops succeed and the suite
+      then dies inside the first real kernel, which reads as a product failure. So a smoke
+      QUERY runs.
+    * A check that SWALLOWS every exception is worse. A transient `cudaErrorMemoryAllocation`
+      in a fresh GPU container silently dropped cuDF from an otherwise-green run, and a
+      skipped GPU parameter reads as evidence of passing. So: a missing module skips, a
+      recognisable GPU-stack error skips WITH ITS TEXT QUOTED, and anything else propagates.
+
+    The smoke query is a plain traversal, never the shape under test — a check that ran the
+    asserted shape would let a regression disarm its own test.
     """
+    import importlib.util
+
+    for module in {"polars": ("polars",), "polars-gpu": ("polars", "cudf_polars"),
+                   "cudf": ("cudf",)}.get(engine, ()):
+        if importlib.util.find_spec(module) is None:
+            return f"{module} is not installed"
     try:
-        _graph(engine).gfql(list(BOUNDARY_OPS), engine=engine)
-        return True
-    except Exception:  # noqa: BLE001 — any failure means "cannot run", never "test fails"
-        return False
+        _graph(engine).gfql([n(), e_forward(), n()], engine=engine)
+    except BaseException as ex:  # noqa: BLE001 — classified below, never blanket-swallowed
+        if isinstance(ex, ImportError):
+            return f"{type(ex).__name__}: {ex}"
+        text = f"{type(ex).__name__}: {ex}".lower()
+        if any(marker in text for marker in _GPU_ENVIRONMENT_MARKERS):
+            return f"{type(ex).__name__}: {ex}"
+        raise
+    return None
 
 
 def _require(engine: str) -> None:
-    if not _engine_runnable(engine):
+    reason = _engine_skip_reason(engine)
+    if reason is not None:
         pytest.skip(
-            f"engine {engine!r} is not runnable in this environment — NOT evidence that it "
-            "passes; see the COVERAGE BOUNDARY note in this module's docstring"
+            f"engine {engine!r} unavailable here ({reason}) — NOT evidence that it passes; "
+            "see the COVERAGE BOUNDARY note in this module's docstring"
         )