feat!: fractional bucketing improvements

[leakonvalinka]

High-precision and nested fractional

This is a coordinated feature across flagd and all flagd providers.

• fractional now supports up to max-int32 total weight and 1/max-int32 resolution as described in the high-precision fractional bucketing ADR
• fractional now supports computed (nested JSONLogic) variants and weights as described in the fractional ADR
• Includes e2e tests from the flagd-testbed v3.1.0...v3.4.0 to validate consistent fractional bucketing across all provider implementations
• ⚠️ Pseudorandom hash assignments will change with this release due to changes in the hashing algorithm; update flagd and your providers to ensure fractional assignment is consistent across all workloads

Related PRs

Component	PR
flagd	open-feature/flagd#1909
java-sdk-contrib	open-feature/java-sdk-contrib#1740
js-sdk-contrib	open-feature/js-sdk-contrib#1501
python-sdk-contrib	#373
dotnet-sdk-contrib	open-feature/dotnet-sdk-contrib#622
flagd-schemas	open-feature/flagd-schemas#207

Warning
@toddbaert will coordinate the release across flagd and all providers. Do not merge without coordination.
@toddbaert will update the RPC mode tests accordingly once the associated flagd PR is merged and an up-to-date flagd-testbed image is available.

---

Original PR description

Related Issues

#360 and #359

Follow-up Tasks

Remove fractional-v2 and fractional-nested tags from RPC tests

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a significant enhancement to the fractional evaluation mechanism within the flagd provider. It focuses on improving the precision and reliability of fractional flag assignments by modernizing the underlying hashing and bucketing algorithms. The changes aim to enhance the accuracy and robustness of fractional flag evaluations, resolving a previously identified issue.

Highlights

• Refactored Fractional Bucketing Logic: The core logic for fractional evaluation has been refactored into a new helper function, _resolve_bucket_by, to improve modularity and clarity.
• Updated Hashing Algorithm: The hashing mechanism for fractional evaluation now uses an unsigned 32-bit MurmurHash3, enhancing precision and distribution.
• Implemented High-Resolution Bucketing: A new high-resolution bucketing mechanism has been introduced, utilizing bit-shifting operations instead of percentage-based calculations, which significantly improves the accuracy of fractional assignments.
• Added Weight Validation: A check has been added to ensure that the total fractional weight does not exceed MaxInt32 (2,147,483,647), preventing potential overflow issues.
• Expanded End-to-End Test Coverage: New end-to-end test filters (~fractional-v1, ~fractional-v2, ~fractional-nested) have been enabled across various test configurations to validate the new fractional evaluation feature.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request refactors and improves the fractional evaluation logic to support high-resolution bucketing. The changes include extracting logic into a helper function, using unsigned 32-bit hashes for better distribution, and adopting a more precise integer-based calculation for bucketing. The test configurations are also updated to reflect these changes. My review identifies a minor opportunity for improving maintainability by replacing a magic number with a named constant.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.91%. Comparing base (81de6ba) to head (f5301be).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #373      +/-   ##
==========================================
- Coverage   98.72%   95.91%   -2.82%     
==========================================
  Files           3       30      +27     
  Lines         157     1517    +1360     
==========================================
+ Hits          155     1455    +1300     
- Misses          2       62      +60     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[leakonvalinka]

There's still 1 failing test, but I'm not sure how to fix it because I don't know what exactly it should be testing in the first place. It's the invalid-fractional-weights.json case of the test_json_logic_parse_errors test, which has valid weights but previously invalid variant types.

[aepfli]

[q] shouldnt we also support this via rpc mode?

[leakonvalinka]

yes, we will, however it's not yet released in flagd, but @toddbaert is working on it. i will remove the fractional-v2 and fractional-nested exclusions once flagd is ready.

[toddbaert]

@leakonvalinka I fixed some conflicts, squashed and rebased on main. Only changes I made from yours was minor lockfile stuff, a small test update, and updating to the latest e2e suite.

[toddbaert]

Implementation is great. I will coordinate the release/merge.