High resolution fractional bucketing #1903

Background

The current fractional operation uses a 100-bucket system, limiting the smallest allocation to 1%. This is insufficient for high-throughput environments where 1% could represent millions of users. Use cases like gradual rollouts, precise A/B testing, and canary deployments require sub-percent granularity (e.g., 0.1% or 0.01%).

Proposal

Use math.MaxInt32 (2,147,483,647) as the maximum allowed weight sum, with pure integer arithmetic for bucket assignment. This replaces the current 100-bucket float-based approach.

The bucket calculation becomes:

bucket = (uint64(hashValue) * uint64(totalWeight)) >> 32

This provides effectively unlimited precision (up to ~0.00000005%), eliminates floating-point issues, and naturally guarantees that any variant with weight >= 1 receives traffic.

Constraints

• The sum of all variant weights must not exceed math.MaxInt32 (2,147,483,647)
• Weights must be integers

Cross-language notes

The intermediate product (uint32 hash * int32 totalWeight) must fit in a 64-bit integer. Java's signed long is the most restrictive, which is why MaxInt32 (not MaxUint32) is the limit. JavaScript requires BigInt for the multiplication.

API

No API changes. Existing fractional syntax is unchanged -- weights are just no longer limited to summing to 100.

Related

• Parent issue: [FEAT] Bucketing improvements in fractional targeting #1788
• ADR: docs(ADR): extends the fractional operator to support up to .001% distributions #1800

Note

This is a behavioral breaking change for existing configurations (bucket assignments will shift), but the API surface remains the same.