graphistry
diff --git a/‎CHANGELOG.md‎
Lines changed: 2 additions & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 2 additions & 0 deletions
diff --git a/‎graphistry/compute/chain.py‎
Lines changed: 49 additions & 10 deletions b/‎graphistry/compute/chain.py‎
Lines changed: 49 additions & 10 deletions
diff --git a/‎graphistry/compute/chain_fast_paths.py‎
Lines changed: 51 additions & 0 deletions b/‎graphistry/compute/chain_fast_paths.py‎
Lines changed: 51 additions & 0 deletions
@@ -22,8 +22,10 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - **GFQL indexed fixed-hop bindings now dispatch BEFORE the canonical traversal (pandas / cuDF / native Polars)**: the resident-index fixed-hop path (`rows(binding_ops=...)`, the Cypher multi-alias `MATCH … RETURN` shape) was consulted only *inside* row materialization — after the engine had already run the full canonical traversal — so its compact path bag was computed on top of the graph-sized work it exists to avoid. Both the pandas/cuDF chain boundary and the native Polars chain now ask the same shared, structural gate first and, only when it can serve the WHOLE middle exactly, skip the canonical traversal and hand the compact state to the unchanged row materializer. Engagement stays operator/index/dtype/cost based — no query, schema, or hop-count recognition — and every unsupported, seeded, prefiltered, policy-bearing, shortest-path, or cost-gated shape still declines to canonical execution with identical results. On a standard LDBC SNB SF1 interactive-short profile this removed the redundant two-hop typed-mask and 16-merge buckets and cut the profiled call ~11.9× (1263 ms → 106 ms), exact 19-row oracle preserved.
 - **Indexed seed lookup now covers a unique node id PLUS extra scalar constraints**: `{node_id: v, other: w}` previously fell back to a full node-table scan even though the unique node-id index can gather at most one row; it now gathers that one row and applies the remaining constraints to it. Missing ids and non-matching extra constraints return the same empty result as before, and duplicate-id graphs (which cannot build the index) are unaffected.
 - **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.
+- **The pandas/cuDF chain fast path serves NAMED patterns**: `_try_chain_fast_path` rejected any op carrying an alias, so `g.gfql([n(name='x'), e_forward(name='r'), n(name='y')])` fell to the full two-pass BFS purely because the ops were named — naming is a PROJECTION concern, not a traversal one, and it should not decide which engine path runs. The alias flag columns `combine_steps` would have merged in are now reconstructed directly from the edges the fast path returns (`_tag_fast_path_aliases`): `combine_steps` tags a node with an alias iff it still participates in a surviving edge, and those edges are exactly the ones the fast path already produced, so `isin` over their endpoint columns is the same predicate computed without the join. A seed whose edges all fail the filter yields an empty edge frame and is tagged `False`, which is the dead-end case. Deliberate declines kept: **undirected + named** (an undirected edge makes a node reachable as either endpoint, so alias identity is not derivable from the endpoint columns), **duplicate alias names** (E201 is raised by `combine_steps`, so serving here would bypass the check and let alias reuse silently succeed), and **a resident index that would actually serve the shape** (checked with `_resident_seed_indexes`, i.e. index VALIDITY for these exact frames — a registry-presence check instead declines on every query and silently turns the whole optimization into a measured no-op). **Measured** on a 200-node / 800-edge pandas graph, where data-proportional work is ~0 so this is the per-query plan floor. Five alternating paired runs against `origin/master`, each the median of 200 reps after 20 warmups: the named 3-op traversal `25.2 ms (24.2–27.0) → 2.3 ms (2.1–2.7)`, **~11×**, and the same pattern followed by `rows(binding_ops=...)` `40.4 ms (38.1–43.6) → 17.4 ms (16.8–19.8)`, **~2.3×**. The `rows()` output is byte-identical between the two arms and the traversal output is value-identical (dtypes differ deliberately, see *Changed*). **Scope, stated plainly**: this is a NATIVE `g.gfql([...named...])` / `g.chain([...named...])` improvement only. It is pandas/cuDF-only, and an instrumented run of the graph-benchmark q1–q9 lane showed the chain fast path is **never consulted** for those Cypher queries — they are served earlier by the Cypher-layer fast paths in `gfql_fast_paths.py`, or hit a separate single-op gate — so **no benchmark cell moves** and no lane currently exercises this. A benchmark lane over the native named-chain surface is required follow-up before any perf claim is made on the board.
 
 ### Changed
