feat: Full Stack v12 — safe traffic ramp-up, variation preview & experiment exclusion

[abbaseya]

Full Stack v12 — next major SDK release

This branch delivers three major capabilities, shipped consistently across all Full Stack SDKs. All three are inert until activated on the backend/UI side, so this deploys safely in any order.

1. Anchored (ramping) bucketing layout

Makes changing an experiment's total traffic allocation safe on a running experiment.

• Each variation is pinned at its own fixed offset (cumulative-weight anchor); its range width equals its allocation. Raising the total grows every arm at its own edge (even growth); lowering ejects evenly; nobody already bucketed gets reshuffled.
• Gated on the experience's existing serving version property: > 11 → anchored pass (contract v12); ≤ 11 / missing → packed pass, bit-identical to today. No schema change, zero migration.
• Hash, seed, stored-decision guard, forced path, and events are untouched. Still stateless, deterministic, and identical across every SDK — enforced by shared cross-SDK golden vectors.
• Changing variation weights mid-flight stays unsupported (unsafe in every layout); the split lock is unchanged.

2. Experiment preview

Lets users preview any variation — including drafts and paused ones — in their own environment, with zero trace.

• New debugToken config option (24h QA token) unlocks the full config, including draft/paused experiences.
• Stateless preview links (web) and deep links (mobile) via convert_preview={expId}.{varId} force a single variation with no side effects: no tracking events, no visitor-state writes, no impact on reporting.
• Rides the existing public serving primitive — no backend serving changes required.

3. Mutual exclusion / inclusion audience rule

Lets teams control which experiments a visitor can be in at the same time, through the normal audience-targeting rules.

• New audience rule bucketed_into_experience_key, resolved against SDK-stored bucketing state.
• negated: true → "NOT in experiment X" (mutual exclusion); default → "in experiment X" (inclusion).
• No new application inputs; evaluates before bucketing and composes identically with both packed and anchored layouts. Old SDKs fail closed.

Notes

• Backend registration of the new rule type and the version 12 stamp, plus the related convert-ui work (preview link/QR button, rule picker) and shared docs, are tracked and coordinated separately.
• Full existing test suites remain green; the anchored pass adds the shared golden-vector acceptance tests.

[gemini-code-assist]

Code Review

This pull request implements experiment-preview capabilities and mutual-exclusion rules (bucketed_into_experience_key) in the Convert Swift SDK, alongside support for the anchored bucketing layout (contract v12+). Key additions include a new PreviewState actor for in-memory preview memoization, a dedicated BucketingExclusion seam for whole-audience mutual exclusion, and zero-trace tracking/persistence hardening under preview. Additionally, a degrading audience decoding mechanism is introduced to prevent config-wide decode failures. A critical issue was identified in the audience decoding loop, where a decoding failure could result in an infinite loop because the container index is not advanced; a fix is suggested to safely advance the index on failure.

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]

Cross-SDK release review — ios-sdk #45

Reviewed at head 662d82d6, alongside javascript-sdk#418, ruby-sdk#43, android-sdk#56. Every claim below was read against the PR head; cross-repo claims were read on both sides.

Leading with the one I'd treat as a merge blocker: it changes bucketing on experiences running in production today, not behind the v12 gate.

1. 🔴 Packed path no longer excludes stopped variations

Sources/ConvertSwiftSDKCore/Bucketing/BucketingManager.swift:92-103 builds the packed eligible list filtering only on variation.id:

let eligible: [WeightedVariation] = (experience.variations ?? []).compactMap { variation in
    guard let key = variation.id else { return nil }
    ...
}

There is no variation.status check. The other three all drop non-RUNNING arms:

• JS _buildPackedBuckets — packages/data/src/data-manager.ts:592-597
• Ruby bucketable_variation? — lib/convert_sdk/data_manager.rb (return false if status && status != "running")
• Android buildPackedBuckets — BucketingLayoutResolver.kt (filter { it.status == null || it.status == VariationStatuses.RUNNING })

