test(gfql): pin #1767 cliff, LazyFrame/cudf AUTO routing, and pandas-oracle parity

- test_auto_engine_gfql_serves_polars_index_1767_cliff: polars frames +
  explicit gfql_index_all(engine='polars') + g.gfql() with NO engine now
  serves path=index on engine=polars per index_trace() -- the #1767
  engine-mismatch cliff can no longer regress silently.
- test_auto_engine_hop_residual_still_scans_1767: the documented scope
  boundary as executable documentation -- direct g.hop() with no engine
  still resolves AUTO to pandas and declines with decision_code
  engine_mismatch (hop/chain/index-build AUTO are follow-ups).
- TestAutoEngineLazyFrames: LazyFrame edges+nodes with engine unset route
  native and return EAGER polars equal to explicit engine='polars'.
- TestAutoEngineCudfUntouched: AUTO on cudf frames never enters the polars
  guard; legacy CUDF resolution unchanged (importorskip-gated).
- TestAutoEnginePandasOracleParity: AUTO-on-polars-frames answers equal the
  pandas-engine oracle in value for a filter+traverse, an aggregate, and a
  WHERE-bearing shape (normalized frame comparison).

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

Author: lmeyerov

graphistry/tests/compute/gfql/index/test_index.py

@@ -1399,3 +1399,65 @@ def test_engine_mismatch_reason_reports_all_undirected_indexes(
         "resident edge_out_adj, edge_in_adj index "
         f"engine={resident_engine}, requested engine={requested_engine} -> scan"
     ), reason
+
+
+# ---------------------------------------------------------------------------
+# 1743: engine=auto on polars-frame graphs routes to the native polars engine,
+# so a polars-engine index built explicitly is actually consulted through
+# g.gfql(...) with NO engine argument. Regression pin for the #1767 cliff:
+# before the AUTO route, resolve_engine(AUTO) mapped polars frames to pandas,
+# so the resident polars index was engine-mismatched and every query scanned.
+# ---------------------------------------------------------------------------
+
+def _polars_indexed_graph():
+    pl = pytest.importorskip("polars")
+    nodes = pd.DataFrame({
+        "id": np.arange(1, 13, dtype=np.int64),
+        "public": np.arange(100, 112, dtype=np.int64),
+    })
+    edges = pd.DataFrame({
+        "src": [1, 1, 1, 2, 2, 3, 4, 5, 6, 8],
+        "dst": [2, 2, 3, 4, 5, 5, 6, 6, 7, 1],
+        "type": ["A", "A", "A", "B", "B", "B", "C", "C", "D", "REV"],
+    })
+    g = graphistry.nodes(pl.from_pandas(nodes), "id").edges(
+        pl.from_pandas(edges), "src", "dst"
+    )
+    return g.gfql_index_all(engine="polars")
+
+
+def test_auto_engine_gfql_serves_polars_index_1767_cliff():
+    """#1767 cliff pin: polars frames + explicit polars index + gfql with NO engine
+    argument must serve path=index on engine=polars (AUTO routes native, so the
+    resident index is no longer engine-mismatched into a silent scan)."""
+    from graphistry.compute.gfql.index import index_trace
+
+    gi = _polars_indexed_graph()
+    q = ("MATCH (source {public:100})-[:A]->(destination) "
+         "RETURN destination.public AS destination ORDER BY destination")
+    with index_trace() as steps:
+        out = gi.gfql(q)  # no engine argument: default AUTO, default index policy
+    assert "polars" in type(out._nodes).__module__, "AUTO must answer in polars frames"
+    served = [s for s in steps if s.get("served") is True]
+    assert served, ("no index-served step; AUTO fell off the polars route", steps)
+    for s in served:
+        assert s.get("path") == "index", steps
+        assert s.get("engine") == "polars", steps
+    assert out._nodes["destination"].to_list() == [101, 102]
+
+
+def test_auto_engine_hop_residual_still_scans_1767():
+    """Documented residual (#1743 scope boundary, executable): direct g.hop() with no
+    engine on the same polars-frame graph still resolves AUTO to pandas, so the
+    resident polars index declines with an engine mismatch and the hop scans."""
+    from graphistry.compute.gfql.index import index_trace
+
+    gi = _polars_indexed_graph()
+    seeds = pd.DataFrame({"id": [1]})
+    with index_trace() as steps:
+        out = gi.hop(nodes=seeds, hops=1, direction="forward")  # no engine argument
+    assert "pandas" in type(out._nodes).__module__, "hop AUTO still bridges to pandas"
+    assert not any(s.get("path") == "index" for s in steps), steps
+    mismatch = [s for s in steps if s.get("decision_code") == "engine_mismatch"]
+    assert mismatch, ("expected an engine_mismatch decline", steps)
+    assert "requested engine=pandas" in mismatch[-1]["decision_reason"], steps