+- **A served chain fast path now returns Cypher-conformant int/bool dtypes on named patterns too**: the pandas full path's rows-pivot upcasts non-id `int64 → float64` and `bool → object` through its merges. That is a pandas merge artifact, not a Cypher semantic — the openCypher TCK (`clauses/return/Return2.feature`, "Returning a node property value": `CREATE ({num: 1})` / `RETURN a.num` expects `1`, and the TCK value grammar writes an Integer as bare decimal digits and a Float with its decimals) and Neo4j (INTEGER and FLOAT are distinct property types; `valueType()` on an integer property reports `INTEGER NOT NULL`) both keep the integer, and this library's own **polars** and **cuDF** canonical paths already return `int64`/`bool` for the same query, so only the pandas merge upcasts. The chain fast path already preserved the conformant dtypes for UNNAMED patterns (documented in its docstring); serving named patterns extends that to the named surface rather than creating a new divergence, and the conformant dtype is deliberately kept rather than cast back to reproduce the defect. **User-visible** where a named pandas pattern is served by the fast path: an integer node property comes back `int64` instead of `float64` (`30` rather than `30.0`, including in JSON), and an alias flag column comes back `bool` instead of `object`. Values are unchanged. **Not aligned yet** (deliberately out of scope, follow-up): the pandas full path itself, and the Cypher-layer seeded projection, still emit the artifact — so pandas can still report `float64` for the same logical query depending on which internal path serves it.
 - **`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.
 
 
@@ -11,7 +11,7 @@
 from .ast import ASTObject, ASTNode, ASTEdge, ASTCall, Direction, from_json as ASTObject_from_json, serialize_binding_ops
 from .typing import DataFrameT, SeriesT
 from .util import generate_safe_column_name
-from .chain_fast_paths import _seeded_typed_hop_pandas_cudf
+from .chain_fast_paths import _seeded_typed_hop_pandas_cudf, _tag_fast_path_aliases
 from graphistry.compute.validate.validate_schema import validate_chain_schema
 from graphistry.compute.gfql.same_path_types import (
     WhereComparison,
@@ -822,9 +822,11 @@ def _try_chain_fast_path(
 
     Same node/edge sets + VALUES as the full machinery (trackA_golden + hop/chain
     suites); the 1-hop additionally preserves int node dtypes (the full path upcasts
-    int→float via merge). Gated to unnamed/unqueried nodes + a plain single-hop edge;
-    filtered-undirected and seeded chains fall through. polars/dask/spark also fall
-    through (own fast path / lazy semantics)."""
+    int→float via merge — the merge is the artifact, int is the Cypher-conformant type).
+    Gated to unqueried nodes + a plain single-hop edge; NAMED ops are served (the alias
+    flags are reconstructed by `_tag_fast_path_aliases`) except when undirected or when
+    the same alias is reused. filtered-undirected and seeded chains fall through.
+    polars/dask/spark also fall through (own fast path / lazy semantics)."""
     from graphistry.compute.filter_by_dict import filter_by_dict
 
     if engine_concrete not in (Engine.PANDAS, Engine.CUDF):
@@ -852,13 +854,28 @@ def _materialize_fast_path_graph() -> Plottable:
     if len(ops) != 3:
         return None
     n0, e1, n2 = ops
-    if not (isinstance(n0, ASTNode) and n0._name is None and n0.query is None):
+    # Aliases are a PROJECTION concern, not a traversal one: capture them, serve the
+    # traversal on the fast path, and tag the result (_tag_fast_path_aliases). Rejecting
+    # them here sent a NAMED `g.gfql([n(name=..), e(..), n(name=..)])` to the full
+    # two-pass BFS purely because the ops carried names — measured ~25.2 ms before vs
+    # ~2.3 ms after (medians of 5 paired runs), on a 200-node graph where data work is ~0.
+    # SCOPE, measured: this does NOT reach the Cypher `MATCH ... RETURN` surface for the
+    # benchmark shapes. Those are served earlier by `gfql_fast_paths.py` and never consult
+    # this function at all, so do not attribute a Cypher-surface win to this gate.
+    alias_n0, alias_e1, alias_n2 = n0._name, e1._name, n2._name
+    _named = [a for a in (alias_n0, alias_e1, alias_n2) if a is not None]
+    if len(_named) != len(set(_named)):
+        # Duplicate alias reuse is an E201 error, and `combine_steps` is what raises it.
+        # Serving these here would BYPASS that check and silently succeed — decline so the
+        # full path still errors. (Caught by test_polars_duplicate_alias_declines_like_pandas.)
         return None
-    if not (isinstance(n2, ASTNode) and n2._name is None and n2.query is None):
+    if not (isinstance(n0, ASTNode) and n0.query is None):
+        return None
+    if not (isinstance(n2, ASTNode) and n2.query is None):
         return None
     if not (isinstance(e1, ASTEdge) and e1.is_simple_single_hop()
             and e1.source_node_match is None
-            and e1.destination_node_match is None and e1._name is None
+            and e1.destination_node_match is None
             and e1.source_node_query is None and e1.destination_node_query is None
             and e1.edge_query is None and not e1.include_zero_hop_seed
             and not e1.prune_to_endpoints):  # prune keeps only the arrival side -> full path
@@ -868,6 +885,11 @@ def _materialize_fast_path_graph() -> Plottable:
     # below rather than falling through to the full two-pass machinery. source/dest
     # node match + edge_query (richer predicates) still bail above.
     direction = e1.direction
+    if direction == "undirected" and (alias_n0 is not None or alias_n2 is not None):
+        # An undirected edge makes a node reachable as EITHER endpoint, so "which alias
+        # does this node carry" is not derivable from the endpoint columns the way it is
+        # for a directed hop. Decline to the full path rather than guess.
+        return None
     unconstrained = not n0.filter_dict and not n2.filter_dict
     if not unconstrained and direction == "undirected":
         return None  # filtered-undirected (OR of both directions) -> full path
@@ -877,6 +899,20 @@ def _materialize_fast_path_graph() -> Plottable:
     src, dst, node = g._source, g._destination, g._node
     if src is None or dst is None or node is None:
         return None  # no edge/node bindings -> can't fast-path; full path handles it
+    if (alias_n0 is not None or alias_e1 is not None or alias_n2 is not None) \
+            and direction != "undirected" and g._nodes is not None and g._edges is not None:
+        # DEFER TO THE INDEX when one would ACTUALLY serve. A resident index is
+        # policy-controlled and can beat this scan-based path, and it is what serves named
+        # patterns today, so taking them here would SHADOW it.
+        # `_resident_seed_indexes` is the right question: it returns None unless BOTH
+        # indexes are VALID for these exact frames (fingerprint + identity via get_valid).
+        # A registry-presence / policy check is NOT equivalent — `get_registry` returns a
+        # non-None registry even when nothing is indexed, so that spelling declines on every
+        # query and silently turns this whole optimization into a no-op (measured: the win
+        # went to exactly 0). Re-measure the win, not just the suite, after touching this.
+        from .chain_fast_paths import _resident_seed_indexes
+        if _resident_seed_indexes(g, g._nodes, g._edges, node, src, dst, direction) is not None:
+            return None
     concat = df_concat(engine_concrete)
     if unconstrained:
         # No node filter to reduce by: validate BOTH endpoints against the full
@@ -902,7 +938,8 @@ def _materialize_fast_path_graph() -> Plottable:
         if engine_concrete in (Engine.PANDAS, Engine.CUDF):
             _fast_res = _seeded_typed_hop_pandas_cudf(g, n0, n2, e1, src, dst, node, direction)
             if _fast_res is not None:
-                return _fast_res
+                return _tag_fast_path_aliases(
+                    _fast_res, alias_n0, alias_e1, alias_n2, src, dst, node, direction)
         from_col, to_col = (src, dst) if direction == "forward" else (dst, src)
         edges = g._edges
         if n0.filter_dict:
@@ -935,15 +972,17 @@ def _materialize_fast_path_graph() -> Plottable:
             edges[[dst]].rename(columns={dst: node}),
         ]).drop_duplicates()
         nodes = cand[cand[node].isin(final[node])]
-        return g.nodes(nodes).edges(edges)
+        return _tag_fast_path_aliases(
+            g.nodes(nodes).edges(edges), alias_n0, alias_e1, alias_n2, src, dst, node, direction)
     endpoints = concat([
         edges[[src]].rename(columns={src: node}),
         edges[[dst]].rename(columns={dst: node}),
     ]).drop_duplicates()
     nodes = g._nodes[g._nodes[node].isin(endpoints[node])]
     # match the full path's merge, which collapses duplicate node-id rows
     nodes = nodes.drop_duplicates(subset=[node])
-    return g.nodes(nodes).edges(edges)
+    return _tag_fast_path_aliases(
+        g.nodes(nodes).edges(edges), alias_n0, alias_e1, alias_n2, src, dst, node, direction)
 
 
 @otel_traced("gfql.chain", attrs_fn=_chain_otel_attrs)
 
@@ -4,6 +4,10 @@
 typed 1-hop pandas/cuDF reduction and the seeded typed RETURN-destination pandas/cuDF and
 polars reductions. Pure code move, no behavior change. chain.py imports from here (one
 direction); this module imports only leaf modules (no back-edge into chain.py).
+
+New fast-path helpers belong HERE, not in chain.py — that is the direction this module was
+created to establish and it is why `_tag_fast_path_aliases` lives alongside the seeded
+reductions rather than next to `_try_chain_fast_path`.
 """
 # ruff: noqa: E501
 
@@ -18,6 +22,53 @@
     from graphistry.compute.gfql.index.registry import AdjacencyIndex, NodeIdIndex
 
 
+def _tag_fast_path_aliases(
+    res: Plottable,
+    alias_n0: Optional[str], alias_e1: Optional[str], alias_n2: Optional[str],
+    src: str, dst: str, node: str, direction: Direction,
+) -> Plottable:
+    """Attach the alias flag columns the full path's ``combine_steps`` would have merged in.
+
+    The chain fast path's gate used to reject ANY named op, so a named
+    `g.gfql([n(name=..), e(..), n(name=..)])` fell to the full two-pass machinery purely
+    because the ops carried names — measured ~25.2 -> ~2.3 ms (medians of 5 paired runs) on
+    a 200-node graph where data-proportional work is ~0. Naming is a PROJECTION concern,
+    not a traversal one, so it should not change which engine path runs. NOTE the scope: this is the NATIVE chain
+    surface. The Cypher `MATCH ... RETURN` shapes on the graph benchmark are served
+    earlier by `gfql_fast_paths.py` and never reach here (measured, both engines).
+
+    Why deriving the tags from the RETURNED EDGES matches the full path: `combine_steps`
+    tags a node with an alias iff it matched that step in the BACKWARD-PRUNED frame, i.e.
+    iff it still participates in a surviving edge. The edges this function receives are
+    exactly the surviving ones — the fast path has already applied the node filters, the
+    edge_match and the endpoint validation — so ``isin`` over their endpoint columns is the
+    same predicate, computed without the join.
+
+    A seed whose edges all fail the type filter yields an empty edge frame, so it is tagged
+    False rather than True: that is the dead-end case, and it is why the tag keys on the
+    edges rather than on the node filter.
+    """
+    if alias_n0 is None and alias_e1 is None and alias_n2 is None:
+        return res
+    nodes: Optional[DataFrameT] = res._nodes
+    edges: Optional[DataFrameT] = res._edges
+    if nodes is None or edges is None:
+        return res
+    from_col, to_col = (src, dst) if direction == "forward" else (dst, src)
+    node_flags: Dict[str, SeriesT] = {}
+    if alias_n0 is not None:
+        node_flags[alias_n0] = nodes[node].isin(edges[from_col])
+    if alias_n2 is not None:
+        node_flags[alias_n2] = nodes[node].isin(edges[to_col])
+    if node_flags:
+        nodes = nodes.assign(**node_flags)
+    if alias_e1 is not None:
+        edge_flags: Dict[str, bool] = {alias_e1: True}
+        edges = edges.assign(**edge_flags)
+
+    return res.nodes(nodes).edges(edges)
+
+
 def _seeded_scalar_filters(fd: Optional[Dict[str, Any]], df: DataFrameT) -> Optional[Dict[str, Any]]:
     """Resolve a filter dict to plain scalar column==value pairs, or None to bail
     to the general path. Mirrors filter_by_dict.resolve_filter_column exactly for