Allow balanced assignment in ConditionAutoTransfer if multiple cohorts match

[rasmi]

Added enableGroupBalancing option to ConditionAutoTransferConfig in the transfer stage. When enabled, participants matching multiple transfer groups with the same condition are balanced across target cohorts instead of always being assigned to the first matching group.

Motivation

In experiments with multiple cohort variants sharing the same eligibility condition (e.g., two cohorts with the same variable values, except in different order), the default first-match-wins behavior sends all participants to the first group. enableGroupBalancing distributes participants evenly by selecting the group whose target cohort has the fewest participants. This is sort of a hack, but useful nonetheless, as the default behavior may be undesirable in some cases.

Changes

utils/src/stages/transfer_stage.ts

• Added enableGroupBalancing?: boolean to ConditionAutoTransferConfig interface (defaults to false)
• Updated createConditionAutoTransferConfig factory to pass through the field

functions/src/participant.utils.ts

• Modified handleConditionAutoTransfer group selection logic:
  • When enableGroupBalancing is false (default): unchanged first-match-wins behavior
  • When enableGroupBalancing is true: collects all ready groups, fetches target cohort sizes, and picks the group with the fewest participants (first match as tiebreaker)

functions/src/cohort_definitions.integration.test.ts

• Added two integration tests:
  1. Balanced mode: 4 participants across 2 groups with identical conditions yields 2+2 distribution
  2. Default mode: same setup without flag yields 4+0 (all to first group)