fix(gfql): preserve bag multiplicity for whole-entity projections

[lmeyerov]

Summary

• preserve openCypher bag multiplicity for fixed-length, non-DISTINCT whole-node projections
• render single- and multi-node entity projections from Polars binding rows
• keep DISTINCT, variable-length paths, relationship-free matches, and WITH-to-MATCH reentry on their established lanes
• keep the seeded endpoint fast path aligned with the generic bag result

Correctness oracle

For nodes 1-5 and edges (1,2) (1,3) (2,3) (3,4), MATCH (a)-->(b) RETURN b now returns b.id = [2,3,3,4], including node 3 once per relationship match. Parallel-edge and two-hop fixtures discriminate a bag from a node set. Cross-engine pins cover pandas, Polars, and cuDF; the final DGX canary covers explicit Polars-GPU.

Validation

• rebased and linearized onto landed fix(gfql): a NULL id is not an identity — one NULL-endpoint contract on every engine (#1995) #1999/master; exact head 696327559297d8ddcfc65e3955ba2a6e4d8e0404
• focused pandas/Polars CPU receipt: 1,935 passed, 32 skipped, 159 cuDF-selected cells deselected
• first local run additionally passed 2,079 cells; its only 7 failures were cuDF parameters blocked by absent local libnvrtc.so.12
• ./bin/lint.sh: clean (Ruff, type-hygiene, comment-density, relative-import gates)
• ./bin/typecheck.sh: 336 source files clean
• pre-rebase guarded DGX canary covered cuDF/NVRTC/Polars-GPU; the rebase was content-preserving and the review fix is comment-only
• authoritative post-rebase status is the GitHub Checks panel

Review resolution

1. EndpointFrameT stays: it preserves the caller's pandas/cuDF/Polars frame flavor across the runtime dispatcher; DataFrameT intentionally models pandas during type checking. Commit 696327559 adds the guard-compliant one-line explanation.
2. Keep fixed-length, non-DISTINCT whole-node bag semantics. Current Cypher documents plain RETURN and GQL-conformant RETURN ALL as equivalent and duplicate-preserving; DISTINCT performs deduplication.

Reviewer handoff

Exact state: rebased linear head 696327559297d8ddcfc65e3955ba2a6e4d8e0404 on master@190b802ba867081f253f21e5c22679de59f7e8f4.

Reviewer decisions:

1. Confirm fixed-length, non-DISTINCT whole-node results use binding-row multiplicity, while DISTINCT, variable-length, reentry, and relationship-free shapes stay excluded.
2. Review _AliasView field mapping for prefixed multi-entity Polars rows, including OPTIONAL-null entity markers and structured versus text rendering.
3. Confirm the seeded typed-hop fast path preserves the same bag and correctly declines the zero-row dtype corner to the full path.
4. Confirm the controls prove property projections and existing non-bag lanes did not move.

Safe local reproduction:

python -m pytest -q -k 'not cudf' graphistry/tests/compute/gfql/test_whole_entity_projection_bag_1994.py graphistry/tests/compute/gfql/cypher/test_lowering.py graphistry/tests/compute/gfql/test_alias_scoping_semantics.py graphistry/tests/compute/gfql/test_engine_polars_row_pipeline.py graphistry/tests/compute/gfql/test_hop_semantics_pins.py graphistry/tests/compute/gfql/test_row_multiplicity_semantics.py
./bin/lint.sh
./bin/typecheck.sh

Stack / landing

Position: #1999 is landed; #2000 is rebased directly on master. After #2000 lands, rebase successor #2001 onto fresh master before its own checks and merge.

Landing rule: merge commit only, exact-head guard, every check settled green, then ancestry verification. Do not delete this branch until dependent successor rebases are complete.

[lmeyerov]

This probably needs to get restacked on 1999 because likely conflicts

[lmeyerov]

Strange, clarify why we track else drop...

[lmeyerov]

Kept and clarified in 696327559. The TypeVar preserves the caller's exact pandas/cuDF/Polars frame flavor through the runtime dispatcher; DataFrameT intentionally models pandas during type checking, so replacing the signature with DataFrameT -> DataFrameT would erase Polars return precision. The declaration now carries a single guard-compliant constraint comment. Focused CPU, lint, and mypy are green.

[lmeyerov]

I can go either way here. What does gql do vs cypher ?

[lmeyerov]

Recommendation: keep the non-DISTINCT bag behavior. Current Cypher documents plain RETURN and RETURN ALL as equivalent, with ALL added for GQL conformance; its exact example returns the same node twice when two relationships bind it, while RETURN DISTINCT returns it once. That matches #2000: preserve binding-row multiplicity for fixed-length whole-node projection, and deduplicate only for DISTINCT. Official reference: https://neo4j.com/docs/cypher-manual/current/clauses/return/