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

[abbaseya]

Summary

Adds the anchored bucketing layout as an extra pass beside the existing packed walk, selected per experience by the served experience.version field: version > 11 → anchored; version ≤ 11 / missing / non-numeric → packed (bit-for-bit as today).

This is a breaking change to the cross-SDK bucketing contract (v12) but ships INERT — the backend currently stamps every experience version 11, so no served experience triggers the anchored path until a separate backend bump to 12. Hash, seed (9999), scaling, stored-decision guard, forced-variation path, and event payloads are all unchanged.

Under the anchored layout each variation occupies a band anchored to its cumulative position, so raising an experiment's total traffic admits new visitors at each arm's own edge instead of relocating existing assignments (fixes the packed-layout reallocation defect). The JS SDK is the cross-SDK parity oracle; equality is proven by a shared golden-vector fixture.

Changes

• AnchoredBucketing.swift — new anchored selector + allocation builder (config-order allocations, isNaN/absent → 100.0, active/inactive with weight-preserving zero-width inactive arms, half-open [anchor, anchor+width)), a faithful port of the JS reference.
• BucketingManager.swift — new bucketVersionGated version-gated entry point; packed eligible builder now defaults an omitted/NaN traffic_allocation to 100.0 to match the JS packed builder (the only packed-path change; the accumulate-first-wins walk is untouched).
• ExperienceManager.swift — selectVariation now routes bucketing through bucketVersionGated (sticky short-circuit still precedes it, so stored-decision precedence is unchanged).
• Tests + the 59-vector cross-SDK golden fixture (cross-sdk-bucketing-vectors.json, shared verbatim across all Convert SDKs).

Tests

• swift test → 337/337 passing.
• AnchoredBucketingParity → 59/59 golden vectors (19 v11 packed-regression + 40 v12 anchored) — AC7.
• AC1 gate branching, AC4/AC5 boundaries & defaults, AC9 event-shape — passing.
• Existing cross-SDK HashParity (74 cases) green unchanged; packed path bit-identical for version ≤ 11 (AC6).
• SwiftLint --strict: 0 violations.

Notes

• No OpenAPI spec — SDK-internal behavioral change gated on a config field the served config already carries; no API endpoint added or modified.
• This SDK pass is independent of the other SDK passes — consistency is enforced solely by the shared golden-vector fixture, not by merge sequencing.

Coordination

The backend's next CURRENT_EXPERIENCE_VERSION bump to 12 MUST be the anchored-rollout bump (an unrelated bump to 12 would activate anchored prematurely). Safe deploy order is SDK-first.

[gemini-code-assist]

Code Review

This pull request introduces the anchored bucketing layout (contract v12+) via the new AnchoredBucketing module, gates its usage in BucketingManager based on the experience version, and updates ExperienceManager to route through this version gate. It also adds extensive test suites and JSON fixtures to ensure cross-SDK parity and boundary correctness. The review feedback suggests simplifying the allocation logic in AnchoredBucketing to improve consistency and readability, as well as removing redundant nil-coalescing operations in BucketingManager by directly utilizing the guaranteed non-nil selectedId.

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]

Approved ✅

Reviewed the anchored bucketing layout end-to-end and it holds up:

• Anchored algorithm is correct — recomputed the golden bands by hand (thirds 15%/25%, stopped-arm stability, NaN-default, ta:0 zero-width, total-weight-zero); all match, including the total ≠ 100 "sliver" growth and the half-open [anchor, anchor+width) edges.
• Cross-SDK parity confirmed — cross-sdk-bucketing-vectors.json is byte-identical (sha256 9993d0e6…83dd1b) to the JS reference in convertcom/javascript-sdk#414, the version gate matches (experience.version > 11), and the port mirrors the JS _buildVariationAllocations / getBucketRanges / selectBucketAnchored line-for-line.
• Determinism preserved — MurmurHash3, seed, and the stored-decision short-circuit are untouched; the anchored path re-derives the bucket value byte-for-byte identically to the packed path, and the event shape (one .bucketing, segments: nil) is unchanged.
• Gate coverage is complete — every production path (runExperience(s), and runFeature(s) via FeatureManager) routes through ExperienceManager.selectVariation → bucketVersionGated; nothing bypasses it.
• Anchored layout ships inert — it can't activate while the backend stamps CURRENT_EXPERIENCE_VERSION = 11.
• Ran swift test locally (Swift 6.2.3): 337 tests / 67 suites pass, 0 failures, including the 59-vector parity sweep and the AC gate/boundary suites.

Nice work on the sha-pinned shared fixture and the parameterized suites. ✅