Add typed channel quotas to distributed PPR sampler

[mkolodner-sc]

Summary

Adds typed-channel support to the distributed PPR sampler.

Previously, our PPR-based graph construction effectively collapsed heterogeneous graphs into a homogeneous-style PPR view. That gave us useful seed-to-neighbor relevance scores, but it also lost important information about how a node was reached: which edge types contributed to the PPR signal, and whether different relation paths should be treated differently.

This change keeps the benefits of PPR sampling while preserving edge-type structure through configurable traversal channels.

Motivation

For heterogeneous graphs, edge types often carry important semantic meaning. Collapsing all relations into one PPR traversal can blur together very different paths, even when those paths should provide distinct modeling signals.

Typed-channel PPR lets us preserve that information by running PPR over configured edge-type channels and emitting channel-aware edge attributes. This gives downstream models access to both:

• the overall best calibrated PPR relevance score
• per-channel scores
• per-channel presence indicators

So instead of only knowing “this neighbor is relevant,” the model can also learn which typed relation channels made it relevant.

What Changed

• Added typed_channel_quotas to PPRSamplerOptions.

  • Keys can be a single canonical edge type, e.g. ("user", "to", "item").
  • Keys can also be a tuple of canonical edge types to define one grouped traversal channel.
  • Values are positive top-k quotas for that channel.

• Added typed-channel validation and normalization in DistPPRNeighborSampler.

  • Rejects invalid channel keys.
  • Rejects non-positive quotas.
  • Rejects edge types that are not traversable or are label edge types.
  • Restricts typed PPR to heterogeneous sampling.

• Added per-channel PPR execution.

  • Builds one PPRForwardPush state per typed channel.
  • Each state traverses only the edge types allowed by that channel.
  • Overlapping channel frontiers share one-hop fetches to avoid duplicate RPCs.

• Added typed PPR merge logic.

  • Deduplicates candidates across channels.
  • Calibrates scores within each channel/seed pool.
  • Emits multi-column PPR edge attributes:
    [best_score, channel_scores..., channel_presence_bits...].

• Wired typed_channel_quotas through sampler construction.

Tests

Added unit coverage for:

• channel key normalization
• invalid quota/key validation
• channel traversal map construction
• shared fetches for overlapping channel frontiers
• typed merge calibration
• residual top-up behavior in typed PPR
• disabling residual top-up for typed PPR

[mkolodner-sc]

/unit_test

[github-actions]

GiGL Automation

@ 19:58:07UTC : 🔄 C++ Unit Test started.

@ 20:00:03UTC : ✅ Workflow completed successfully.

[github-actions]

GiGL Automation

@ 19:58:07UTC : 🔄 Python Unit Test started.

@ 20:02:41UTC : ❌ Workflow failed.
Please check the logs for more details.

[github-actions]

GiGL Automation

@ 19:58:09UTC : 🔄 Scala Unit Test started.

@ 20:06:48UTC : ✅ Workflow completed successfully.