perf(gfql): serve seeded node lookups and two-alias projections on the fast paths - #2035

Ready for review at f8f2e73 (rebased on master after #2024/#2028; 77/77 checks green incl. tck-gfql, RTD green).

Hardening per the review bar (audit table in the private plan, reviews/pygraphistry-2035-hardening/audit.md):

• Every admission check in _execute_seeded_node_lookup_fast_path and the two-alias projection now has a pin on both sides: whole-row RETURN with a suffix, expression items, mixed whole-row + property items, LazyFrame nodes, requested engine ≠ frames' engine, and a destination-side extension dtype all decline to the full path with parity; seed-side extension and datetime columns keep parity; the scan reason (index_missing / served / index_stale) is visible in gfql_explain.
• One finding fixed here (explain.py): under index_policy="off" a served Cypher fast path was reported as used_index: True / index_selected; gfql_explain now derives used_index and the decision from index steps only and reports policy_off. Pinned on pandas / polars / cuDF.
• Cross-platform: dgx-spark, RAPIDS 26.02 image (cudf 26.02.01), lookup + typed-hop + engagement + latency-contract + index + indexed-bindings + polars-gpu suites: 727 passed / 0 failed / 1 opt-in skip. mypy clean on the changed file; no new Any/ignore/cast.
• pyg-bench lock-ins: the SNB point-latency sentinel (is1/is5/seeded-hop/node-only on pandas + polars, < 10 ms absolute, drift-gated vs the committed baseline that contains this PR) and the docs-numbers acceptance gate.

Suggested order after this: #2036 next (green; it is what keeps the #2028 scaling pin stable — a loaded runner just measured 30.6x vs the 30x bound on a branch without it), then #2037 → #2038 → #2040.

READY (f8f2e73): 77/77 checks + RTD; boundary audit above; real-GPU 727/0/1 opt-in skip; mypy clean; sentinel + acceptance gate lock-ins.

Fair challenge on "two projections". In the code, "two" was never a projection count: it meant the two node endpoints of the single hop, and the path already took any number of properties from either endpoint (an eight-property RETURN is served). The benchmark-shaped gap was real though: an edge-alias property (RETURN r.since) declined to the full path, and that is the natural n. Pushed in e2db9cb:

• the seeded typed-hop fast path now projects any number of properties from any alias of the hop (seed node, edge, destination node), one row per matched edge; edge properties keep their source dtypes like the full path;
• a projection that touches any non-destination alias takes the per-edge frame, so a no-match seed with an edge property projects an empty frame instead of reading node columns (a bug the new pins caught);
• pins: all three aliases, edge-only including endpoints, twelve properties across three aliases, parallel edges, no match; two hops and an absent edge property decline with parity;
• CHANGELOG wording now states the general contract rather than the IS1 shape.

What still declines by construction: anything beyond one hop (a different fast path's job) and anything with side channels (policy, WHERE, OPTIONAL). Local: fast-path + index + latency + lowering suites 548 + 1765 passed (the two cuDF t6 lowering failures are the dev-box libcublas environment, identical on master); ruff/guards/mypy clean, no new Any/ignore/cast. Real-GPU receipt for the new shapes follows on this PR. #2037/#2038/#2040 are restacked on this head.

Scenario review (include/exclude, per your note; matrix in the private plan reviews/pygraphistry-2035-hardening/scenarios.md): 16 shapes probed for served-or-declined plus fast-vs-full parity.

• EXCLUDE found and landed (7e3f983): an edge alias named like an edge column (-[type:HAS_CREATOR]-> on a frame with a type column), or a node alias named like a node column, now declines on every RETURN form. Before this, the projection's marker insert raised on pandas/cuDF where the full path serves; the polars full path has its own collision residual (gfql polars: an edge alias that collides with the edge column its own filter uses raises incompatible-column-type (pandas serves it) #2039/fix(gfql): polars chain re-executes steps on the graph's original edge columns (#2039) #2046). Pins on all three engines for filtered / projected / not-projected / whole-row.
• INCLUDE candidates, deferred as perf(gfql): seeded fast paths could admit single-alias WHERE predicates and LIMIT-only whole-row RETURNs #2048 (not needed by the SNB shapes, each reopens admission logic): single-alias WHERE on the seed or destination alias, and LIMIT-only whole-row RETURN. Both decline with parity today.
• Everything else (reverse direction, undirected, OPTIONAL, label-only seed, IN seeds, count, DISTINCT, string/bool/two-property seeds, null-valued seed, absent property, two hops) is served with parity or declines with parity.

Real-GPU at 37ada01: 766 passed / 0 failed; rerun on 7e3f983 in flight. #2037/#2038/#2040 restacked on this head.

Real-GPU receipt at 7e3f983 (dgx-spark, RAPIDS 26.02 image, cudf 26.02.01 / polars 1.35.2): lookup + typed-hop + engagement + latency-contract + index + indexed-bindings + polars-gpu suites = 784 passed, 0 failed, 1 opt-in skip. CI on this head and the restacked #2037/#2038/#2040 is running.

READY (7e3f983): 77/77 checks + RTD; real-GPU 784 passed / 0 failed; n-alias generalization, alias/column collision declines, scenario matrix (#2048 for the two include candidates). #2037 e08a059 / #2038 88ff625 / #2040 c4d2e9a restacked on this head, 75/75 each.

Quality pass per the review checklist, landed as aad106c:

• Error amplification: a random-shape differential (test_random_projection_shapes_match_the_full_path: random aliases, property subsets from seed/edge/destination, seed hit or miss, ORDER BY/LIMIT suffixes, indexed or not, 12 seeds × 3 engines) found one more real divergence: projecting an edge's endpoint binding (r.src) served the ids where the full path resolves an absent property (null). The fast path now declines those items (pinned). On polars, shapes the full path declares unsupported (NotImplementedError for the row-op select) are held to parity-or-error, and served shapes are checked against the pandas full path as the oracle.
• pyg-bench / contract: the latency contract gains the all-aliases shape (m.lastName, r.type, p.firstName) against a faithful two-lookup plain-frame floor: pandas 1.1×, polars 2.5×, cuDF 4.4× locally. The sentinel's IS1/IS5/hop/node-only routes are unchanged by the later commits, so the cdbcc64 baseline stands; the master re-measure covers the cells.
• DRY: the select-item admission loop is duplicated between the two fast paths; noted on perf(gfql): seeded fast paths could admit single-alias WHERE predicates and LIMIT-only whole-row RETURNs #2048 to fold with the WHERE-pushdown work rather than churn this PR again.

Suites: lookup + typed-hop + indexed-bindings + engagement + latency-contract + index + alias-scoping = 825 passed locally; guards/mypy clean. #2037 ab3a32e / #2038 6312e18 / #2040 ab74105 restacked. Real-GPU run of aad106c in flight; CI running.

Real-GPU receipt at aad106c (dgx-spark, RAPIDS 26.02 image, cudf 26.02.01 / polars 1.35.2): lookup + typed-hop + engagement + latency-contract + index + indexed-bindings + polars-gpu suites = 829 passed, 0 failed, 1 opt-in skip.

READY (aad106c): 77/77 checks + RTD; real-GPU 829 passed / 0 failed; random-shape differential + curated boundary pins on 3 engines; latency-contract pin for the all-aliases shape; #2037 ab3a32e / #2038 6312e18 / #2040 ab74105 restacked, 75/75 each.

READY + MERGING (7db7968) — owner-authorized after the round-002 test-amplification pass.

Round-002 (timeboxed 1–1.5 h, hypotheses not pre-constrained): a 90-cell differential matrix (30 shapes × pandas/polars/cuDF, default route vs fast paths disabled vs pandas oracle) over 13 hypothesis families (categorical / string / nullable dtypes, stale indexes, $param seeds, naming collisions, WITH/UNION/OPTIONAL/count/DISTINCT composition, parallel-edge multiplicity, policy force/decline, whole-row variants, seed value types, empty results). Found 2 new classes, both fixed here with pins:

• an empty projection kept the node id column at int64 where the full path widens it to float64 (no-match seed, destination label mismatch; pandas + cuDF)
• a whole-row RETURN on pandas next to a categorical column kept neighbouring bool/int columns narrow; the typed-hop lane now declines pandas extension-dtype frames (polars/cuDF keep parity and stay served)

Post-fix matrix: 0 DIFF / 81 parity / 9 both-raise (same exception class on both routes). Artifacts and probe outputs in the plan's rounds/round-002/.

Receipts at 7db7968

• CI: 77/77 check-runs success, incl. tck-gfql, changed-line coverage, polars-lane completeness and the three hygiene guards.
• Real GPU (dgx-spark, graphistry/test-rapids-official:26.02-gfql-polars, cudf 26.02.01 / cupy 13.6.0 / polars 1.35.2, safe_run): 865 passed, 1 skipped (opt-in wall-clock gate), 2 xfailed (recorded gaps) — +36 cells over the previous head's 829 with the same skip/xfail set.
• Local broad GFQL suite (graphistry/tests/compute/gfql + chain/hop): 12152 passed, 0 failed.
• mypy on the changed product files: no new errors vs master; no new Any / type: ignore / typing cast in product code.
• pyg-bench sentinel (snb_point_latency, SF0.1, dgx-spark release runner, pyg-bench main 5cf81ae, run snb-sentinel-7db7968f6-r1): every Cypher point served and within the gate vs the 2026-09-04 baseline (pandas IS1 1.97 ms vs 1.97; IS5 1.07 vs 1.05; seeded-hop props 1.03 vs 1.02; entity 3.03 vs 3.01; node-only props 0.59 vs 0.58; entity 2.47 vs 2.49; polars 1.7–5.3 ms, all ≤ baseline except node-only-entity 2.74 vs 2.26, inside the 1.5× gate). The three native op-list points read as regressions only because the baseline was measured at the perf(gfql): use resident seed indexes in native Polars chains #2038 head, which stacks perf(gfql): native chain seeds resolve through the resident indexes; named patterns served (#2027) #2037/perf(gfql): use resident seed indexes in native Polars chains #2038 on this PR; those lanes do not exist at this head and land next, after which the sentinel is re-run on master.

Restacked on this head with identical patch-ids: #2037 ff818e1, #2038 0664c3a (also drops a duplicated #2033 CHANGELOG bullet a union rebase had left), #2040 682c072.