refactor(cypher): extract bounded-reentry runtime helpers (#987 Step 3)

[lmeyerov]

Summary

• Continues Cypher/GFQL: replace bounded reentry hidden-column handshake with an explicit ReentryPlan #987 (replace bounded reentry hidden-column handshake with an explicit ReentryPlan) — Step 3 (move runtime stitching into a dedicated reentry module).
• Pure-move refactor: bounded-reentry data-frame execution helpers move out of graphistry/compute/gfql_unified.py into a new graphistry/compute/gfql/cypher/reentry/execution.py module. No semantic change.
• gfql_unified.py shrinks by ~440 LOC, comfortably hitting the issue's "low-hundreds LOC reduction" success criterion.

What moved

To graphistry/compute/gfql/cypher/reentry/execution.py (new):

• compiled_query_reentry_state — whole-row carry dispatch state
• compiled_query_scalar_reentry_state — scalar-only prefix carry
• compiled_query_freeform_reentry_state — free-form intermediate MATCH (Cypher/GFQL: free-form intermediate MATCH after WITH (LDBC SNB IC3 endpoint) #1263 single-row)
• freeform_broadcast_row_to_nodes — single-row broadcast (also reused per-row in Cypher/GFQL: admit multi-prefix-row free-form intermediate MATCH runtime path #1285 multi-row)
• union_scalar_reentry_results — concat per-row dispatches
• apply_optional_reentry_null_fill — OPTIONAL re-entry null fill
• aligned_reentry_rows, reentry_carry_payload, ordered_reentry_start_nodes — supporting helpers
• reentry_validation_error + REENTRY_WHOLE_ROW_SUGGESTION, REENTRY_SCALAR_SUGGESTION constants

To graphistry/compute/gfql/cypher/result_postprocess.py:

• entity_projection_meta_entry — moved next to WholeRowProjectionMeta since it is shared by the connected-OPTIONAL-MATCH (_apply_optional_null_fill) and bounded-reentry whole-row paths.

What stays

• _execute_compiled_query_with_reentry (the dispatcher) stays in gfql_unified.py — it threads the recursive _execute_compiled_query call inside the orchestration loop, so moving it would require introducing a callback indirection. Out of scope for a pure-move slice.
• The leading-underscore names remain accessible as gfql_unified._compiled_query_reentry_state etc. via aliased re-imports, so existing tests that reach into graphistry.compute.gfql_unified continue to work without modification.

Pointers

• Compile-time contract: graphistry/compute/gfql/cypher/reentry_plan.py (introduced in PR feat(cypher): ReentryPlan + multi-whole-row prefix WITH (#989 slices 4.1+4.3a) #1248).
• Compile-time query rewrites: graphistry/compute/gfql/cypher/reentry/runtime.py (extracted in PR Refactor #1295: extract bounded reentry glue from lowering.py #1299; despite the name, this is compile-time).
• Data-frame execution: graphistry/compute/gfql/cypher/reentry/execution.py (this PR).

Test plan

• ./bin/pytest.sh graphistry/tests/compute/test_gfql.py -k reentry — 6 passed, 3 skipped (cuDF only)
• ./bin/pytest.sh graphistry/tests/compute/gfql/cypher/ — 1202 passed, 89 skipped, 15 xfailed
• ./bin/pytest.sh graphistry/tests/compute/test_gfql.py graphistry/tests/test_compute_chain.py graphistry/tests/compute/gfql/ — 1963 passed, 123 skipped, 15 xfailed
• ./bin/ruff.sh on touched files — clean
• ./bin/mypy.sh on touched files — clean
• Full CI suite (will run after flipping to ready)

🤖 Generated with Claude Code

[lmeyerov]

CI status: 1 failure inherited from master tip

After rebase onto 557acde0b (master tip), tck-gfql is failing on this PR. Same failure exists on the master commit itself:

• Master tip CI (557acde0b, PR #973: expand direct-Cypher varlen WHERE support beyond endpoint-only #1328): run 25471177793 / tck-gfql FAIL
• This PR's run after rebase: run 25471407240 / tck-gfql FAIL

Both fail the same scenario:

FAILED tests/cypher_tck/test_tck_runner.py::test_direct_cypher_xfail_contract[expr-pattern1-10]
AssertionError: assert 'success_wrong_rows' == 'GFQLValidationError'

This is a master-side TCK xfail-contract pin that needs updating after #1328 widened direct-Cypher varlen WHERE admission (the scenario that previously raised GFQLValidationError now succeeds with wrong rows). Not caused by this PR's pure-move refactor — AST signature parity for all 11 moved helpers was verified locally, and full cypher dir (1211 pass / 89 skip / 15 xfail) is green.

Holding merge until master is green again.