[vazarkevych]

Summary

Adds consumption of the contextual-bandit payload, so a feature rule referencing a contextual bandit is evaluated with the per-segment variation weights the backend computed instead of being skipped.

Today such a rule is silently ignored: its variations ship under contextualVariations, and the evaluator skips on variations == null. Graceful degradation works as designed, but bandits do not function at all.

All the optimization stays server-side. The SDK only consumes ready weights: resolve the referenced definition, pick the leaf whose condition matches the user, apply its weights, and bucket through the normal mechanism.

Diff size note: 7.5k added lines look alarming, but only 389 lines land under lib/. The bulk is the shared contextualBandit conformance block embedded in test/test_cases/test_case.dart.

Scope

• Parse contextualBandits and encryptedContextualBandits from the feature payload.
• Resolve a rule's contextualBanditRef against the payload definitions.
• Leaf selection: evaluate each context's condition against user attributes, first match wins.
• Fallback: no matching leaf, or a missing/unparseable definition → leafId = -1 with the experiment's existing or equal weights.
• Surface leafId, variationWeights, and banditVersion on GBExperimentResult, but only when the user was actually hash-bucketed in (hashUsed && inExperiment) — a force-assigned exposure must not carry bandit metadata.
• New models: ContextualBandit, ContextualBanditContext, ContextualBanditDefinition, exported from the package entry point.

Two fixes found along the way

Both predate this work; bandits only surfaced them.

featuresAPIModelSuccessfully never fired for encrypted payloads. handleValidFeatures invoked the delegate only inside the plaintext branch, so encrypted deployments silently skipped refreshStickyBucketService(model) — sticky-bucket documents were never refreshed against a new payload. Now mirrored in the encrypted branch after a successful decrypt.

Sticky-bucket identifier scan skipped bandit rules. deriveStickyBucketIdentifierAttributes only collected a rule's hash/fallback attributes when it had a plain variations list, so bandit rules contributed nothing and sticky bucketing had no attribute to key on.

Reported weights match the assignment

The bandit learns from the reported weights, so they must be the ones the user was actually bucketed with. Beyond the JS SDK, and as in the Kotlin SDK:

• a rule with explicit ranges, which take precedence over weights in the bucketer, reports no bandit metadata;
• a leaf without a leafId, or whose weights the bucketer would replace (wrong length, sum outside 0.99–1.01, negative or non-finite), falls back to leafId: -1;
• the fallback reports the weights actually used: the rule's weights if valid, otherwise equal weights.

8 new tests in contextual_bandit_test.dart; 7 fail without this change.

Test plan

• New test/common_test/contextual_bandit_test.dart — 7 unit tests over the evaluator state matrix: matching leaf applies its weights and records metadata; no matching leaf falls back to -1 with equal weights; a ref absent from the payload leaks no metadata; first match wins when several leaves match; a malformed definition is swallowed and treated as no-bandit; contextualVariations without a ref still runs the experiment; a zero-coverage rule attributes no metadata to a non-bucketed exposure.
• New test/common_test/contextual_bandit_conformance_test.dart — runs the 35 shared conformance cases with a per-field diff, so a failure names the exact mismatch rather than just failing. All 35 pass.
• Regression tests for the encrypted-payload fix: the delegate fires exactly once with the original model in both the plaintext and encrypted branches, and stays silent when decryption fails.
• flutter test — 312 pass. One pre-existing flake in caching_manager_test (concurrent test files race on the shared temp cache directory); it passes in isolation 3/3 and also fails on current main, where 2 tests fail.
• dart analyze --fatal-infos — clean.
• dart format --output=none --set-exit-if-changed . — clean.

BREAKING CHANGE: feature rules with a contextualBanditRef were skipped before and now enroll users, so the values of those features can change after upgrading.

[andywhite37]

Please confirm contextual-bandit support and the proposed public models and exposure metadata are in scope for Flutter. This changes assignment behavior and also alters encrypted-payload callbacks. Record approval of that scope, or identify changes to split out, so review can proceed.

[vazarkevych]

Please confirm contextual-bandit support and the proposed public models and exposure metadata are in scope for Flutter. This changes assignment behavior and also alters encrypted-payload callbacks. Record approval of that scope, or identify changes to split out, so review can proceed.

Decisions:

• Scope: in scope. The JS SDK consumes contextual-bandit payloads (buildContextualBanditExperiment in core.ts), and the shared spec 0.9.0 has a contextualBandit section. This PR follows the JS behavior:
  • first matching leaf wins;
  • no matching leaf → leafId: -1 with the rule's weights (or equal weights);
  • a missing ref → aggregate weights and no metadata;
  • metadata only when the user was hash-bucketed into the experiment.
• Public models and exposure metadata: ContextualBandit, ContextualBanditContext, ContextualBanditDefinition, and leafId / variationWeights / banditVersion on GBExperimentResult, matching the JS field names. Carrying the metadata in the tracking plugin's event is left out, as in JS.
• Hardening beyond JS (new commit, mirroring the Kotlin SDK): the reported weights must be the ones the user was actually bucketed with, since the bandit learns from them. So:
  • a rule with explicit ranges (which override weights in the bucketer) reports no bandit metadata;
  • a leaf without a leafId, or with weights the bucketer would replace (wrong length, sum outside 0.99–1.01, negative or non-finite), falls back to -1 with the weights actually used.
• Assignment behavior: rules with a contextualBanditRef were silently skipped before; now they enroll users. Users of those features can therefore change value after upgrading, so this ships in 5.0.0 as feat!: (see Release plan #192).
• Encrypted-payload callbacks: kept in this PR. featuresAPIModelSuccessfully never fired for encrypted payloads, so sticky-bucket documents were not refreshed against a new encrypted payload. Bandit rules surfaced it, and it ships with them.
• Spec: this branch's test_case.dart is spec 0.7.2 plus the contextualBandit section; feat!: support saved group references v2 ($savedGroup) and align condition operators with the JS SDK #178 brings 0.9.0 without it. Whichever merges second takes the full cases.json 0.9.0. Both PRs together pass it in full, including the four bandit feature cases missing here.