graphistry/tests/compute/gfql/test_engine_polars_cypher_conformance.py

@@ -602,3 +602,65 @@ def test_policy_hooks_fire_once_on_nie_shape(self):
         g.gfql(q, policy=pol)
         assert seen.count("precompile") == 1, seen
         assert seen.count("preload") == 1, seen
+
+
+class TestAutoEngineLazyFrames:
+    """LazyFrame is the other member of the PolarsFrame union `is_polars_df` admits, so
+    the AUTO route must take it too — and hand back EAGER polars, same as explicit
+    engine='polars' does."""
+
+    def test_lazyframe_auto_routes_native_and_matches_explicit(self):
+        nodes = pl.DataFrame({"id": [0, 1, 2, 3], "label__Person": [True] * 4}).lazy()
+        edges = pl.DataFrame({"s": [0, 1, 2], "d": [1, 2, 3], "type": ["KNOWS"] * 3}).lazy()
+        g = graphistry.nodes(nodes, "id").edges(edges, "s", "d")
+        q = "MATCH (a:Person {id: 0})-[:KNOWS]->(b) RETURN b.id AS bid ORDER BY bid"
+        r_auto = g.gfql(q)._nodes
+        r_expl = g.gfql(q, engine="polars")._nodes
+        assert isinstance(r_auto, pl.DataFrame), type(r_auto)  # eager out, not Lazy
+        assert isinstance(r_expl, pl.DataFrame), type(r_expl)
+        from polars.testing import assert_frame_equal
+        assert_frame_equal(r_auto, r_expl)
+        assert r_auto["bid"].to_list() == [1]
+
+
+class TestAutoEngineCudfUntouched:
+    """cuDF frames never enter the polars-AUTO guard (`is_polars_df` is a polars module
+    check), so the legacy AUTO->CUDF resolution is byte-for-byte what it was. Skips
+    without cudf/GPU; runs on GPU lanes."""
+
+    def test_auto_on_cudf_frames_stays_on_legacy_cudf_path(self):
+        cudf = pytest.importorskip("cudf")
+        nodes = cudf.DataFrame({"id": [0, 1, 2, 3], "label__Person": [True] * 4})
+        edges = cudf.DataFrame({"s": [0, 1, 2], "d": [1, 2, 3], "type": ["KNOWS"] * 3})
+        g = graphistry.nodes(nodes, "id").edges(edges, "s", "d")
+        out = g.gfql("MATCH (a:Person {id: 0})-[:KNOWS]->(b) RETURN b.id AS bid")._nodes
+        assert "cudf" in type(out).__module__, type(out)  # not polars, not pandas
+
+
+class TestAutoEnginePandasOracleParity:
+    """Routed AUTO answers must equal the pandas oracle in VALUE, not just shape: the
+    same query on pandas frames via engine='pandas' is the reference for each routed
+    query shape (filter+traverse, aggregate, WHERE-bearing)."""
+
+    ROUTED_SHAPES = [
+        # filter + traverse (connected join, multi-alias projection)
+        "MATCH (a {kind: 'alpha'})-[]->(b) RETURN a.id AS aid, b.id AS bid ORDER BY aid, bid",
+        # aggregate
+        "MATCH (n) RETURN n.kind AS kind, count(n) AS c ORDER BY kind",
+        # WHERE-bearing (predicate + arithmetic projection)
+        "MATCH (a)-[]->(b) WHERE b.val > 50 AND b.flag "
+        "RETURN b.id AS bid, b.val + b.score AS v ORDER BY bid, v",
+    ]
+
+    @pytest.mark.parametrize("query", ROUTED_SHAPES)
+    def test_auto_polars_matches_pandas_oracle(self, query):
+        g_pl = graphistry.nodes(pl.from_pandas(BASE._nodes), "id").edges(
+            pl.from_pandas(BASE._edges), "s", "d"
+        )
+        got = g_pl.gfql(query)._nodes  # AUTO: routes native polars
+        assert "polars" in type(got).__module__, "shape did not route; oracle test is vacuous"
+        oracle = BASE.gfql(query, engine="pandas")._nodes
+        a = _normalize_nulls(_round_floats(_to_pd(got).reset_index(drop=True)))
+        b = _normalize_nulls(_round_floats(oracle.reset_index(drop=True)))
+        assert list(a.columns) == list(b.columns), (list(a.columns), list(b.columns))
+        pd.testing.assert_frame_equal(a.astype(str), b.astype(str), check_dtype=False)