fix(hop): to_fixed_point saturation, edges-only node output, tracked-seed attributes (#1918)

[lmeyerov]

Stacked on #1919. Unblocks #1893 — this fixes F4, the case where that PR's own headline invariant was still false.

F4. The tfp+undirected wavefront strip decided seed retention by topology heuristics (component holds >1 seed, or the seed is on a cycle), while the bounded arm uses "was the seed re-encountered". #1892's F-02 patch fixed the resulting leak but never the drop. Now one rule serves every arm — keep a seed iff it is in matches_nodes — which let 72 lines of heuristics be deleted.

F1 node output was gated on self._nodes is not None, so edges-only graphs returned the full materialized table; the block is now unconditional. F2 labels are a left-join instead of an inner-merge, so a tracked seed keeps its attributes and dtypes. F3 dedups the undirected double-emission. F5 removes the label_seeds gate so a labeling flag no longer changes membership. F6/F7 a shared resolve_hop_bounds() gives polars the validation it lacked entirely; hops=None resolves to run-to-closure (released default-engine behavior, and the signature admits None). F8 the closure break is deferred while a finite bound is unmet, on both engines.

Anti-vacuity check — the mistake that hid F4 in the first place: the new pins produce 46 failures at base, and the widened test_hop_undirected_tfp_wavefront_matches_saturated_bounded fails at base on exactly the 3 unfiltered single-seed cells the old parameterization omitted.

Performance improved. Board hop path untouched (200k nodes/1M edges, 15 reps, 5 interleaved rounds — all within noise), and undirected tfp wavefront went 34.7 ms → 12.8 ms (−63%) from the removed itertuples walks. No board cell traded.

Pins: test_hop_semantics_pins.py 42 → 70, plus 102 new in test_hop_semantics_1918.py. Gates: full-tree failure set byte-identical (+133 passing, −3 xfail = un-xfailed #1787 cases), typecheck 329, ruff + guards clean, zero TCK regression.

Existing tests changed — four, each hand-adjudicated against an independent brute-force trail enumerator (validated first against the files' own unchanged controls). Two pinned the #1787 defect as the oracle: the file's own note already conceded the eccentricity prune "under-reports the one 3-trail" (0→4, 4→5, 5→6). One polars case was testing contradictory bounds against the shared hops=1 and silently exercising the wrong decline.

label_edge_hops polars decline: its stated reason is gone, but the gate stays. The decline cites pandas duplicating undirected edges under labels; re-running that differential over 2879 shapes gives 628 → 0 divergences. But hop_eager.py has no edge-label output path at all, so lifting it is now a feature with a clean pandas oracle to port against — the comment records this rather than removing the gate.

Honest residuals: F2 under min_hops>=2 still returns an attribute-less seed — there the label set is the rebuilt retained-path set and the restriction is load-bearing (widening it admits nodes with no retained incident edge, breaking 17/400 polars chain parity cases), so lifting it is a decision about the chain contract; pinned as a value test so the boundary cannot rot. Two pre-existing defects found and left unfixed (identical at base, so not regressions): unseeded return_as_wave_front gives NaN attributes to a node that exists in the node table, and the internal __gfqlhop__hop_0__ column leaks into output under min_hops>=2.

🤖 Generated with Claude Code

https://claude.ai/code/session_01MF7uRZLKZaD6Q9FGWSmyXi

[lmeyerov]

MERGE BLOCKER — the F4 fix aligned the two arms in the wrong direction. CI caught it via graphistry/tests/compute/test_hop.py::TestMultiHopForward::test_hop_fixedpoint_undirected_does_not_revisit_seed_via_same_edge, outside the gfql tree.

Fixture is the acyclic path a→b→c→d→e, seed {a}, undirected, return_as_wave_front=True. Measured on both commits:

	parent c6fc1fcda	this PR
to_fixed_point	{b,c,d,e} ✅	{a,b,c,d,e} ❌
bounded hops=4	{a,b,c,d,e} ❌	{a,b,c,d,e} ❌

Returning to 'a' on a path requires traversing edge ab twice. to_fixed_point was the arm enforcing no-edge-reuse; the bounded arm was already violating it. This PR made tfp agree with the broken arm.

The round-011 F4 diagnosis had it backwards. It observed bounded=[0,1,2] vs tfp=[1,2] on a 3-node path and assumed bounded was the reference — same shape as this test, and the same wrong conclusion. "Make X agree with Y" needs establishing which of X and Y is correct first; that step was skipped, by the probe and by me when I briefed the fix.

The deleted "topology heuristics" were a real contract, not heuristics. The "component holds more than one seed" rule encodes exactly the distinction pinned by the sibling test immediately below the failing one, test_hop_one_hop_undirected_keeps_rediscovered_seed_from_other_seed: with seeds {a,b} the answer does include 'a', because it is rediscovered from a different seed rather than by reusing its own edge. Both tests still pass that distinction today — seeds {a,b} correctly gives {a,b,c} on this PR.

Corrected direction: restore the tfp behavior and fix the bounded arm to stop reusing the departure edge, then re-derive the equivalence pin from a hand oracle rather than from either arm. F1/F2/F3/F5/F6/F7/F8 in this PR are unaffected and stand on their own evidence; only F4 needs reversing. Redirecting now.

[lmeyerov]

F4 reversed — and the reversal found the deeper answer. Blocker lifted.

What the bounded arm's defect actually was: return_as_wave_front=True returns encountered nodes, and walking back along your departure edge is the trip home, not a discovery. A seed is re-encountered only when a walk reusing no edge reaches it. to_fixed_point enforced that; the bounded arm asked only "did the BFS reach it", and BFS re-enters a seed at hop 2 by traversing its departure edge a second time. polars had no seed strip at all, so it shared the defect on both arms — which is why the first cross-engine probe looked consistent and pointed the fix the wrong way.

The 72 "topology heuristics" I had them delete were computing exactly the right thing. A seed is re-encountered by an edge-disjoint walk of some length iff another seed shares its component (the shortest path between them is simple, hence edge-disjoint) or it lies on a cycle. Both arms now intersect that with the reached set — exact for to_fixed_point, and a necessary condition for a bounded window, so it removes the backtracking class without ever dropping a seed a bounded window should keep. One implementation, both arms, module-level and id-sequence-based so pandas/cuDF/polars all call it with no to_pandas() bridge. Verified equal to brute-force edge-disjoint-walk enumeration on 6000 random multigraphs.

It also fixed a latent bug in the old helper: adjacency was a set of neighbours, so two parallel edges collapsed into one, both endpoints peeled as degree-1, and a seed on that length-2 cycle was wrongly dropped. Degree now counts edge rows. Pinned.

Pins re-derived from paper, not from either arm, with the enumeration in the docstrings. Two residues are pinned as value tests rather than prose: the rule is length-blind (5-cycle at hops=3 keeps a seed the oracle drops), and min_hops>=2 forward still yields an attribute-less seed.

Anti-vacuity at the true parent c6fc1fcda: 19 F4 cells fail for the right reason — [1] == [0,1], i.e. tfp correct and bounded keeping the seed — across both engines, plus the bounded-window and parallel-edge cells.

Two existing chain tests changed, and I verified the oracle independently before accepting it. test_hop_chain_2_undirected / test_hop_chain_2_end_undirected, raw-hop expectation only: [a,b,c] → [b,c] and [b,c,d] → [b,c]. On the path a-b-c-d, the edge-disjoint walks from a are a-b and a-b-c; returning to a needs edge ab twice. Ran it: both now return [b,c]. The chain expectations directly below were left unchanged and still keep the seed — correctly, because n({'n':'a'}) binds it, which is a different question from re-encounter.

Perf: the rule initially cost +43% on undirected single-hop wavefront; a one-edge window cannot backtrack, so it is skipped there. After that, 9 reps × 3 interleaved rounds at 200k nodes / 1M edges show every affected shape within noise. No board cell traded.

Gates: test_hop.py 61 passed (not edited); compute tree base 109 failed, 10347 passed → 107 failed, 10359 passed — zero new, the delta being the two tests round 1 broke. The gate was widened to the whole compute tree, since the narrow gfql-only list is exactly what let this through. TCK 4143 passed / 0 failed. ruff, mypy (329 files), hygiene, surface guard all clean.

[lmeyerov]

Round-005 test amplification / first formal mutation audit

Audited head f1c4e491c against merge base 42566a644; the base branch moved to 6ac9c22d3 (#1919's audit push) and is folded forward here (clean merge). Confirms the three previously-strict-xfailed boundaries (REDISCOVERY_XFAIL / TFP_EQUALS_BOUNDED_XFAIL) are now EMPTY sets — this PR flipped them: pandas parallel-edge cycle-helper collapse, the missing polars undirected-wavefront seed strip, and tfp==saturated-bounded, all green at head across the 581-cell matrix.

Verdict: SAFE TO LAND (no introduced defects) at 6f07f2953

NULL-endpoint probe battery (null-src/dst edges, null seeds; forward hop, undirected tfp; both engines) head-vs-base found exactly ONE divergence, and it is the intended fix: polars leading-undirected-tfp wavefront kept the seed at base (['a','b']) and now strips it (['b']), matching pandas and the hand-oracle (seed re-entry needs edge ab twice). Null endpoints stay inert on both engines, no NaN node synthesis, null seed matches nothing. cuDF parity spot-checked on the parallel-edge rediscovery oracle (['a','b','c'], tfp == bounded — shares the pandas kernel; cupy remains broken/out of scope on this box).

Mutation audit: 11 mutants, 11 caught (after 2 added killer cells)

All with pytest summary lines against the 581-cell matrix (test_hop_semantics_1918.py + test_hop_boundary_matrix.py + test_hop_semantics_pins.py).

• Caught outright: rediscovery-returns-none 42F; rediscovery-returns-all 42F; parallel-edges-collapse (the pre-fix set-based adjacency) 6F; self-loop-rule-off 2F; component-seed-rule-off 24F; negative-min-ok 4F; min-default-always-1 8F; polars-seed-strip-off 21F; min-bound-unmet-early-exit-off 4F.
• Two survived and were killed with new cells:
  1. min>max-check-off survived because the output_max < min_hops cross-check masked it — but an explicit wide output_max_hops=5 un-masks it into a silent EMPTY answer. Added min-gt-max-wide-output to _BAD_BOUNDS (2F verified).
  2. tfp-keeps-the-hops-bound survived two ways: every tfp pin saturated within the passed bound, and all 9 read sites of resolved_max_hops are not to_fixed_point-guarded — but the RESOLVER's own min>max cross-check makes it observable: to_fixed_point=True, hops=1, min_hops=2 must answer, not raise against a bound fixed-point never uses. Added test_f4_tfp_with_min_hops_does_not_trip_the_dead_hops_bound (1F verified), which also pins the pre-existing residual honestly: pandas currently IGNORES min_hops under to_fixed_point (same at this PR's base — category 2, listed) while polars declines the combination typed.
• Plus a plain saturation cell (hops=1, to_fixed_point=True reaches full closure).

New cells + anti-vacuity

4 new cells (2 killers above + the saturation cell + the residual pin). PR's own matrix: 83 of 581 cells fail at the merge base — the flipped boundaries are real fixes, not decorative flips; 498 base-passers are the previously-green matrix cells and controls. No swallow sites (the matrix asserts values, never skips on decline; the one xfail machinery present takes an explicit set, now empty).

Category 2 (pre-existing, listed)

• pandas ignores min_hops under to_fixed_point (polars: typed NIE) — pinned as-is so a change is deliberate; unchanged by this PR.

Engines

pandas + polars across the full matrix; cuDF spot-parity on the rediscovery oracle (dataframe kernel; cupy/libnvrtc.so.12 broken here, polars-gpu out of scope).

Gates

ruff clean; all three guards rc=0 from inside the worktree; mypy error set identical to base (4 pre-existing transitive); polars lane: both matrix files registered (test_polars_lane_completeness green); no new source files. Full graphistry/tests/compute: failure SET identical to the folded base (105 = 105, both diffs empty — 102 known env + the 3 GPU cells #1914 added).