Merge #1816 into docs/withdraw-q8-win-claim-1825 (linear PR stack, top)

Docs sits at the TOP so a change-request here cannot block the code underneath.

CHANGELOG hand-resolved: this branch REPLACES #1823's entry rather than adding
one, so neither a textual 3-way nor the add-only fallback applies. Built as the
parent file with the q8 withdrawal applied in place, asserting the anchor occurs
exactly once before the edit and the entry exactly once after.

Rebuilt from this branch's clean pre-stack head: an earlier stacking attempt
uploaded child blobs over already-merged ones, which propagated a dropped
POLARS_TEST_FILES entry up the whole stack and turned test-gfql-core red.

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

Author: lmeyerov

CHANGELOG.md

@@ -13,5 +13,5 @@
       "max_properties": 0
     }
   },
-  "lowering_py_max_lines": 9255
+  "lowering_py_max_lines": 9260
 }

bin/ci_cypher_surface_guard_baseline.json

@@ -34,6 +34,9 @@ POLARS_TEST_FILES=(
     # only ever run here (the file has no module-level importorskip, so nothing else flags it)
     graphistry/tests/compute/gfql/test_exec_context_scoping.py
     graphistry/tests/compute/gfql/test_engine_polars_cypher_conformance.py
+    # aggregate x dtype type contract: the polars params of this file are the ONLY lane where the
+    # native polars aggregate guard and the raw-polars-exception wrap are exercised
+    graphistry/tests/compute/gfql/test_aggregate_type_contract.py
     graphistry/tests/compute/gfql/test_engine_polars_conformance_matrix.py
     graphistry/tests/compute/gfql/test_polars_string_predicate_nonstring.py
     graphistry/tests/compute/gfql/cypher/test_order_by_null_placement.py
@@ -55,6 +58,7 @@ POLARS_TEST_FILES=(
     # polars-parametrized cases inside otherwise-pandas modules: these files DO run in the
     # pandas lanes, but their polars/polars-gpu parameters are skipped there for want of the
     # wheel, so the polars lane is the only place those parameters can execute
+    graphistry/tests/compute/gfql/test_const_fold_engine_parity.py
     graphistry/tests/compute/gfql/index/test_indexed_bindings.py
     graphistry/tests/compute/gfql/test_reentry_caller_graph_immutability.py
     graphistry/tests/compute/gfql/test_rewrite_param_discard.py

bin/test-polars.sh

@@ -437,10 +437,25 @@ analysis = g.gfql([
 | `LIMIT 10` | `limit(10)` | Row cap |
 | `WHERE <row expr>` | `where_rows(expr="...")` | Scalar expression subset |
 | `count(*)` | `group_by(keys=[...], aggregations=[("cnt", "count")])` | Grouped count |
-| `sum(n.val)` | `group_by(..., aggregations=[("total", "sum", "val")])` | Grouped sum |
+| `sum(n.val)` | `group_by(..., aggregations=[("total", "sum", "val")])` | Grouped sum; see [Aggregate input types](#aggregate-input-types) |
 | `collect(n.x)` | `group_by(..., aggregations=[("xs", "collect", "x")])` | Nulls excluded from collection |
 | Named patterns | `rows(source="alias")` | Scope row table to a named match alias |
 
+### Aggregate input types
+
+`sum` and `avg` accept `INTEGER`, `FLOAT` and `DURATION`, matching Cypher — **plus `BOOLEAN`, which
+is a deliberate GFQL extension.** Neo4j rejects it (*"expected Float, Integer or Duration but was
+Boolean"*); GFQL accepts it because summing an indicator column is idiomatic in the dataframe
+surface GFQL also serves, and every engine already agrees on the answer. `sum` over a boolean
+counts the true values; `avg` gives their fraction.
+
+Any other input type **raises**. This is stricter than earlier releases, where a string column
+returned its *concatenation* on pandas and leaked a raw polars error on polars — wrong in two
+different directions.
+
+Empty and all-null inputs follow Cypher rather than SQL: `sum` returns **0**, `avg` returns
+**null**.
+
 ## Key Differences
 
 | Feature | Python | Wire Protocol |

docs/source/gfql/spec/cypher_mapping.md

@@ -13,7 +13,14 @@
     # Frame aliases (pandas types for mypy; ``Any`` at runtime). Imported under TYPE_CHECKING
     # and referenced via string annotations below so Engine.py — imported very early — never
     # triggers ``graphistry.compute`` package init at runtime (would be circular).
-    from graphistry.compute.typing import DataFrameT, SeriesT
+    from graphistry.compute.typing import DataFrameT, PolarsFrame, PolarsSeriesT, SeriesT
+    # TypeGuard, NOT TypeIs (PEP 742). TypeIs additionally narrows the negative branch, and to
+    # do that soundly it REQUIRES the narrowed type to be consistent with the declared input
+    # type. ``is_polars_df`` is called on values declared ``DataFrameT``/``SeriesT`` (i.e.
+    # pandas), and a polars frame is not a subtype of a pandas one, so TypeIs is rejected here
+    # — it typechecks only where the declared type already contains the narrowed one (as in
+    # ``polars/dtypes.py:is_lazy``, whose input is already ``PolarsFrame``).
+    from typing_extensions import TypeGuard
 
 
 class Engine(Enum):
@@ -196,13 +203,20 @@ def _cudf_from_pandas_best_effort(df: pd.DataFrame, *, validate: Optional[Valida
         return out_gdf
 
 
-def is_polars_df(df: Any) -> bool:
+def is_polars_df(df: object) -> "TypeGuard[PolarsFrame]":
     """True if ``df`` is a polars DataFrame or LazyFrame.
 
     Import-light module-name check (polars is an optional dependency, so we avoid importing
     it just to ``isinstance``). ``type(df).__module__`` starts with ``polars.`` for both
     ``pl.DataFrame`` and ``pl.LazyFrame``. Single source of truth — the gfql engine had this
-    reimplemented in 5 places."""
+    reimplemented in 5 places.
+
+    Declared ``TypeGuard[PolarsFrame]`` rather than ``bool`` so the polars branch of an
+    engine-dispatching helper actually narrows: callers pass a value declared ``DataFrameT``
+    (pandas at checking time) and the guard is what proves the polars API is available inside
+    the branch, with no ``cast`` at the call site. ``object`` (not ``Any``) as the parameter
+    type is deliberate — it is the widest input a predicate can accept while still checking
+    its own body."""
     return df is not None and "polars" in type(df).__module__
 
 
@@ -287,7 +301,10 @@ def df_to_engine(df, engine: Engine, *, validate: Optional[ValidationParam] = No
             with target_mode(_tgt):
                 return _pl_nan_to_null(_lazy_collect(df))
         if isinstance(df, pa.Table):
-            return _pl_nan_to_null(pl.from_arrow(df))
+            # ``pl.from_arrow`` is declared ``DataFrame | Series`` because polars cannot
+            # overload it on the pyarrow input type (see polars/convert/general.py); a
+            # ``pa.Table`` in always yields a DataFrame, so the Series arm is unreachable here.
+            return _pl_nan_to_null(pl.from_arrow(df))  # type: ignore[arg-type]
         pl_validate: ValidationParam = 'strict' if validate is None else validate
         if isinstance(df, pd.DataFrame):
             return _pl_from_pandas(df, validate=pl_validate, warn=warn)
@@ -300,7 +317,8 @@ def df_to_engine(df, engine: Engine, *, validate: Optional[ValidationParam] = No
         if 'cudf' in str(type(df).__module__):
             import cudf
             if isinstance(df, cudf.DataFrame):
-                return _pl_nan_to_null(pl.from_arrow(df.to_arrow()))
+                # see the pa.Table branch above for the from_arrow union
+                return _pl_nan_to_null(pl.from_arrow(df.to_arrow()))  # type: ignore[arg-type]
         # dask/spark and anything else: route through pandas
         return _pl_from_pandas(df_to_engine(df, Engine.PANDAS), validate=pl_validate, warn=warn)
     raise ValueError(f'Only engines pandas/cudf/dask/polars supported, got: {engine}')
@@ -862,39 +880,51 @@ def safe_merge(
 # Engine-agnostic series / frame primitives (pandas / cuDF / polars dispatch).
 #
 # Pure per-row/per-column dispatch helpers with no domain knowledge — the polars
-# branches genuinely return polars objects mypy can't narrow to the pandas frame
-# aliases, so the localized ``# type: ignore`` lives here at the dispatch point and
-# callers get a clean ``SeriesT`` / ``DataFrameT`` contract with no ``cast()``.
+# branches genuinely RETURN polars objects, which cannot be the pandas frame aliases
+# the engine-agnostic signature promises, so the localized ``# type: ignore`` lives
+# here at the dispatch point and callers get a clean ``SeriesT`` / ``DataFrameT``
+# contract with no ``cast()``.
+# Since ``is_polars_df`` / ``is_polars_series`` became TypeGuards the polars branch is
+# now genuinely CHECKED against the polars API (the ignores below are scoped to the
+# return/argument mismatch alone, no longer blanket ``attr-defined``).
 # Annotations are strings so the TYPE_CHECKING-only alias import stays runtime-free.
 # ---------------------------------------------------------------------------
 
 
+def is_polars_series(s: object) -> "TypeGuard[PolarsSeriesT]":
+    """True if ``s`` is a polars Series. Same import-light module check as ``is_polars_df``
+    (``polars.series.series``), split out only so the SERIES call sites narrow to
+    ``pl.Series`` instead of to a frame -- the frame guard would wrongly promise
+    ``.height`` / ``.columns`` on a value that is a column."""
+    return s is not None and "polars" in type(s).__module__
+
+
 def is_series_like(s: object) -> bool:
     """True for a pandas/cuDF Series (``.dropna``) or a polars Series (module check).
 
     Some engine-agnostic callers accept an ``ids`` Series that is pandas under
     ``engine='pandas'`` and polars under ``engine='polars'``; both are valid."""
-    return hasattr(s, "dropna") or is_polars_df(s)
+    return hasattr(s, "dropna") or is_polars_series(s)
 
 
 def series_not_null_mask(s: "SeriesT") -> "SeriesT":
     """Non-null boolean mask, engine-aware (polars ``is_not_null`` vs pandas ``notna``)."""
-    if is_polars_df(s):
-        return s.is_not_null()  # type: ignore[attr-defined,no-any-return]
+    if is_polars_series(s):
+        return s.is_not_null()  # type: ignore[return-value]  # polars Series, not the pandas alias
     return s.notna()
 
 
 def series_filter(s: "SeriesT", mask: "SeriesT") -> "SeriesT":
     """Filter a Series by a boolean mask, engine-aware, dropping the old index (pandas)."""
-    if is_polars_df(s):
-        return s.filter(mask)  # type: ignore[attr-defined,no-any-return]
+    if is_polars_series(s):
+        return s.filter(mask)  # type: ignore[return-value]  # polars Series, not the pandas alias
     return s[mask].reset_index(drop=True)
 
 
 def frame_filter(df: "DataFrameT", mask: "SeriesT") -> "DataFrameT":
     """Filter a DataFrame's rows by a boolean mask, engine-aware, dropping the old index."""
     if is_polars_df(df):
-        return df.filter(mask)  # type: ignore[attr-defined,no-any-return]
+        return df.filter(mask)  # type: ignore[return-value]  # polars frame, not the pandas alias
     return df.loc[mask].reset_index(drop=True)
 
 
@@ -909,16 +939,18 @@ def ordered_left_join(left: "DataFrameT", right: "DataFrameT", *, on: str) -> "D
     if is_polars_df(left):
         if not is_polars_df(right):
             right = df_to_engine(right, Engine.POLARS)
-        return left.join(right, on=on, how="left", maintain_order="left")  # type: ignore[call-arg,no-any-return]
+        return left.join(right, on=on, how="left", maintain_order="left")  # type: ignore[arg-type,return-value]
     return safe_merge(left, right, on=on, how="left")
 
 
 def row_as_mapping(rows: "DataFrameT", row_index: int) -> Mapping[str, Any]:
     """One frame row as a col->scalar mapping, engine-aware (``row[col]`` works for
     both the pandas Series and the polars named-row dict)."""
     if is_polars_df(rows):
-        return rows.row(row_index, named=True)  # type: ignore[attr-defined,no-any-return]
-    return rows.iloc[row_index]
+        # ``.row()`` is eager-only; the guard cannot rule out a LazyFrame, and callers of
+        # this helper are always past collection.
+        return rows.row(row_index, named=True)  # type: ignore[union-attr]
+    return rows.iloc[row_index]  # type: ignore[return-value]  # pandas Series is a str->scalar mapping
 
 
 def assign_constant_columns(df: "DataFrameT", values: Dict[str, Any]) -> "DataFrameT":
@@ -927,14 +959,14 @@ def assign_constant_columns(df: "DataFrameT", values: Dict[str, Any]) -> "DataFr
         return df
     if is_polars_df(df):
         import polars as pl
-        return df.with_columns([pl.lit(v).alias(k) for k, v in values.items()])  # type: ignore[attr-defined,no-any-return]
+        return df.with_columns([pl.lit(v).alias(k) for k, v in values.items()])  # type: ignore[return-value]
     return df.assign(**values)
 
 
 def drop_columns(df: "DataFrameT", cols: Sequence[str]) -> "DataFrameT":
     """Drop columns by name, engine-aware (polars ``drop(list)`` vs pandas ``drop(columns=)``)."""
     if is_polars_df(df):
-        return df.drop(list(cols))  # type: ignore[no-any-return]
+        return df.drop(list(cols))  # type: ignore[return-value]
     return df.drop(columns=list(cols))