Add hop-prioritized graph transformer sequences

[yliu2-sc]

Summary

• Adds an opt-in prioritize_hop_order mode for k-hop graph transformer sequence construction.
• Preserves the existing sparse reachable-node ordering by default.
• When enabled, fills truncated sequences in hop order: anchor, 1-hop neighbors, then 2-hop neighbors.
• Rejects prioritize_hop_order=True with PPR sequence construction because PPR already uses weight ordering.

Efficiency

• Builds sparse adjacency once and reuses sparse frontier expansion.
• Avoids dense (batch_size, num_nodes) hop-distance state.
• Retains only visited (batch, node) keys, current frontier, and output sequence tensors.
• Exits early once all anchor sequences have filled max_seq_len.

Efficiency vs. existing k-hop path

The default k-hop implementation is unchanged. It computes the full sparse reachable set for each anchor up to hop_distance, then lays out/truncates that set into max_seq_len. That path is simple and sparse-matmul dominated, but it may still materialize reachable nodes that are later dropped by sequence truncation.

The new prioritize_hop_order=True path keeps the same sparse-adjacency/sparse-matmul shape, but expands one hop frontier at a time and stops expanding batches once their sequences are full. This avoids any dense (batch_size, num_nodes) hop-distance matrix and keeps persistent extra state to the current frontier, visited (batch, node) keys, and the (batch_size, max_seq_len) outputs.

Worst-case time is still sparse expansion dominated, with some extra per-hop bookkeeping/sorting for deterministic hop-local ordering. In the common tight-max_seq_len case, it can be cheaper than the existing path because it avoids carrying/laying out reachable nodes that cannot be selected.

Validation

• Added transform coverage for hop-prioritized truncation under tight max_seq_len.
• Added paired default-mode coverage to show existing ordering remains unchanged.
• Added incoming-edge hop-order coverage, encoder pass-through coverage, and PPR validation coverage.
• Ran direct smoke coverage, py_compile, targeted ty, make format_py, make check_format_py, and git diff --check.

Notes

• Broader unit-test entrypoints were blocked locally by missing optional/build dependencies: cmake, graphlearn_torch, and torchrec.