SDK: client-side deterministic bucketing (assign locally from a signed config, no live round-trip)

[jean9ross]

Split from flame#17. That issue bundled two fixes: (1) parallelize the N+1 serial /assign loop — shipped — and (2) client-side deterministic bucketing. This tracks (2), the still-open half.

The gap

Even parallelized, the script-tag SDK still hard-depends on a live /assign round-trip to assign a visitor. A slow or failed API means the visitor can't be bucketed and sees control. The edge SDK (@cuped-io/flame-edge) already resolves server-side; this brings no-round-trip resolution to the script-tag path.

Scope

• A config payload carrying per-experiment variant weights (+ salt/seed), delivered up front (e.g. alongside /experiments/active, or a standalone signed config blob).
• Deterministic weighted bucketing client-side: stable hash of the user/device id → variant, matching the server's allocation so client and server agree on the assignment.
• Signature / integrity so the config can't be tampered with client-side.
• Fallback to the live /assign when no local config is present (backward compatible).

Origin: flame#17 (2026-07 platform audit, Phase 2 — SDK front door). The deeper half; parallelization shipped separately.

[jean9ross]

Cross-repo dependency + a contract ask for Mike

Client-side bucketing must produce bit-identical assignments to ember's server, or experiment data corrupts silently (visitor sees variant A, server attributes B). So this needs two things from ember:

1. Expose variant weights in /experiments/active. The client can't do the % total_weight → weighted CDF walk without per-variant weights, and flame's Variant type has no weight today. Please include weights in the active-experiments response — whatever payload shape you pick, flag it here and I'll add the field + parse it.

2. Treat the bucketing algorithm as a FROZEN SHARED CONTRACT, enforced by golden vectors. The port is only safe if ember's sticky_bucket (SHA256("{user_id}:{experiment_id}") → first 8 BE bytes → % total_weight → weighted CDF over sorted variants) doesn't change underneath it. I'm porting your sticky_bucket_golden_vectors + select_variant_weighted_cdf_golden_vectors into flame's tests so the TS port is provably identical. Going forward: if either side touches the algorithm, both golden-vector suites update in lockstep. Agree the algorithm + its vectors are the shared contract?

Our plan: building the algorithm port + golden-vector verification now (payload-independent, correctness-critical). The wiring (parse weights → bucket locally when present, /assign fallback otherwise) waits on your payload shape (#1) so we don't build against a guess.