This SDK's own anchored path does apply it (AnchoredBucketing.swift:94-95), so only the packed path diverges. That matters because packed is the v11 path, and per the JS reference's own docstring (data-manager.ts:582-584) version 11 "is the version stamped on every experience currently served in production."

Worked example — O=10% running, V1=80% stopped, V2=10% running:

	bands
JS / Ruby / Android	O=[0,1000), V2=[1000,2000)
iOS (this PR)	O=[0,1000), V1=[1000,9000), V2=[9000,10000)

A visitor at bucket value 4957 gets no variation elsewhere and the stopped variation V1 here; one at 1500 gets V2 elsewhere and V1 here.

The comment at :86-91 cites parity with "the JS reference's packed builder … whose include filter at L568-572" — that JS filter chain is precisely where the status check lives.

Note the golden fixture can't catch this: its only v11 stopped-arm vector (total-weight-zero) has traffic_allocation: 0 on both arms, so it passes vacuously.

2. 🔴 Permanent audiences are re-evaluated for already-bucketed visitors

ExperienceManager.swift:340-375 (audiencePasses) resolves and evaluates every attached audience on every call — there is no audience-type check and no already-bucketed short-circuit in the gate itself. Searching the PR head's changed sources and the repo more broadly, the only occurrences of "permanent" are the generated ConfigAudienceTypes in ConfigSchemas.swift, the demo config, the OpenAPI spec, and the phrase "a permanent hang" in ConfigStore.swift — so as far as I can tell nothing implements it elsewhere either. Happy to be pointed at it if I've missed a call site.

JS filters permanent audiences out once the visitor is bucketed:

// packages/data/src/data-manager.ts:393-396
audiencesToCheck = audiences.filter(
  (audience) => !(isBucketed && audience.type === ConfigAudienceTypes.PERMANENT)
);

Ruby does the same in audiences_to_check (lib/convert_sdk/data_manager.rb:801), documented there as "decided behavior 2026-06-07".

Consequence: a bucketed iOS visitor is re-gated on every call, so a permanent audience that stops matching — a time window, a first-session audience, or simply attributes not re-supplied on a later runExperience call — evicts them from a running experiment mid-flight. That's the exact result-skew Safe Traffic Ramp-Up is meant to prevent. android-sdk#56 has the same gap.

3. A failed re-preview leaves the previous preview stuck

ConvertContext.swift:229-241 — the guard let ... else logs and returns without touching previewState, and PreviewState.swift documents the prior value as "simply left in place."

JS clears it on failure (context.ts:172/182/195, this._preview = null) and Android clears it (ConvertContext.kt:1187/1261/1279, previewState = null). Ruby matches iOS.

So: QA previews variation X, then opens a second shared link whose variation was deleted. JS/Android revert to normal decisions and resume tracking; iOS keeps forcing the old variation and keeps zero-trace suppression on for the context's whole lifetime — every conversion, bucketing event and visitor-state write silently dropped, with only a warn log.

4. The anchored version gate can't read a string-typed version

BucketingManager.swift:175 — guard let version = experience.version, version > 11 — reads the generated public var version: Swift.Double? (Sources/ConvertSwiftSDKCore/Generated/ConfigSchemas.swift). Plain Codable synthesis cannot decode a JSON string "12".

The other three deliberately coerce: Android's BigDecimalSerializer states it reads "a JSON number (or numeric string, for loose parity with JavaScript's Number(x) coercion)"; JS uses Number(); Ruby uses Float(x, exception: false).

Conditional on the backend ever emitting the string form — but three platforms were built defensively for it and this one wasn't, so the failure would be iOS-only and look like a decode bug rather than a gate miss.

5. Deleting the packed nil-allocation guard changed explicit-null semantics

:96-101 replaces the old guard let allocation = variation.traffic_allocation else { return nil } with a default of 100.0. For an absent field that's correct JS parity (isNaN(undefined) → include at 100). For an explicit JSON null it isn't: JS excludes the arm from the packed layout (data-manager.ts:598-602) and marks it weight-0/inactive in anchored (:629-636), while iOS, Android and Ruby all now treat null as 100 % / active.

