setupAB: correct isControl and carry edge fields on multi-arm tests

[MO-Thibault]

Summary

setupAB cannot express a split test with more than two arms. Three separate defects, all of which surface the moment a third variant exists. The More than two variants section of abTestAssignment.md already documents this as a supported shape, so today that documentation is wrong.

The concrete case: chess is running a three-arm test — production at 50%, skip1p at 45% carrying skipMatchers: ['1p'], and a 5% holdout — and the wrapper has to hand-roll the whole assignment because setupAB cannot hold it.

isControl treated every non-treatment arm as a holdout

const isControl = selected.id !== treatmentId;
if (isControl) { localStorage.removeItem("OPTABLE_RESOLVED"); /* + targeting cache */ }

A middle arm that still resolves EIDs was classified as control and had its cache cleared on every page load. That is wrong twice over: it corrupts the measurement, and because the session guard (OPTABLE_TARGETING_DONE, sessionStorage) survives the wipe, the user serves an empty cache for the rest of the session rather than re-resolving.

Now selected.id === controlId.

This is not a behaviour change for any current caller. With two variants the two predicates are the same test. All 17 templated bundles in optable-solutions pass exactly [{id:'production'},{id:'test',trafficPercentage:5}], and the documented custom-name example already passes controlId and treatmentId together.

skipMatchers was stripped off the variant

fillTrafficPercentages rebuilt each variant as {id, trafficPercentage}, discarding skipMatchers, skipResolvers and matcher_override. Those fields are the reason an arm would differ at the edge at all, and ABTestConfig already declares them.

Variants are now spread through, so the assigned variant can go straight into InitConfig.abTests — which is the only way skip_matchers reaches the edge, since targeting.ts reads it off determineABTest(config.abTests) and a top-level skipMatchers is inert.

The sticky read returned the stored copy, not the current config

Editing an arm's skipMatchers, or its weight, applied only to newly assigned users; anyone already holding that arm kept whatever was serialized at assignment time. The read now resolves the stored id against the current variant list and returns that entry, so config is the single source of truth for everything except the id. Unknown ids are still discarded.

New optableSplitTest flag

optableControlGroup only reaches the two arms named by controlId and treatmentId, so there was no way to hold a middle arm for QA. ?optableSplitTest=<id> forces a variant by id and takes precedence over optableControlGroup. An id absent from variants is ignored and assignment proceeds normally, so a stale flag cannot invent an arm.

Test plan

• 12 new cases in abTestAssignment.test.ts: three-arm assignment, cache retention for a middle arm, control still clearing its cache, skipMatchers passthrough and absence, config re-read over the stored copy, and the full optableSplitTest precedence chain. Existing cases are unmodified.
• pnpm test — 387 pass, 24 suites.
• pnpm build-lib and prettier --check lib/ clean.
• Distribution sanity outside the suite, 500k draws through the real setupAB with the chess config: 50.01% / 44.98% / 5.01%, zero null selections; skipMatchers present only on skip1p, isControl true only on the holdout.
• Consumer check: the chess bundle built against this branch and driven in headless Chrome with the edge stubbed, 44 assertions passing, including that the middle arm keeps its third-party EIDs across a page load and sends skip_matchers=1p.

Docs updated: abTestAssignment.md gains a section on variants that change what the edge resolves, states the isControl rule for multi-arm tests, and documents optableSplitTest; flags.md gains the new flag.

Release

Consumers need this on npm before they can use a third arm. Optable/optable-solutions#775 is waiting on it.

[MO-Thibault]

Unblocking note: Optable/optable-solutions#775 no longer waits on this. Chess now layers its third arm inside the production variant, which setupAB already treats as enabled, so it runs on 0.59.0 as published.

This is still worth landing on its own merits — it is what makes a genuine third variant work, stops skipMatchers being stripped off the variant, and lets optableSplitTest reach a middle arm. But there is no release pressure behind it now, so it can go at review pace.