fix(gfql): gate polars varlen node aliases by hop distance (refs #1741)

[lmeyerov]

Stacked on #1746 — review that one first; this PR's diff is only the chain half.

What this fixes

#1741: on the polars engine, MATCH (a {id: 'p0'})-[*1..2]-(b) RETURN b returned {p0, p1, p2} where pandas returns {p1, p2}. Silently wrong rows, not an error. After this PR both engines return {p1, p2}.

Root cause (corrected — the original write-up was wrong)

The first diagnosis said "polars lacks pandas' backtrack avoidance". Direct A/B refutes that: both engines return identical node sets and identical final _nodes; only the alias flag diverges.

The actual pandas rule is a hop-distance gate (compute/chain.py ~456-501): a node named after an edge op is aliased only when min_hop <= hop <= max_hop. The seed's hop label is null under an undirected walk, so it fails the gate and loses the alias. polars had no hop labels at all, so it could not run the gate — #1746 adds the labels, this PR adds the gate.

Implementation

• Auto-inject label_node_hops whenever an edge op is variable-length or output-sliced, mirroring ast.py:621-625 needs_auto_labels.
• Gate the alias by semi-joining against the [min_hop, max_hop] window in _apply_node_names.
• The hop distance travels with the wavefront, so it lands on the named node step's own frame, not the preceding edge step's. The gate reads it there. (This cost a debugging round — worth knowing if you touch it.)
• Also corrects the label rule under return_as_wave_front — the mode the chain always hops in. visited_nodes starts empty there, but pandas labels a backtracked-to seed null in both modes, so the undirected label-seen set is now pre-seeded with the seeds unconditionally.

Verification

• 4892 passed across graphistry/tests/compute/gfql + test_compute_hops.py + test_compute_chain.py.
• The 59 failures in that selection are byte-identical to origin/master's on the same environment (temporal / cudf / viz) — I ran the same selection on a detached master worktree and diffed the failure lists: zero new failures.
• 8 new tests pin the gate: pandas-parity across four varlen patterns, the backtracked seed explicitly, a negative case proving fixed-length hops are not gated, and a no-leak check on the injected column.

Residual gap (kept on #1741)

min_hops > 1 chains get no gate — requesting labels there would turn a currently-native chain into an NIE, since those labels come from the layered backward walk (hop.py:676-778), which is not yet ported.

Follow-up

Once this lands, #1742 closes unmerged — it was the interim honest-NIE decline for exactly this shape, and a raise is the wrong end state (per review feedback). Its test flips from "raises" to "matches the pandas oracle".

🤖 Generated with Claude Code

[lmeyerov]

Cross-engine validation on dgx-spark — 0 regressions, 70/98 mismatches fixed

4-engine differential sweep against pandas as oracle, 144 cases (4 hand graphs + 12 random graphs × 9 varlen/fixed patterns), run in-container on dgx-spark under safe_run.sh (RAPIDS 26.02, RMM 40GB, floor 20GB). Same box, same session, A/B against clean master c355660a.

build	pandas	cudf	polars	polars-gpu
master c355660a	144/144	144/144	79 ok / 49 wrong / 16 NIE	79 / 49 / 16
+ #1746 + #1747	144/144	144/144	114 ok / 14 wrong / 16 NIE	114 / 14 / 16

Set-diff of the two mismatch sets: 0 regressions, 70 fixed. polars and polars-gpu behave identically throughout, and cudf/pandas are untouched — confirming the change is confined to the polars lane.

The 28 residual mismatches (14 per polars engine) are all one shape, forward -[*2..3]->, where min_hops > 1 declines the hop label and so leaves the alias ungated. That is pre-existing on master — it shows up in the baseline column too — so this PR does not introduce it. Filed separately as #1748.

Raw JSON + the sweep script are committed in the campaign evidence set.

[lmeyerov]

Rebased to chain-only + collision-hardened

Two changes since the review:

1. Moved the hop-label correctness fix down to the base PR feat(gfql): native polars label_node_hops on the plain BFS (#1741 groundwork) #1746. The reviewer here noted this PR also carried a hop_eager.py pre-seed change; that (plus a label-column collision parity fix) now lives in feat(gfql): native polars label_node_hops on the plain BFS (#1741 groundwork) #1746, where the label feature is introduced. This PR's diff is now chain.py + its tests only — verified: git diff vs the feat(gfql): native polars label_node_hops on the plain BFS (#1741 groundwork) #1746 head touches exactly those two files.

2. Finding 2 (collision-safe column name) fixed. __gfql_chain_node_hop__ is no longer a raw literal fed to the hop as label_node_hops; it is resolved once per chain against the user's node columns via generate_safe_column_name, so a user column of that exact name can't be clobbered (which would otherwise crash the int/str compare in the gate). New test test_user_column_named_like_the_auto_label_is_not_clobbered.

3. Finding 1 (retitle + pin the gap). closes #1741 → refs #1741. The forward/reverse min_hops>1 alias remains ungated (silently-wrong, pre-existing on master) — filed as polars chain: forward/reverse varlen with min_hops>1 returns nodes outside the hop window (silent wrong) #1748 and pinned here with strict xfail tests (test_fwd_rev_min_hops_gt_one_alias_matches_pandas_KNOWN_GAP) so it flips to a hard CI failure the moment polars chain: forward/reverse varlen with min_hops>1 returns nodes outside the hop window (silent wrong) #1748 is fixed.

Full polars chain suite: 1000 passed, 2 xfailed, ruff clean. Cross-engine A/B (all 4 engines, dgx-spark) re-run below.

[lmeyerov]

Now leaves ZERO silent-wrong shapes (adapted the closed #1742's mechanism for #1748)

Rather than discard the closed #1742 (which declined the undirected-varlen-alias shape), its decline pattern is adapted here to the one shape this PR's hop-gate can't yet cover: a node named after a forward/reverse min_hops>1 edge. Those labels come from pandas' layered backward walk (not ported), so the alias would run ungated and tag nodes outside the [min_hop, max_hop] window — previously silently-wrong (#1748). It now raises an honest NotImplementedError.

Precise, not blunt — differential vs pandas (15 graphs × fwd/rev × named/unnamed):

• 30/30 named shapes → decline (NIE)
• 30/30 unnamed shapes (no alias to mis-gate) → run natively and match pandas
• 0 silent-wrong, 0 over-decline

4-engine cross-engine sweep on dgx-spark, before → after this commit:

	pandas	cudf	polars	polars-gpu
#1747 hop-gate only	144/144	144/144	114 / 14 wrong / 16 NIE	114 / 14 / 16
+ #1748 decline	144/144	144/144	112 / 0 wrong / 32 NIE	112 / 0 / 32

The xfail pins flipped to positive assert-raises tests. Net: the whole #1741 stack is now silent-wrong-free on the polars chain — every unsupported shape is an honest error, every supported shape matches pandas. Raw: xeng-1748.json in pyg-bench #91.

[lmeyerov]

extern to a symbols.py?