The old guard was the only mobile-side behavior matching JS here, and nothing re-establishes it. No golden vector carries an explicit null.

6. [parity] Whole-audience exclusion override — matches JS, diverges from Ruby/Android

ExperienceManager.swift:358-368: when statefulLeaf(in: groups) finds a leaf, the whole audience resolves through BucketingExclusion.resolve and ruleManager.evaluate never runs — consistent with BucketingExclusion.swift's header and with JS (data-manager.ts:1336-1345).

Ruby (rule_manager.rb:145) and Android (RuleManager.kt:299-302) instead evaluate the leaf inline so siblings still count. Needs one cross-repo decision on which is normative; flagging identically on all four PRs.

7. Minor — audience evaluation lost its short-circuit

:358 eagerly maps every attached audience to a Bool before applying ANY/ALL at :371-374, so under the default ANY semantics every remaining audience's full rule tree is still walked after the first match. One-line fix preserving laziness:

matching_options == .all ? audiences.allSatisfy(evaluate) : audiences.contains(where: evaluate)

Android has the same regression (ConvertContext.kt:1455).

Test-gap note

CI is green on this head, but the shared cross-sdk-bucketing-vectors.json exercises none of: a v11 stopped arm at nonzero allocation (item 1), an explicit-null traffic_allocation (item 5), or a string-typed version (item 4). Those three vectors would turn this review into a failing test.

_{Automated cross-repo review; every cited line read at the PR head SHA.}

[abbaseya]

Thanks Joseph — the packed-path catch (#1) was the most valuable of the set. iOS dispositions; fixes pushed in bee1a4a.

Fixed (bee1a4a)

• feat(epic-1): story 1 — Package Scaffolding & Two-Target Structure #1 🔴 Packed path doesn't exclude stopped variations. Added the status == nil || .running guard to the packed eligible builder, matching JS _buildPackedBuckets and iOS's own anchored statusActive. (For the record: main's packed builder also lacked it, so it was pre-existing rather than introduced on this branch — but it's a real JS-parity defect on the v11 path, so it's fixed.)
• feat(epic-1): story 3 — CI Pipeline: Build, Lint, Import-Guard & Coverage Gates #3 Failed re-preview leaves preview stuck. setPreview's failure path now calls clearForcedVariation() (JS parity).

Refuted (with evidence)

• feat(epic-1): story 2 — Port Protocols & Core Model DTOs #2 🔴 Permanent audiences re-evaluated → mid-flight eviction. Doesn't occur on iOS. selectVariation returns the sticky/stored decision before audiencePasses runs — a bucketed visitor is never re-gated, so no audience change can evict them mid-flight. The gate function reads as you described, but the caller short-circuits ahead of it. Same as android-sdk #56.

Intentionally not changed (reasons)

• feat(epic-1): story 4 — OpenAPI Config Type Generation & LCD-Sentinel Decode #4 version gate can't read a string version. The backend serves version as a JSON number (intval), which Double? decodes fine; the string case is hypothetical. Defensive coercion like the others' is a nicety, not a live issue.
• feat(epic-1): story 5 — Release Pipeline: Signed Tag → GitHub Release #5 packed nil-allocation → explicit-null semantics. Explicit null is never served (0 fixture occurrences); theoretical only.
• feat(epic-2): story 1 — Internal Event System (on/off/fire) #6 [parity] whole-audience exclusion override. Out-of-contract mixed-tree only; supported shape agrees across SDKs.
• feat(epic-2): story 2 — SDK Initializer, ConvertConfiguration & READY #7 audience eval short-circuit. Perf-only.

Test-gap note

Agreed — and a sharp catch that the fixture's only v11 stopped-arm vector has ta:0, so #1 passed vacuously. Adding a nonzero-ta stopped-arm vector (plus the others) to the shared fixture is queued as a coordinated follow-up.