feat: cudf same-path executor

.gitignore

@@ -101,6 +101,7 @@ docs/source/demos
 # Legacy - kept for backward compatibility
 AI_PROGRESS/
 /PLAN.md
+/plan.md
 plans/
 tmp/
 test_env/

CHANGELOG.md

@@ -13,13 +13,20 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - **Docs / hop**: Added bounded-hop walkthrough notebook (`docs/source/gfql/hop_bounds.ipynb`), cheatsheet and GFQL spec updates, and examples showing how to combine hop ranges, labels, and output slicing.
 - **GFQL / reference**: Extended the pandas reference enumerator and parity tests to cover hop ranges, labeling, and slicing so GFQL correctness checks include the new traversal shapes.
 - **Docs / GFQL**: Documented the external `tck-gfql` conformance harness and local run instructions in GFQL docs.
+- **GFQL / Oracle**: Introduced `graphistry.gfql.ref.enumerator`, a pandas-only reference implementation that enumerates fixed-length chains, enforces local + same-path predicates, applies strict null semantics, enforces safety caps, and emits alias tags/optional path bindings for use as a correctness oracle.
+- **GFQL / cuDF same-path**: Added execution-mode gate `GRAPHISTRY_CUDF_SAME_PATH_MODE` (auto/oracle/strict) for GFQL cuDF same-path executor. Auto falls back to oracle when GPU unavailable; strict requires cuDF or raises. Oracle path retains safety caps and alias-tag propagation.
+- **GFQL / cuDF executor**: Implemented same-path pruning path (wavefront backward filtering, min/max summaries for inequalities, value-aware equality filters) with oracle fallback. CUDF chains with WHERE now dispatch through the same-path executor.
 
 ### Fixed
 - **Compute / hop**: Exact-hop traversals now prune branches that do not reach `min_hops`, avoid reapplying min-hop pruning in reverse passes, keep seeds in wavefront outputs, and reuse forward wavefronts when recomputing labels so edge/node hop labels stay aligned (fixes 3-hop branch inclusion issues and mislabeled slices).
 
 ### Tests
 - **GFQL / hop**: Expanded `test_compute_hops.py` and GFQL parity suites to assert branch pruning, bounded outputs, label collision handling, and forward/reverse slice behavior.
 - **Reference enumerator**: Added oracle parity tests for hop ranges and output slices to guard GFQL integrations.
+- **GFQL**: Added deterministic + property-based oracle tests (triangles, alias reuse, cuDF conversions, Hypothesis) plus parity checks ensuring pandas GFQL chains match the oracle outputs.
+- **GFQL / cuDF same-path**: Added strict/auto mode coverage for cuDF executor fallback behavior to keep CI stable while GPU kernels are wired up.
+- **GFQL / cuDF same-path**: Added GPU-path parity tests (equality/inequality) over CPU data to guard semantics while GPU CI remains unavailable.
+- **Layouts**: Added comprehensive test coverage for `circle_layout()` and `group_in_a_box_layout()` with partition support (CPU/GPU)
 
 ### Infra
 - **Tooling**: `bin/flake8.sh` / `bin/mypy.sh` now require installed tools (no auto-install), honor `FLAKE8_CMD` / `MYPY_CMD` and optional `MYPY_EXTRA_ARGS`; `bin/lint.sh` / `bin/typecheck.sh` resolve via uvx → python -m → bare.
@@ -109,6 +116,8 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 ### Tests
 - **CI / Python**: Expand GitHub Actions coverage to Python 3.13 + 3.13/3.14 for CPU lint/type/test jobs, while pinning RAPIDS-dependent CPU/GPU suites to <=3.13 until NVIDIA publishes 3.14 wheels (ensures lint/mypy/pytest signal on the latest interpreter without breaking RAPIDS installs).
 - **GFQL**: Added deterministic + property-based oracle tests (triangles, alias reuse, cuDF conversions, Hypothesis) plus parity checks ensuring pandas GFQL chains match the oracle outputs.
+- **GFQL / cuDF same-path**: Added strict/auto mode coverage for cuDF executor fallback behavior to keep CI stable while GPU kernels are wired up.
+- **GFQL / cuDF same-path**: Added GPU-path parity tests (equality/inequality) over CPU data to guard semantics while GPU CI remains unavailable.
 - **Layouts**: Added comprehensive test coverage for `circle_layout()` and `group_in_a_box_layout()` with partition support (CPU/GPU)
 
 ### Infra

graphistry/compute/chain.py

@@ -1,6 +1,6 @@
 import logging
 import pandas as pd
-from typing import Dict, Union, cast, List, Tuple, Optional, TYPE_CHECKING
+from typing import Dict, Union, cast, List, Tuple, Sequence, Optional, TYPE_CHECKING
 from graphistry.Engine import Engine, EngineAbstract, df_concat, df_to_engine, resolve_engine
 
 from graphistry.Plottable import Plottable
@@ -12,6 +12,11 @@
 from .typing import DataFrameT
 from .util import generate_safe_column_name
 from graphistry.compute.validate.validate_schema import validate_chain_schema
+from graphistry.compute.gfql.same_path_types import (
+    WhereComparison,
+    parse_where_json,
+    where_to_json,
+)
 from .gfql.policy import PolicyContext, PolicyException
 from .gfql.policy.stats import extract_graph_stats
 
@@ -26,8 +31,14 @@
 
 class Chain(ASTSerializable):
 
-    def __init__(self, chain: List[ASTObject], validate: bool = True) -> None:
+    def __init__(
+        self,
+        chain: List[ASTObject],
+        where: Optional[Sequence[WhereComparison]] = None,
+        validate: bool = True,
+    ) -> None:
         self.chain = chain
+        self.where = list(where or [])
         if validate:
             # Fail fast on invalid chains; matches documented automatic validation behavior
             self.validate(collect_all=False)
@@ -120,7 +131,15 @@ def from_json(cls, d: Dict[str, JSONVal], validate: bool = True) -> 'Chain':
                 f"Chain field must be a list, got {type(d['chain']).__name__}"
             )
 
-        out = cls([ASTObject_from_json(op, validate=validate) for op in d['chain']], validate=validate)
+        where_raw = d.get('where')
+        where = parse_where_json(
+            cast(Optional[Sequence[Dict[str, Dict[str, str]]]], where_raw)
+        )
+        out = cls(
+            [ASTObject_from_json(op, validate=validate) for op in d['chain']],
+            where=where,
+            validate=validate,
+        )
         return out
 
     def to_json(self, validate=True) -> Dict[str, JSONVal]:
@@ -129,10 +148,13 @@ def to_json(self, validate=True) -> Dict[str, JSONVal]:
         """
         if validate:
             self.validate()
-        return {
+        data: Dict[str, JSONVal] = {
             'type': self.__class__.__name__,
             'chain': [op.to_json() for op in self.chain]
         }
+        if self.where:
+            data['where'] = where_to_json(self.where)
+        return data
 
     def validate_schema(self, g: Plottable, collect_all: bool = False) -> Optional[List['GFQLSchemaError']]:
         """Validate this chain against a graph's schema without executing.