perf(gfql): fuse the distinct-domain two-hop count into one polars lazy plan

[lmeyerov]

What

_execute_two_hop_count_fast_path (the polars MATCH (a {..})-[{..}]->(b {..})-[{..}]->(c {..}) [WHERE ..] RETURN count(*) lane) chained five eager ops, each its own lazy().collect(). Every intermediate materialized in full with all edge columns still attached, and nothing could push across an op boundary — profiled on the 20k graph-benchmark dataset the four-semi-join chain built a 199,939-row wide frame that the degree join immediately reduced to 120,586, with 88–96% of that query's wall time inside those collects.

The distinct-domain case now builds the same algebra as one lazy plan, collected once. New helper _two_hop_count_fused_polars; the eager code is untouched and remains the fallback.

The EQUAL-domain shape is not routed through the fused lane — deliberately

The equal-domain shape (equal node domains + equal edge match) takes a memoized degree-count branch (_two_hop_cached_equal_domain_degree_counts, cached on the caller's Plottable across calls). Routing it through the fused lane would trade a cross-call cache hit for a per-call replan. The gate is not reuse_single_edge_domain, and test_h3_fused_two_hop_count_never_reached_by_equal_domain_shape asserts the fused lane is not even called for that shape. What this PR does change for that shape is its MEMO-MISS branch — see "Equal-domain memo-MISS" below.

Shape enumeration

The outer gate (_two_hop_count_alias + _two_hop_count_binding_ops) is narrow: exactly 4 ASTCalls (rows(table='nodes', binding_ops=[n,e,n,e,n]) → with_([("__cypher_group__",1)]) → group_by(["__cypher_group__"], [(alias,"count")]) → select([(alias,alias)])) with both edges _is_connected_fast_single_hop. Probed end-to-end, these 13 shapes never reach either lane: ORDER BY, LIMIT, ORDER BY … LIMIT, count(a), count(DISTINCT a), a second RETURN item, -[]-, <-[]-, -[*1..2]->, -[r]->, 3-hop, same-path WHERE a.id < d.id, WHERE b.g IN [...], 1-hop. This is why there is no ordering/null-ordering contract to preserve here — test_h3_two_hop_count_fast_path_has_no_order_by_or_limit_surface pins it rather than inheriting the claim.

Within the served shape the fused lane declines (falls through to the eager code, which answers correctly):

• equal-domain — by design, see above
• pandas / cuDF — polars-only
• non-eager-polars frames (LazyFrame / non-polars) — schema probes on a LazyFrame warn and cost
• an edge column already named __in_count__ / __out_count__ — defensive; measured identical on polars 1.42, but name survival under projection pushdown is version-dependent and the eager twin is correct, so it hands back rather than bets

I did not find a shape the fused plan answers wrongly; both declines outside the equal-domain gate are conservative boundaries, not known-wrong cases.

Not a GPU change: like the eager code and the existing fused two-star lane, it collects on CPU polars for both polars and polars-gpu.

Correctness evidence

• Differential fuzz: fused vs forced-eager vs pandas oracle over 972 query shapes × 6 graphs = 5,832 comparisons, 4,815 with the fused lane engaged, 0 divergences. Graphs cover parallel edges, self-loops, duplicate node rows, null properties, null endpoints, string ids, empty edge sets, empty node domains.
• 25 new tests (engine-parametrized pandas / cudf / polars / polars-gpu where cross-engine): engagement, the equal-domain no-regression structural guard, a 9-case fused-vs-eager-vs-pandas differential, empty-match count = 0, both declines, degenerate bindings (node key sharing an endpoint column; source and destination bound to the SAME column), and the ordering-surface proof.
• Mutation-checked. Killed: in-arm group_by key swap (15 fails), degree-product sum→len (11), start-domain→end-domain (8), end-domain→middle-domain (7), product→sum (10), dedup parallel edges (5), out-arm edge frame swap (3), removing either decline (1 each), routing the equal-domain shape into the lane (2). Three mutants survived and are provably equivalent rewrites, not coverage gaps: dropping the middle semi-join on the out arm (the final inner join already restricts b to middle_ids), semi→inner on a .unique()'d single-column right side, and inner→left on the final join (null products drop out of sum, then fill_null(0)).
• Full graphistry/tests/compute suite, master arm vs this branch: failure sets are byte-identical (123 pre-existing failures, all local GPU-env artifacts reproduced on unmodified master), +25 passed / +15 skipped from the new tests. bin/lint.sh and bin/typecheck.sh clean.

Perf

dgx-spark, benchmarks/graphbench/matched_q1_q9 at pyg-bench 7e5ce3b (gb_queries.py md5 6e7ae268a5a41742587fcb87854b6e27, verified on the box — query text loaded, never re-typed), RAPIDS image graphistry/test-rapids-official:26.02-gfql-polars, --gpus all --network none, perf lock held, position-balanced K M S S M K × 2 = 12 slots per scale, RUNS=7 WARMUP=3, per-slot medians. Both build trees are frozen git archive exports whose only differing files are gfql_fast_paths.py and the test file.

scale	cell	master	this PR	delta	overlap	Kuzu (same session)	verdict
20k	polars distinct-domain	16.91 [15.9 16.6 17.2 18.1]	10.02 [9.2 9.9 10.2 10.3]	−40.7%	no	10.90 [10.82–10.96]	LOSE 1.55× → WIN 1.09×, a FLIP (non-overlapping both ways)
20k	polars equal-domain	2.44 [2.02–2.46]	2.30 [2.03–2.65]	−5.4%	yes	3.50	TIE = unchanged by this PR (see #1825 — this warm cell is not one-shot-honest)
100k	polars distinct-domain	68.04 [65.9 66.7 69.4 69.7]	37.96 [36.5 37.3 38.6 39.3]	−44.2%	no	84.73	win 1.25× → 2.23× (widens, not a flip)
100k	polars equal-domain	5.46	5.62	+3.0%	yes	9.62	TIE = unchanged by this PR (see #1825)

Baseline reconciliation (the check that makes the deltas transferable): the pandas arm, which this change cannot touch, reproduces the reference 20k board to +0.3% … +4.1% on all nine cells, and same-session Kuzu's distinct-domain cell lands at 10.90 ms vs the board's 10.93 — the harness matches. polars runs uniformly ~12–33% high against the board on this box (a loaded-host thread-pool offset both arms share), which is why the same-session distinct-domain win is 1.09× rather than the 1.30× a ratio-transfer onto the board's own polars baseline would give. The measured, same-session number is the one quoted.

All 18 (engine, query) cells at each scale: 0 row-count and 0 canonical-value divergences between arms.

Flag isolation (the lane's own rule: re-run a flagged sub-20 ms cell at high repetition before believing it). The 12-slot 100k screen produced one non-overlapping cell besides the distinct-domain one — an unrelated single-hop grouped-aggregate cell at −12.1% faster, on a query the fused lane is never even called for. Re-run in isolation, 8 slots, RUNS=31: that cell went −12.1% → +6.1%, ranges overlap = TIE (sign flipped — noise, exactly as the lane's README documents for a ~13 ms cell). Same run: equal-domain +3.0% → +3.8%, TIE, distinct-domain −44.2% → −44.8%, still non-overlapping (master 63.9–65.2, this PR 35.3–36.4).

GPU receipt — dgx-spark (NVIDIA GB10), image graphistry/test-rapids-official:26.02-gfql-polars, --gpus all, polars 1.35.2 / cudf 26.02.01 / cudf_polars 26.02.01, GPU collect probe green: the new tests run 40 passed, 0 skipped — every polars-gpu param and the cudf param actually EXECUTED rather than silently skipping. (On a CPU-only host those 15 polars-gpu params skip with an explicit reason; that is the stated coverage boundary, and this is the receipt that closes it.)

One disclosure: the measured stack tree and this branch differ by exactly one thing — two module-private constants were renamed TWO_HOP_* → _TWO_HOP_* (5 sites, identical string values) after the lane was already running. Nothing else differs.

Equal-domain memo-MISS: one lazy plan (added 2026-07-28)

_two_hop_cached_equal_domain_degree_counts eagerly materialized the whole filtered edge frame (every edge column still attached) and grouped it twice. Its MISS branch now builds both degree arms as ONE lazy plan (pl.collect_all over a shared filtered-edge sub-plan), so polars pushes the src/dst projection into the semi-joins. Same algebra, same values. The memo HIT returns before reaching it, so a warm call is untouched — measured, not assumed.

This is the branch a one-shot query, a rebound Plottable, or any future removal of the cross-call memo (#1825) actually runs.

dgx-spark, perf lock held, position-balanced A B B A B A A B slots per scale, per-slot medians, RUNS=21 WARMUP=5, arms differing by exactly this one file (md5s recorded in-container), rows and values identical on every arm:

scale	cell	without	with	delta	overlap
20k	equal-domain memo-MISS	10.94 [10.24–11.10]	8.25 [7.65–8.71]	−24.5%	no
100k	equal-domain memo-MISS	48.27 [47.65–48.89]	33.13 [32.68–33.66]	−31.4%	no
20k	equal-domain one-shot (fresh Plottable)	12.19 [11.89–13.12]	9.18 [8.30–9.46]	−24.7%	no
100k	equal-domain one-shot (fresh Plottable)	49.67 [48.28–50.71]	34.62 [33.60–35.07]	−30.3%	no
20k / 100k	equal-domain memo-HIT	1.84 / 5.41	2.14 / 5.84	—	yes → TIE
20k / 100k	distinct-domain one-shot	9.35 / 36.68	8.83 / 36.71	—	yes → TIE
20k / 100k	bind_only control	0.02 / 0.02	0.03 / 0.02	—	yes → TIE

test_h3_equal_domain_two_hop_count_memo_miss_matches_memo_hit pins it: memo engagement is asserted via the memo attribute (absent before, one entry after), and the cold answer, the warm answer and a never-warmed Plottable's answer must all equal the pandas oracle.

Re-verified on dgx (RAPIDS 26.02, --gpus all, polars 1.35.2): full graphistry/tests/compute/gfql 6201 passed, 25 skipped, 19 xfailed, 0 failed; ruff clean; mypy over the whole package adds 0 new errors vs the same tree without this change.

Lock-in

tests/test_gfql_two_hop_fused_engagement.py in pyg-bench (self-merged there): a structural probe, not a timing gate — a growth-ratio or wall-clock gate polices the wrong direction for a constant-factor plan fusion and would keep passing after the lane silently stopped engaging. It asserts the distinct-domain shape is served by the fused lane, the equal-domain shape never enters it, and fused == eager == pandas — on the board's own gb_queries.py text. Verified to fail loudly (3 tests) against a pre-change build.

Correction (2026-07-28): that pre-existing probe covers fused-lane ENGAGEMENT only — it does not cover the memo-MISS widening described above, as an earlier revision of this section implied. A second lock-in now does: tests/test_gfql_two_hop_memo_miss_lazy.py (pyg-bench #118, merged) asserts that a memo MISS reaches polars.collect_all with both degree arms in one plan, and that a memo HIT never reaches it at all. 4 pass on this build; 1 fails against a pre-change build.

Independently re-measured under pyg-bench's own harness (dgx-spark, all three perf locks held, box verified quiet, slots A B B A B A A B, RUNS=21 WARMUP=5, per-slot medians, board query text md5 6e7ae268a5a41742587fcb87854b6e27, arms differing by exactly one file):

cell	master	this PR	verdict
20k distinct-domain warm	15.01 [14.80–15.46]	8.87 [8.76–10.77]	WIN −40.9%
20k equal-domain memo MISS	10.78 [10.72–11.21]	8.73 [7.68–9.31]	WIN −19.0%
100k distinct-domain warm	62.96 [62.79–63.36]	35.77 [34.36–36.19]	WIN −43.2%
100k equal-domain memo MISS	47.75 [47.42–47.95]	32.73 [32.46–32.95]	WIN −31.5%
memo HIT (20k / 100k)	—	—	TIE (ranges overlap)

Two things stated rather than smoothed over: the deltas replicate but the absolute centers run ~10% below the numbers carried forward in this PR (a quieter box — so the ratio, not the center, is the transferable figure); and although the 20k memo-HIT cell is a TIE by the overlap rule, all four PR slots (1.58–2.40) sit above three of four master slots (1.22–1.40). Worth watching, not a loss. The 100k memo-HIT is clean noise.

Notes for review

• Merged with master (d0515d34) on 2026-07-28: gfql_fast_paths.py 3-way merged cleanly (rc=0, no markers) against master's fused single-hop grouped-aggregate lane; CHANGELOG.md was the only real conflict and was resolved by taking master's file and re-inserting this entry under ### Performance.
• Branched off master (233b64c8). PR perf(gfql): constant-fold literal-only sub-expressions at plan time (generalizes the toLower residual fix) #1800 is open against the same file but touches _RESIDUAL_TOLOWER_EQ at line ~617; this PR only adds a new function at ~1549 and rewires the dispatch at ~1997. The diffs are mechanically separate and either can rebase over the other.
• Typing: master's compute/typing.py has no PolarsFrame/PolarsT (PR refactor(typing): canonical polars frame vocabulary + is_polars_df TypeGuard (Wave 0) #1799 adds them and is unmerged), so this uses polars' own pl.LazyFrame / pl.DataFrame under TYPE_CHECKING, matching the existing fused two-star lane. No Any, no getattr/setattr, no bare list/Dict[str, Any].