feat(bucketing)!: anchored bucketing layout for ramping allocations (contract v12)

[abbaseya]

Summary

Adds the anchored bucketing layout as an additional selection pass beside the existing packed walk, selected per experience from the served config's version field: experience.version > 11 → anchored; version ≤ 11, missing, or non-numeric → packed, bit-for-bit as today. This is the Android SDK pass of a cross-SDK breaking change (bucketing contract v12) — a faithful sibling of the JS reference and the already-shipped Python, PHP, and Ruby passes.

Each variation is anchored to its own position in the allocation space, so raising or lowering an experience's total traffic allocation keeps every already-bucketed visitor on the same variation and admits/ejects visitors evenly at each arm's own edge (fixing the packed layout's "new band lands on the last variation" defect, Asana 1215457291725231).

Ships inert: the backend currently stamps every experience with version = 11, so no served experience activates anchored until a separate backend bump (out of scope). Hash, seed (9999), stored-decision guard, forced-variation path, and event payloads are all untouched.

What changed

• :packages:core BucketingManager — new anchored selector (getBucketRanges / selectBucketAnchored / getBucketForVisitorAnchored): totalWeight over all entries (active + inactive), totalWeight ≤ 0 → not bucketed, anchor = (cumWeight/totalWeight)·10000, width = active ? allocation·100 : 0, half-open [anchor, anchor+width). Reuses the frozen hash path unchanged.
• :packages:core BucketingLayoutResolver (new) — the version > 11 gate (BigDecimal.compareTo, mirroring JS Number(version) > 11), the allocation builder (keeps inactive arms at zero width; absent traffic → 100, explicit 0 → zero width never 100), the relocated frozen packed builder, and a single resolveVariationId seam.
• :packages:sdk ConvertContext — allocateAndRecord wired to the shared resolveVariationId seam (no divergent duplicate between runtime and tests). Sticky/stored-decision recall still short-circuits upstream — unchanged.

Tests (hard gate — all green)

• Cross-SDK golden vectors 59/59 (v11 packed × 19 + v12 anchored × 40), consumed verbatim from the shared fixture (sha256 9993d0e6…83dd1b) via a table-driven parameterized runner.
• AC1–AC9 acceptance 12/12 (gate branching, raise-is-superset incl. the exact 15%→25% table, lower-ejects-evenly-no-flip, stops/ta:0 zero-width, defaults/boundaries, packed regression lock, sticky precedence, no event/return-type drift).
• Packed regression lock (AC6): existing HashParityTest 69/69 and BucketingManagerTest 16/16 green unchanged; packed path is byte-identical for version ≤ 11.
• detekt clean; Kover coverage gates (core 85, sdk 70) pass.

Notes for reviewers

• No OpenAPI / serving-schema change — this is an SDK-internal behavioral change gated on a field the served config already carries.
• The golden-vector fixture is the immutable cross-SDK contract; if a vector ever fails, the bug is in the port, not the fixture.

Related sibling PRs: JS reference (javascript-sdk), Python (python-sdk#52), PHP, Ruby.

[gemini-code-assist]

Code Review

This pull request introduces the new anchored bucketing layout (contract v12) to the Android SDK, enabling version-gated layout resolution between the legacy packed cumulative walk and the new anchored layout. The core logic has been consolidated in the :packages:core module with the addition of BucketingLayoutResolver.kt, VariationAllocation.kt, and corresponding bucketing manager updates, which are fully validated by new acceptance and cross-SDK parity tests. Additionally, ConvertContext has been refactored to delegate to this shared resolution seam. The review feedback suggests a clean refactoring of buildPackedBuckets using mapNotNull to optimize sequence operations and eliminate an unsafe double-bang (!!) operator.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[JosephSamirL]

✅ Approve — faithful, byte-verified parity port of the anchored bucketing layout

Reviewed the full diff plus the surrounding runtime code and compared it line-by-line against the JS feat/anchored-bucketing-layout reference. No correctness defects.

Parity verified (against the JS reference, not just self-consistency)

• Fixture is verbatim — cross-sdk-bucketing-vectors.json is byte-for-byte identical to the JS packages/bucketing/tests/cross-sdk-bucketing-vectors.json source (sha256 9993d0e6…83dd1b), including the v11 ≡ v12 coincidence cases (single-arm, 100%-total).
• getBucketRanges matches JS bucketing-manager.ts exactly: totalWeight ≤ 0 → [], anchor = (cum/total)·10000, width = active ? alloc·100 : 0, cumulative weight over all entries (active + inactive) → the anchor-stability / raise-is-superset property.
• Anchor scale uses the fixed DEFAULT_BUCKETING_MAX_TRAFFIC constant, matching JS (DEFAULT_MAX_TRAFFIC, not the configurable maxTraffic).
• selectBucketAnchored is the identical half-open [anchor, anchor+width), first match in config order.
• buildVariationAllocations active flag equals JS _buildVariationAllocations for every backend-emitted shape (absent → 100/active, explicit 0 → inactive, stopped → inactive-but-weight-preserved).
• Gate wired to a real runtime field — ConfigExperience.version (@Contextual BigDecimal? = null) exists and defaults null → packed. (The golden test binds version to a test-only class, so the runtime field warranted separate confirmation.)
• Single bucketing seam — the only getBucketForVisitor* caller in src/main is ConvertContext.allocateAndRecord → resolveVariationId; experience.version is read nowhere else. Nothing bypasses the gate.
• Determinism preserved — getBucketForVisitorAnchored reuses getValueVisitorBased unchanged (seed 9999); the MurmurHash path is untouched (69-vector HashParityTest still green); the sticky / stored-decision recall (runExperience Step 3, resolveSticky(...)?.let { return it }) short-circuits before the gate and is byte-untouched by this diff, so an already-bucketed visitor never re-enters the layout switch.
• Ships inert — backend ExperienceService::CURRENT_EXPERIENCE_VERSION = 11, and the gate maps both 11 and missing → packed, so no served experience activates the anchored layout until the separate backend bump.
• Packed path frozen (AC6) — the new buildPackedBuckets is token-identical to the removed buildBuckets; clean removal, no dangling refs. Constants match JS (seed 9999, maxTraffic 10000).

One caveat on the version gate

The "non-numeric → packed" description isn't literally true on Android. BigDecimalSerializer coerces JSON numbers and numeric strings ("11"/"12" → parity with JS Number(x)), but a genuinely non-numeric version throws NumberFormatException → config decode failure, rather than JS's silent NaN → packed. This is unreachable in practice (the backend always stamps an integer, per the constant above) and is a pre-existing property of the shared @Contextual BigDecimal serializer used across every numeric config field — not introduced here. Flagging only so the parity guarantee reads precisely: numeric / numeric-string / missing → packed; alphabetic → decode failure, never the anchored path.

LGTM to merge into feat/fullstack-v12.