test+docs(cypher): pin aggregate-failfast interaction with chained-reentry carry (#1256 W1-I1)

Wave-1 review flagged that hidden-column forwarding could in principle silently
mutate grouping when the appended `__cypher_reentry_<S>_<X>__` bare item lands
inside a `WITH a, friend, count(*) AS n` chain — the carry would join the
group key set.

Empirically those queries already fail at the pre-existing
"aggregate would need repeated MATCH rows from a relationship pattern"
failfast, so no silent wrong-result path exists today. Pin that behavior with
a regression-lock test so a future change that lifts the aggregate failfast
must reckon with carry-grouping interaction explicitly.

Also document the DISTINCT/aggregate interaction in `_demote_secondary_whole_row_aliases`
inline so the next reader sees the design tradeoff.

Refs #1256.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: lmeyerov

graphistry/compute/gfql/cypher/lowering.py

@@ -7948,6 +7948,17 @@ def rewrite_text(expr: ExpressionText, field: str) -> ExpressionText:
     # is in the prefix) but the subsequent WITH/RETURN scope-narrowing drops it,
     # and references like `RETURN x.id AS xid` (rewritten to a bare hidden
     # identifier) fail at the inner compile's alias resolution.
+    #
+    # Interaction with DISTINCT/aggregating downstream stages: appending the
+    # carry as a bare item makes it a participant in DISTINCT key sets and (in
+    # principle) aggregation grouping. For multi-alias carry semantics this is
+    # what callers want — DISTINCT over `(friend, x.id)` is the desired
+    # behavior when `x.id` is referenced downstream. Queries that combine carry
+    # forwarding with relationship-pattern aggregation already fail at the
+    # earlier "aggregate would need repeated MATCH rows" failfast, so no silent
+    # wrong-grouping reaches a user via this code path. A future tightening
+    # (gate per-stage on `not stage.clause.distinct and not has_aggregate`) is
+    # tracked under #1256 follow-up.
     if refs_collected and rewritten_with_stages_tail:
         forwarded_items: List[ReturnItem] = []
         for alias_name, prop in sorted(refs_collected):

graphistry/tests/compute/gfql/cypher/test_lowering.py

@@ -8081,6 +8081,32 @@ def test_string_cypher_admits_multi_alias_distinct_forwarding_through_reentry()
     ]
 
 
+def test_string_cypher_chained_reentry_carry_with_aggregate_hits_existing_aggregate_failfast() -> None:
+    """#1256 wave-1 review W1-I1 regression-lock: hidden-column forwarding
+    appends ``__cypher_reentry_<S>_<X>__`` bare items to downstream WITH stages
+    so chained recursive compiles see them as scalar carries. The reviewer
+    flagged that a chained WITH with relationship-pattern aggregation could in
+    principle silently mutate grouping (`WITH a, friend, count(*) AS n` would
+    add the carry to the group key). Empirically those queries already fail at
+    the pre-existing aggregate-after-relationship-MATCH failfast, so no silent
+    wrong-result path exists. This test pins that behavior so a future change
+    that lifts the aggregate failfast must also reckon with carry-grouping
+    interaction explicitly.
+    """
+    query = (
+        "MATCH (a:A {id: 'a'}), (x:B {id: 'b'}) "
+        "WITH a, x "
+        "MATCH (a)-[:R]->(friend) "
+        "WITH a, x, count(*) AS n "
+        "RETURN x.id AS xid, n"
+    )
+    with pytest.raises(
+        GFQLValidationError,
+        match=r"aggregate would need repeated MATCH rows",
+    ):
+        _mk_multi_stage_reentry_graph().gfql(query)
+
+
 def test_string_cypher_failfast_rejects_intermediate_reentry_match_with_no_carried_source() -> None:
     """#1256 slice 4.3d remaining gap: trailing MATCH that does NOT start from a
     carried alias (free-form intermediate MATCH) is still unsupported.