feat(gfql #1650): structured flattened whole-entity returns

[lmeyerov]

Summary

Closes the core of #1650. Terminal Cypher RETURN a (whole node/edge) previously emitted one column of Cypher display strings built row-wise (({id: 51, val: 51, kind: 'a'})). That string is a presentation format (it matches the cypher-shell / TCK oracle), not data — callers had to re-parse it to use it, and constructing it is O(rows).

This flattens whole-entity returns into structured {alias}.{field} columns (a.id, a.val, a.kind, ...) by default. The per-field columns already exist on the working frame before projection, so this is "stop collapsing", not "rebuild": near-free, lossless, directly usable, and it survives JSON / CSV / Parquet / Arrow serialization and plot().

Performance (dgx-spark, median-of-7, RETURN a vs old text form)

	pandas @10k	pandas @100k	cuDF @10k	cuDF @100k
flat (#1650)	20.5 ms	32.1 ms	19.8 ms	26.6 ms
old text form	41.9 ms	204.2 ms	53.3 ms	113.5 ms
speedup	2.0×	6.4×	2.7×	4.3×

Win grows with row count (text render is O(rows); flat is ~free).

Design

• apply_result_projection(..., structured=True) emits flat columns for whole-entity returns; structured=False keeps the legacy single Cypher-display-string column. The OPTIONAL-MATCH null-fill / projection row-guard paths (which still consume a single-column entity value for row alignment) opt out via this flag and are unchanged.
• A synthesized null/absent-entity row (top-level OPTIONAL-MATCH miss or OPTIONAL WITH-reentry no-match, built by _apply_empty_result_row as a single {alias: None} column) has no field columns to flatten, so it falls back to the single-column text form — rendering to None and preserving the shape the OPTIONAL / reentry machinery consumes for identity recovery and no-match detection. Real rows always carry flat fields and flatten.
• Text is now presentation-only: render_entity_text(result, alias) reconstructs the Cypher display string on demand (used by the conformance/TCK driver and any caller wanting the human-readable form). The structured data path never pays the render cost.
• The entity-projection meta ids snapshot (.copy()) is retained — bounded reentry recovers carried node identities from it and must not alias the live frame ([BUG] Cypher reentry path mis-handles OPTIONAL prefix MATCH on no-match fixtures #1356).

Behavior change

Callers that previously read the rendered Cypher display string from a terminal RETURN a column now receive flattened a.* columns. Documented under [Development] › Changed in CHANGELOG. No programmatic consumer of the display string was found (graphistry server / louie serialize to flat JSON/CSV/Parquet).

Tests

• Whole-entity text assertions migrated to a entity_text_records shim that renders flat → text for comparison against the pre-GFQL: avoid spurious entity-text stringification of returned entities (return structured/Arrow frames) #1650 Cypher-text oracle.
• Grouping / connected-optional / null_fill paths (still single-column text) keep direct text assertions.
• Flat-shape + render-helper + projection-meta tests added.
• Full graphistry/tests/compute/gfql/ on dgx-spark (cuDF 25.12 container): 2509 passed, 16 skipped, 15 xfailed. The only 2 failures are pre-existing container-environment artifacts unrelated to this change (image's stale baked setup.py; a cugraph test that asserts "without cugraph" in an image that has cugraph).
• ruff-clean; mypy-clean for changed code.

Follow-ups (separate PRs, after this lands)

• tck-gfql conformance adapter: reconstruct the Cypher display string from flattened a.* columns at the comparison hook (paired-contract).
• pyg-bench probes: durable RETURN a structured-vs-text + where_rows micro-probes.
• Optional polish: unify the intermediate grouping/reentry value-eval onto structured (flat everywhere). Not required for the perf win; tracked as deferred.

🤖 Generated with Claude Code