fix(gfql): IS5 projection slice — pivot dtype parity, empty edges frame, engine-mismatch decline

Review-skill findings (plans/review-pr-1766/review.md):
B1 int/bool property dtypes diverged from the full pandas path (rows-pivot
upcasts non-id int/float->float64, bool->object; id keeps dtype). The lean
tail now applies the same casts; unverified dtype classes (datetimes,
extension dtypes, categoricals) decline to the full path.
M1 res._edges was None where the full path yields an empty edges frame;
now the helper edges' zero-row head.
M2 requested-vs-actual engine mismatch (e.g. polars frames + engine=
'pandas') declines — the full path converts to the requested engine.
M3 CHANGELOG corrected to the measured 116.3->38.3ms (was 'low
single-digit ms').

Pinned in TestSeededProjectionDtypeAndEdgesParity (dtype parity pandas+
polars, datetime decline, edges empty-not-None, both mismatch directions),
all engagement-asserted. 14-case fast-vs-full probe matrix: exact parity.

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

Author: lmeyerov

CHANGELOG.md

@@ -9,7 +9,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 <!-- Do Not Erase This Section - Used for tracking unreleased changes -->
 
 ### Performance
-- **GFQL seeded fast path covers single-alias property RETURNs (LDBC IS5 shape) (#1755)**: `MATCH (m {id})-[:T]->(p) RETURN p.a AS x, p.b` — which lowers to `rows(source=p)+select(items)` rather than a whole-row projection — now takes the seeded typed-hop fast path: the deduped destination rows are renamed/selected directly (value-identical to the rows-pivot + select pipeline; row order may differ). Conservative declines keep full-path semantics for everything else: cross-alias refs (`RETURN m.x, p.y`), mixed whole-row+property, DISTINCT/ORDER BY/LIMIT (extra lowered ops), expr items, and properties absent from the node frame (the full path's null/error semantics must apply). Differential fast-vs-full sweep across all of the above on pandas + polars: exact parity, engagement pinned both ways. Measured on LDBC SNB SF1 (dgx): `message-creator` (IS5) drops from 116 ms to low single-digit ms on polars.
+- **GFQL seeded fast path covers single-alias property RETURNs (LDBC IS5 shape) (#1755)**: `MATCH (m {id})-[:T]->(p) RETURN p.a AS x, p.b` — which lowers to `rows(source=p)+select(items)` rather than a whole-row projection — now takes the seeded typed-hop fast path: the deduped destination rows are renamed/selected directly (value-identical to the rows-pivot + select pipeline; row order may differ). Dtype parity with the full pandas path is exact: non-id properties ride the rows-pivot there, which upcasts int/float to float64 and bool to object, so the lean tail applies the same casts (the id property keeps its dtype); dtype classes not verified against the pivot (datetimes, pandas extension dtypes, categoricals) decline. `res._edges` is the same empty edges frame the full path yields (never None). Conservative declines keep full-path semantics for everything else: cross-alias refs (`RETURN m.x, p.y`), mixed whole-row+property, DISTINCT/ORDER BY/LIMIT (extra lowered ops), expr items, properties absent from the node frame (the full path's null/error semantics must apply), and requested-vs-actual engine mismatches (the full path converts to the requested engine). Differential fast-vs-full sweep across all of the above on pandas + polars: exact parity incl. dtypes and edges, engagement pinned both ways. Measured on LDBC SNB SF1 (dgx, harness row-validated): `message-creator` (IS5) 116.3→38.3 ms on polars (the residue is the seed scan, targeted separately by resident-index coverage).
 - **GFQL seeded typed-hop fast path (#1755)**: a seeded typed 1-hop — native chain `[n({id}), e_forward(), n({type})]` or Cypher `MATCH (m {id})-[:T]->(p) RETURN p` — previously paid the full two-pass chain machinery (~20-40ms: whole-frame combines, full-column type filters, rows-pivot projection). A new seed-first fast path recognizes exactly this shape and reduces the graph to the seed's 1-hop neighborhood before any of that work: native chain 32.6→0.93ms (35×), Cypher RETURN 39.2→1.9ms (20×) on pandas, with cuDF covered via the shared DataFrame API (30.8→4.7ms). Value-identical to the full path by construction (same rows/columns/dtypes; row order and index may differ) — the helpers return `None` and fall through for anything outside the exact shape or carrying full-path side-channels (multi-hop, variable-length, undirected, predicate filters, reverse patterns, missing bindings, list-`labels` columns, policy hooks, same-path WHERE, OPTIONAL MATCH null rows, and WITH..MATCH carried seeds all decline). Null ids/endpoints never link (membership sets are null-dropped, matching the full pipeline's joins). Verified with an independent oracle (results checked against the creator set hand-computed from the raw frames, not merely fast-vs-slow agreement) plus a differential fast-vs-full sweep across shapes × engines in `test_seeded_typed_hop_fastpath.py`.
 - **GFQL seeded typed-hop fast path on polars/polars-gpu (#1755)**: extends the seeded typed-hop Cypher fast path to the polars engines via native polars filters (`_seeded_typed_return_dst_polars`), so a seeded typed 1-hop RETURN also lands in single-digit ms on polars (13.7→3.4ms, 4×) and polars-gpu (24.6→2.5ms, 10×). Dispatch is on the ACTUAL frame type (`is_polars_df`), not the requested engine, because WITH..MATCH reentry can request polars while handing pandas-materialized frames. Same decline contract as the pandas path (undirected/multi-hop/varlen/predicates fall through; value-identical for the covered shape), verified by the per-engine differential sweep and oracle tests in `test_seeded_typed_hop_fastpath.py`.
 - **GFQL connected-join simple residuals filter natively on polars (#1729/#1755)**: on the polars engines, a connected-join node residual of the #1729 scalar shapes — case-insensitive equality ``(tolower(a.col) = tolower('lit'))`` and scalar comparisons ``(a.col <op> literal)`` for ``= >= <= > <`` — previously dispatched a full sub-``chain()`` per alias (the polars row pipeline has no native ``where_rows``), costing several ms per residual on OLAP group-aggregate queries. `_residual_polars_expr` now translates these shapes to native ``pl.Expr`` filters applied directly to the alias frame (graph-benchmark q5 10.2→6.6ms, q6 10.7→8.9ms on dgx). Null semantics match the ``where_rows`` evaluator (null comparisons drop the row); any unrecognized shape, alias mismatch, or absent column falls back to the existing chain path — and if *any* expr in a residual group fails to translate, the whole group falls back (never a partial mix). Byte-parity verified across an 8-case adversarial differential (nulls, unicode/casefold, numeric ranges, mixed residuals) plus the full suite.

graphistry/compute/gfql_fast_paths.py

@@ -1957,6 +1957,11 @@ def _execute_seeded_typed_hop_fast_path(
     is_polars = is_polars_df(nodes_frame)
     if is_polars != is_polars_df(base_graph._edges):
         return None  # mixed-engine node/edge frames: decline, full path decides
+    if select_items is not None and (requested_engine in (Engine.POLARS, Engine.POLARS_GPU)) != is_polars:
+        # Requested-vs-actual engine mismatch (e.g. polars frames + engine='pandas'):
+        # the full path CONVERTS the result to the requested engine, so the lean
+        # projection would leak actual-engine frames. Decline; the full path decides.
+        return None
     helper = _seeded_typed_return_dst_polars if is_polars else _seeded_typed_return_dst_pandas_cudf
     dst_res = helper(base_graph, n0, n2, e1, src, dst, node, direction)
     if dst_res is None:
@@ -1971,11 +1976,36 @@ def _execute_seeded_typed_hop_fast_path(
             import polars as pl
             out_frame = p_rows.select([pl.col(prop).alias(out) for out, prop in select_items])
         else:
+            # dtype parity with the full path: non-id properties ride the rows-pivot,
+            # which upcasts int/float -> float64 and bool -> object; the node-id
+            # property passes through the pivot key and keeps its dtype. Any dtype
+            # class not verified against the pivot (datetimes, pandas extension
+            # dtypes like nullable Int64/StringDtype, categoricals) declines to the
+            # full path rather than risk a silent dtype divergence.
+            import numpy as np
+            casts: Dict[str, str] = {}
+            for out_name, prop in select_items:
+                if prop == node:
+                    continue
+                d = p_rows[prop].dtype
+                if not isinstance(d, np.dtype):
+                    return None
+                if d == np.dtype(bool):
+                    casts[out_name] = "object"
+                elif d.kind in "iuf":
+                    casts[out_name] = "float64"
+                elif d.kind != "O":
+                    return None
             out_frame = p_rows[[prop for _, prop in select_items]].copy()
             out_frame.columns = [out for out, _ in select_items]
+            for out_name, target in casts.items():
+                out_frame[out_name] = out_frame[out_name].astype(target)
         out = base_graph.bind()
         out._nodes = out_frame
-        out._edges = None
+        # full-path parity: a property RETURN yields an EMPTY edges frame with the
+        # edge schema (never None — res._edges must stay usable). The helper's
+        # edges are the matched hop edges, so take their zero-row head.
+        out._edges = _edges.head(0)
         return out
     assert projection is not None  # narrowed by the gate above
     # Lean projection: p_rows already IS the RETURN-alias (destination) node set.

graphistry/tests/compute/gfql/test_seeded_typed_hop_fastpath.py

@@ -688,3 +688,87 @@ def test_out_of_shape_declines_with_parity(self, q, label):
             import pytest as _pt
             with _pt.raises(Exception):
                 _run_diff(g, "pandas", q, fast=False)
+
+
+class TestSeededProjectionDtypeAndEdgesParity:
+    """Review pins (plans/review-pr-1766/review.md): B1 int-property dtype parity
+    (the full pandas path's rows-pivot upcasts non-id int/float props to float64
+    and bool to object; the id prop keeps its dtype), M1 res._edges is an EMPTY
+    edges frame (never None), M2 requested-vs-actual engine mismatch declines."""
+
+    Q = ("MATCH (m:Message {id:10})-[{type:'HAS_CREATOR'}]->(p:Person) "
+         "RETURN p.id AS pid, p.age AS a, p.flag AS f")
+
+    def _typed_graph(self):
+        ndf = pd.DataFrame({
+            "id": [0, 1, 2, 10, 11],
+            "type": ["Person"] * 3 + ["Message"] * 2,
+            "age": [30, 40, 50, 0, 0],              # int64: pivot upcasts to float64
+            "flag": [True, False, True, False, False],  # bool: pivot upcasts to object
+            "ts": pd.to_datetime(["2020-01-01"] * 5),   # datetime: fast path declines
+        })
+        edf = pd.DataFrame({"src": [10, 10, 11], "dst": [0, 1, 2],
+                            "type": ["HAS_CREATOR"] * 3})
+        return graphistry.nodes(ndf, "id").edges(edf, "src", "dst")
+
+    def _pl_graph(self):
+        pl = pytest.importorskip("polars")
+        g = self._typed_graph()
+        return graphistry.nodes(pl.from_pandas(g._nodes), "id").edges(
+            pl.from_pandas(g._edges), "src", "dst")
+
+    def _fast_and_full(self, g, engine, q, expect_engage=True):
+        hits = {"n": 0}
+        real = gfql_unified._execute_seeded_typed_hop_fast_path
+
+        def spy(*a, **k):
+            r = real(*a, **k)
+            hits["n"] += r is not None
+            return r
+        gfql_unified._execute_seeded_typed_hop_fast_path = spy
+        try:
+            fast = g.gfql(q, engine=engine)
+        finally:
+            gfql_unified._execute_seeded_typed_hop_fast_path = real
+        full = _run_diff(g, engine, q, fast=False)
+        assert bool(hits["n"]) == expect_engage, f"engaged={hits['n']} expected={expect_engage}"
+        return fast, full
+
+    def test_pandas_int_bool_dtype_parity(self):
+        fast, full = self._fast_and_full(self._typed_graph(), "pandas", self.Q)
+        pd.testing.assert_frame_equal(_canon_nodes(fast), _canon_nodes(full))
+        dt = dict(zip(fast._nodes.columns, map(str, fast._nodes.dtypes)))
+        assert dt == {"pid": "int64", "a": "float64", "f": "object"}
+
+    def test_polars_int_bool_dtype_parity(self):
+        pytest.importorskip("polars")
+        fast, full = self._fast_and_full(self._pl_graph(), "polars", self.Q)
+        assert dict(fast._nodes.schema) == dict(full._nodes.schema)
+        pd.testing.assert_frame_equal(_canon_nodes(fast), _canon_nodes(full))
+
+    def test_pandas_datetime_property_declines(self):
+        q = self.Q.replace("p.flag AS f", "p.ts AS t")
+        fast, full = self._fast_and_full(self._typed_graph(), "pandas", q, expect_engage=False)
+        pd.testing.assert_frame_equal(_canon_nodes(fast), _canon_nodes(full))
+
+    @pytest.mark.parametrize("engine", ["pandas", "polars"])
+    def test_edges_empty_frame_not_none(self, engine):
+        g = self._typed_graph() if engine == "pandas" else self._pl_graph()
+        if engine == "polars":
+            pytest.importorskip("polars")
+        fast, full = self._fast_and_full(g, engine, self.Q)
+        assert fast._edges is not None
+        assert fast._edges.shape[0] == 0
+        assert sorted(map(str, fast._edges.columns)) == sorted(map(str, full._edges.columns))
+        assert full._edges.shape[0] == 0
+
+    def test_engine_mismatch_declines(self):
+        pytest.importorskip("polars")
+        # polars frames + engine='pandas': full converts to pandas; fast must decline
+        fast, full = self._fast_and_full(self._pl_graph(), "pandas", self.Q, expect_engage=False)
+        assert type(fast._nodes).__module__.startswith("pandas")
+        pd.testing.assert_frame_equal(_canon_nodes(fast), _canon_nodes(full))
+        # pandas frames + engine='polars' (reentry direction): also declines
+        fast2, full2 = self._fast_and_full(self._typed_graph(), "polars", self.Q, expect_engage=False)
+        assert type(fast2._nodes).__module__ == type(full2._nodes).__module__
+        pd.testing.assert_frame_equal(_canon_nodes(fast2), _canon_nodes(full2))