perf(gfql): dispatch indexed fixed-hop bindings before the canonical traversal

[lmeyerov]

What

The resident-index fixed-hop path (rows(binding_ops=...) — the Cypher multi-alias MATCH … RETURN shape) was only consulted inside row materialization, after the engine had already executed the full canonical traversal. It therefore built its compact path bag on top of the graph-sized work it exists to avoid.

Both boundaries now ask the same shared, structural gate first:

• pandas / cuDF — _handle_boundary_calls (compute/chain.py)
• native Polars — chain_polars (gfql/lazy/engine/polars/chain.py)

Only when the helper can serve the whole middle exactly do they skip the canonical traversal and hand the compact state to the unchanged row materializer via an internal graph copy. A decline is memoized so the rows path does not re-attempt (or re-record) the same decision.

Engagement stays operator / index / dtype / cost based — no query, schema, or hop-count recognition. Seeded, prefiltered, policy-bearing, shortest-path, unsupported, and cost-gated shapes still fall back to canonical execution with identical results.

Also included:

• Indexed seed lookup covers {id, …extra scalar constraints} — gather the one indexed row, then filter it, instead of scanning the whole node table. Missing ids and non-matching constraints return the same empty result; duplicate-id graphs cannot build the index and are unaffected.
• Seeded typed-hop property projection keeps its fast path through trailing DISTINCT / ORDER BY / SKIP / LIMIT by delegating those plain frame ops to the canonical chain.
• Fix (pre-existing, cuDF): that projection applied the pandas rows-pivot artifact (int → float64, bool → object) on every engine, but cuDF's canonical pivot preserves source dtypes — so the fast path returned float64/object where cuDF's own canonical path returns int64/bool. The cast rule is now engine-aware; the dtype-class decline guard is unchanged.
• Empty edge-frame alias marker columns now follow each engine's own canonical column order (pandas first, polars appended).

Not in this PR

Engine.py AUTO source-native routing is unchanged — the deferred #1743 policy is deliberately out of scope, and the two tests that pinned it were dropped.

Tests

Standard-derived (LDBC-shaped; benchmark names appear only in test ids/comments), all comparing against the same-engine canonical path:

• exact value / order / dtype / index / schema parity, one trace decision per serve/decline, missing / stale / off index lifecycle, named-edge schema, policy hooks, shortest-path exclusion, exception propagation;
• no-canonical-traversal proofs for both pandas (ASTEdge.execute forbidden) and polars (_chain_traversal_polars forbidden);
• an unnamed-middle regression pinning the bypass gate — reverting the gate fails it on both engines;
• mixed int / float / bool / string / id projection dtype parity across pandas / polars / cuDF;
• test_out_of_shape_declines_with_parity reconciled: DISTINCT and ORDER BY … LIMIT moved to a new engages-with-parity case, since they are now served with proven parity.

Validation (dgx-spark, capped guard, read-only source)

• full CPU graphistry/tests/compute: 6232 passed, 1 failed — master's pre-existing test_chain_dask_edges
• cuDF lane (indexed + seeded fast-path files): 30 passed
• ruff: clean · mypy: 0 new errors vs master
• standard LDBC SNB SF1 interactive-short profile: the redundant two-hop typed-mask and 16-merge buckets disappear; profiled call 1263 ms → 106 ms (~11.9×), exact 19-row oracle preserved (diagnostic measurement, not a published comparison number)

🤖 Generated with Claude Code

https://claude.ai/code/session_01NxxTFpKiqA4FQa9Pjy8yR1