@decocms/blocks 7.48.4 → 7.49.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks",
-  "version": "7.48.4",
+  "version": "7.49.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -56,6 +56,7 @@
     "./sdk/env": "./src/sdk/env.ts",
     "./sdk/fetchCache": "./src/sdk/fetchCache.ts",
     "./sdk/fetchTimeout": "./src/sdk/fetchTimeout.ts",
+    "./sdk/experiments": "./src/sdk/experiments.ts",
     "./sdk/flags": "./src/sdk/flags.ts",
     "./sdk/http": "./src/sdk/http.ts",
     "./sdk/instrumentedFetch": "./src/sdk/instrumentedFetch.ts",

package/src/cms/resolve.ts

@@ -1,6 +1,7 @@
 import { getMatchersOverride, getRuleOverrideId, hasMatchersOverride } from "../matchers/override";
 import { getMeter, MetricNames, withTracing } from "../middleware/observability";
 import { djb2Hex } from "../sdk/djb2";
+import { stickyDecide } from "../sdk/experiments";
 import { parseSegmentCookie, SEGMENT_COOKIE, type StoredFlag, trafficToPct } from "../sdk/flags";
 import { withInflightTimeout } from "../sdk/inflightTimeout";
 import { normalizeUrlsInObject } from "../sdk/normalizeUrls";
@@ -758,21 +759,20 @@ function evaluateVariantRule(
   // production concern (previews aren't cached), so skipping it here is fine.
   if (!meta || hasMatchersOverride(ctx)) return evaluateMatcher(rule, ctx);
 
-  // Reuse a decision already made this request so every resolve pass (page,
-  // shallow section-key, deferred) selects the same variant.
-  const already = ctx.flags?.find((f) => f.name === meta.name && f.pct === meta.pct);
-  if (already) return already.value;
-
-  const stored = parseSegmentCookie(ctx.cookies?.[SEGMENT_COOKIE]).find(
-    (f) => f.name === meta.name,
-  );
-  // pct === -1 marks a classic-deco segment without a fingerprint — honor it
-  // (stay sticky) instead of re-rolling. A stale fingerprint re-rolls.
-  const useStored = stored && (stored.pct === -1 || stored.pct === meta.pct);
-  const value = useStored ? stored.value : Math.random() < meta.traffic;
-
-  ctx.flags?.push({ name: meta.name, value, pct: meta.pct });
-  return value;
+  // Shared with sdk/experiments.ts' N-way resolution — same reuse / stay-sticky
+  // / re-roll precedence, so the two assignment paths cannot drift. This path
+  // keeps its own `trafficToPct` fingerprint: swapping it for the experiment
+  // weight hash would re-roll every live visitor on the next deploy.
+  return stickyDecide<boolean>({
+    name: meta.name,
+    fingerprint: meta.pct,
+    recorded: ctx.flags,
+    stored: parseSegmentCookie(ctx.cookies?.[SEGMENT_COOKIE]),
+    roll: () => Math.random() < meta.traffic,
+    // A matcher decision is always boolean; a string here means an experiment
+    // took the same cookie slot. Re-roll rather than coerce a variant id.
+    accepts: (v) => typeof v === "boolean",
+  }).value;
 }
 
 // ---------------------------------------------------------------------------

package/src/sdk/experiments.test.ts

@@ -0,0 +1,328 @@
+import { describe, expect, it } from "vitest";
+import {
+  type ExperimentConfig,
+  pickWeightedVariant,
+  readExperimentConfig,
+  resolveExperimentVariant,
+  weightsFingerprint,
+} from "./experiments";
+import {
+  parseSegmentCookie,
+  type StoredFlag,
+  segmentCacheToken,
+  serializeSegmentCookie,
+} from "./flags";
+
+type Payload = { collectionId: string };
+
+/** Contract 1's example document, verbatim. */
+const CONFIG: ExperimentConfig<Payload> = {
+  version: 1,
+  experiments: [
+    {
+      key: "plp-ranking",
+      variants: [
+        { id: "control", weight: 95, payload: { collectionId: "139" } },
+        { id: "model-b", weight: 5, payload: { collectionId: "412" } },
+      ],
+    },
+  ],
+};
+
+/** Same experiment after a ramp stage advances 5% -> 10%. */
+const RAMPED: ExperimentConfig<Payload> = {
+  version: 1,
+  experiments: [
+    {
+      key: "plp-ranking",
+      variants: [
+        { id: "control", weight: 90, payload: { collectionId: "139" } },
+        { id: "model-b", weight: 10, payload: { collectionId: "412" } },
+      ],
+    },
+  ],
+};
+
+/**
+ * One request: a cookie in, a fresh assignment sink, a fixed RNG sample.
+ * Mirrors what the framework threads through in production.
+ */
+function request(
+  config: ExperimentConfig<Payload> | null,
+  cookie: string | undefined,
+  rand: number,
+) {
+  const assignments: StoredFlag[] = [];
+  const resolve = () =>
+    resolveExperimentVariant<Payload>("plp-ranking", {
+      config,
+      segmentCookie: cookie,
+      assignments,
+      random: () => rand,
+    });
+  // The cookie the framework would write back (persistFlags merges the same way).
+  const nextCookie = () =>
+    serializeSegmentCookie([
+      ...parseSegmentCookie(cookie).filter((f) => !assignments.some((a) => a.name === f.name)),
+      ...assignments,
+    ]);
+  return { resolve, assignments, nextCookie };
+}
+
+describe("pickWeightedVariant", () => {
+  const variants = CONFIG.experiments[0].variants;
+
+  it("splits the range in proportion to the weights", () => {
+    expect(pickWeightedVariant(variants, 0)).toBe("control");
+    expect(pickWeightedVariant(variants, 0.94)).toBe("control");
+    expect(pickWeightedVariant(variants, 0.96)).toBe("model-b");
+    // 0.9999 must not fall off the end into `undefined`.
+    expect(pickWeightedVariant(variants, 0.9999)).toBe("model-b");
+  });
+
+  it("holds the distribution over many draws", () => {
+    let modelB = 0;
+    for (let i = 0; i < 10_000; i++) {
+      if (pickWeightedVariant(variants, i / 10_000) === "model-b") modelB++;
+    }
+    expect(modelB / 10_000).toBeCloseTo(0.05, 2);
+  });
+
+  it("handles N > 2 arms", () => {
+    const three = [
+      { id: "a", weight: 50, payload: {} },
+      { id: "b", weight: 30, payload: {} },
+      { id: "c", weight: 20, payload: {} },
+    ];
+    expect(pickWeightedVariant(three, 0.1)).toBe("a");
+    expect(pickWeightedVariant(three, 0.6)).toBe("b");
+    expect(pickWeightedVariant(three, 0.9)).toBe("c");
+  });
+
+  it("still splits proportionally when weights violate the sum-to-100 contract", () => {
+    const bad = [
+      { id: "a", weight: 1, payload: {} },
+      { id: "b", weight: 1, payload: {} },
+    ];
+    expect(pickWeightedVariant(bad, 0.25)).toBe("a");
+    expect(pickWeightedVariant(bad, 0.75)).toBe("b");
+  });
+});
+
+describe("weightsFingerprint", () => {
+  it("changes when a weight changes", () => {
+    expect(weightsFingerprint(CONFIG.experiments[0].variants)).not.toBe(
+      weightsFingerprint(RAMPED.experiments[0].variants),
+    );
+  });
+
+  it("is stable under variant reordering", () => {
+    const reversed = [...CONFIG.experiments[0].variants].reverse();
+    expect(weightsFingerprint(reversed)).toBe(weightsFingerprint(CONFIG.experiments[0].variants));
+  });
+
+  it("never collides with the legacy -1 sentinel", () => {
+    expect(weightsFingerprint(CONFIG.experiments[0].variants)).toBeGreaterThanOrEqual(0);
+  });
+});
+
+describe("resolveExperimentVariant — first assignment", () => {
+  it("assigns a fresh visitor and reports isFresh", async () => {
+    const { resolve, assignments } = request(CONFIG, undefined, 0.99);
+    const variant = await resolve();
+
+    expect(variant).toEqual({
+      experimentKey: "plp-ranking",
+      variantId: "model-b",
+      payload: { collectionId: "412" },
+      isFresh: true,
+    });
+    expect(assignments).toEqual([
+      {
+        name: "plp-ranking",
+        value: "model-b",
+        pct: weightsFingerprint(CONFIG.experiments[0].variants),
+      },
+    ]);
+  });
+
+  it("routes the majority of fresh visitors to the heavy arm", async () => {
+    const { resolve } = request(CONFIG, undefined, 0.5);
+    expect((await resolve())?.variantId).toBe("control");
+  });
+
+  it("returns null when no config is published", async () => {
+    expect(await request(null, undefined, 0.5).resolve()).toBeNull();
+  });
+
+  it("returns null when the key is not among the active experiments", async () => {
+    const other: ExperimentConfig<Payload> = { version: 1, experiments: [] };
+    expect(await resolveExperimentVariant<Payload>("plp-ranking", { config: other })).toBeNull();
+  });
+
+  it("resolves once per request even when several loaders ask", async () => {
+    const { resolve, assignments } = request(CONFIG, undefined, 0.99);
+    const [a, b] = [await resolve(), await resolve()];
+
+    expect(b?.variantId).toBe(a?.variantId);
+    expect(b?.isFresh).toBe(false); // only the first call assigned
+    expect(assignments).toHaveLength(1);
+  });
+});
+
+describe("resolveExperimentVariant — stickiness across requests", () => {
+  it("re-serves the stored variant without re-rolling", async () => {
+    const first = request(CONFIG, undefined, 0.99);
+    expect((await first.resolve())?.variantId).toBe("model-b");
+    const cookie = first.nextCookie();
+
+    // Next request: an RNG sample that WOULD have drawn "control".
+    const second = request(CONFIG, cookie, 0.1);
+    const variant = await second.resolve();
+
+    expect(variant?.variantId).toBe("model-b");
+    expect(variant?.payload).toEqual({ collectionId: "412" });
+    expect(variant?.isFresh).toBe(false);
+  });
+
+  it("stays sticky over many requests with adversarial RNG", async () => {
+    let cookie = request(CONFIG, undefined, 0.99).nextCookie();
+    const first = request(CONFIG, undefined, 0.99);
+    await first.resolve();
+    cookie = first.nextCookie();
+
+    for (const rand of [0, 0.2, 0.5, 0.94, 0.999]) {
+      const req = request(CONFIG, cookie, rand);
+      expect((await req.resolve())?.variantId).toBe("model-b");
+      cookie = req.nextCookie();
+    }
+  });
+
+  it("honours a classic-deco cookie that carries no fingerprint", async () => {
+    // pct absent -> parses as -1 -> must stick, not churn every legacy visitor.
+    const legacy = btoa(encodeURIComponent(JSON.stringify({ exp: { "plp-ranking": "model-b" } })));
+    const variant = await request(CONFIG, legacy, 0.1).resolve();
+
+    expect(variant?.variantId).toBe("model-b");
+    expect(variant?.isFresh).toBe(false);
+  });
+
+  it("re-rolls a visitor holding a variant that no longer exists", async () => {
+    const stale = serializeSegmentCookie([
+      {
+        name: "plp-ranking",
+        value: "model-z",
+        pct: weightsFingerprint(CONFIG.experiments[0].variants),
+      },
+    ]);
+    const variant = await request(CONFIG, stale, 0.1).resolve();
+
+    expect(variant?.variantId).toBe("control");
+    expect(variant?.isFresh).toBe(true);
+  });
+});
+
+describe("resolveExperimentVariant — re-roll once, then stick, when weights change", () => {
+  it("re-rolls on the ramp and re-sticks on the new weights", async () => {
+    // Assigned under 95/5.
+    const first = request(CONFIG, undefined, 0.99);
+    expect((await first.resolve())?.variantId).toBe("model-b");
+    const beforeRamp = first.nextCookie();
+
+    // Ramp to 90/10: the stored fingerprint goes stale -> exactly one re-roll.
+    const rerolled = request(RAMPED, beforeRamp, 0.5);
+    const afterRamp = await rerolled.resolve();
+    expect(afterRamp?.isFresh).toBe(true);
+    expect(afterRamp?.variantId).toBe("control"); // 0.5 lands in the 90% arm
+    const afterRampCookie = rerolled.nextCookie();
+
+    // Every subsequent request sticks — no second re-roll.
+    for (const rand of [0.99, 0.01, 0.5]) {
+      const req = request(RAMPED, afterRampCookie, rand);
+      const variant = await req.resolve();
+      expect(variant?.variantId).toBe("control");
+      expect(variant?.isFresh).toBe(false);
+    }
+  });
+
+  it("writes the new fingerprint so the re-roll cannot repeat", async () => {
+    const first = request(CONFIG, undefined, 0.99);
+    await first.resolve();
+
+    const rerolled = request(RAMPED, first.nextCookie(), 0.5);
+    await rerolled.resolve();
+
+    expect(rerolled.assignments[0].pct).toBe(weightsFingerprint(RAMPED.experiments[0].variants));
+  });
+});
+
+describe("deco_segment carries the assignment (contract 4)", () => {
+  it("stores the variant id under the experiment key", async () => {
+    const req = request(CONFIG, undefined, 0.99);
+    await req.resolve();
+
+    const payload = JSON.parse(decodeURIComponent(atob(req.nextCookie())));
+    expect(payload.exp).toEqual({ "plp-ranking": "model-b" });
+    // Boolean buckets stay untouched, so analytics reading `active` is unaffected.
+    expect(payload.active).toEqual([]);
+  });
+
+  it("coexists with a CMS boolean flag in the same cookie", async () => {
+    const withFlag = serializeSegmentCookie([{ name: "TestHero", value: true, pct: 50 }]);
+    const req = request(CONFIG, withFlag, 0.99);
+    await req.resolve();
+
+    const payload = JSON.parse(decodeURIComponent(atob(req.nextCookie())));
+    expect(payload.active).toEqual(["TestHero"]);
+    expect(payload.exp).toEqual({ "plp-ranking": "model-b" });
+    expect(parseSegmentCookie(req.nextCookie())).toEqual(
+      expect.arrayContaining([
+        { name: "TestHero", value: true, pct: 50 },
+        { name: "plp-ranking", value: "model-b", pct: expect.any(Number) },
+      ]),
+    );
+  });
+
+  it("folds into the CDN cache key so two variants never share cached HTML", async () => {
+    const a = request(CONFIG, undefined, 0.99);
+    const b = request(CONFIG, undefined, 0.1);
+    await a.resolve();
+    await b.resolve();
+
+    const tokenA = segmentCacheToken(parseSegmentCookie(a.nextCookie()));
+    const tokenB = segmentCacheToken(parseSegmentCookie(b.nextCookie()));
+    expect(tokenA).not.toBe(tokenB);
+  });
+
+  it("keeps the cookie byte-identical to today when no experiment is assigned", () => {
+    const flags: StoredFlag[] = [{ name: "TestHero", value: true, pct: 50 }];
+    const payload = JSON.parse(decodeURIComponent(atob(serializeSegmentCookie(flags))));
+    expect("exp" in payload).toBe(false);
+  });
+});
+
+describe("readExperimentConfig", () => {
+  const kv = (value: unknown) => ({ get: async () => value as never });
+
+  it("reads contract 1's document", async () => {
+    expect(await readExperimentConfig(kv(CONFIG), "www.farmrio.com")).toEqual(CONFIG);
+  });
+
+  it("returns null instead of throwing when the binding is missing", async () => {
+    expect(await readExperimentConfig(undefined, "www.farmrio.com")).toBeNull();
+  });
+
+  it("returns null on an unset key or a malformed document", async () => {
+    expect(await readExperimentConfig(kv(null), "www.farmrio.com")).toBeNull();
+    expect(await readExperimentConfig(kv({ version: 1 }), "www.farmrio.com")).toBeNull();
+  });
+
+  it("returns null when KV itself fails — never a thrown request", async () => {
+    const broken = {
+      get: async () => {
+        throw new Error("KV unavailable");
+      },
+    };
+    expect(await readExperimentConfig(broken, "www.farmrio.com")).toBeNull();
+  });
+});

package/src/sdk/experiments.ts

@@ -0,0 +1,314 @@
+/**
+ * Generic variant resolution — sticky, self-healing, N-way, and independent of
+ * where the variant list comes from.
+ *
+ * ## What this is
+ *
+ * Two layers, deliberately separable:
+ *
+ * 1. {@link stickyDecide} — the assignment *policy*, extracted from
+ *    `cms/resolve.ts`'s `evaluateVariantRule`: reuse the decision already made
+ *    this request, else honour the `deco_segment` cookie while its fingerprint
+ *    still matches, else roll fresh. Pure, synchronous, no CMS, no KV, no
+ *    cookies. The CMS multivariate path and this module both call it, so the
+ *    two cannot drift.
+ * 2. {@link resolveExperimentVariant} — the N-way experiment on top of it:
+ *    reads config from KV, draws from a weight vector, records the assignment
+ *    for the framework to persist into `deco_segment`.
+ *
+ * ## Self-healing re-roll
+ *
+ * The stored fingerprint is a hash of the *weight vector*. Change a weight (a
+ * ramp stage advancing 5% to 10%) and every stored assignment's fingerprint
+ * goes stale, so each visitor is re-rolled exactly once and then re-sticks on
+ * the new weights. The control plane never has to know this mechanic exists —
+ * hence "no fingerprint field" in the published config.
+ *
+ * ## Why not `sdk/abTesting.ts`
+ *
+ * That is a binary `"worker" | "fallback"` whole-request proxy for the
+ * migration period. Its bucket type, cookie, and fallback machinery are all
+ * two-way-specific. Only its `kv.get<T>(key, "json")` shape is borrowed here.
+ */
+
+import { djb2 } from "./djb2";
+import { parseSegmentCookie, SEGMENT_COOKIE, type StoredFlag } from "./flags";
+import { getRuntimeEnv } from "./otelAdapters";
+import { RequestContext } from "./requestContext";
+
+// ---------------------------------------------------------------------------
+// Layer 1 — the extracted sticky/re-roll core
+// ---------------------------------------------------------------------------
+
+/** Outcome of a sticky decision. `isFresh` is true when it was rolled now. */
+export interface StickyDecision<V> {
+  value: V;
+  isFresh: boolean;
+}
+
+/**
+ * Sticky assignment with self-healing re-roll, over any value type.
+ *
+ * Precedence: a decision already recorded this request (so every resolve pass
+ * agrees) then the stored decision, if its fingerprint still matches, then a
+ * fresh roll. `fingerprint === -1` on the stored decision marks a classic-deco
+ * segment written without the blocks extension: honour it rather than
+ * re-rolling, or every legacy visitor churns on first contact.
+ *
+ * @param name        Cohort identity — matcher block name or experiment key.
+ * @param fingerprint Current config fingerprint; a mismatch re-rolls once.
+ * @param recorded    Decisions already made this request (mutated: the new one
+ *                    is pushed onto it). Undefined disables both dedupe and
+ *                    persistence.
+ * @param stored      Decisions parsed from the visitor's cookie.
+ * @param roll        Draws a fresh value. Called at most once.
+ * @param accepts     Guards a stored value that is no longer valid — e.g. a
+ *                    variant deleted from the config. Rejected means re-roll.
+ */
+export function stickyDecide<V extends boolean | string>({
+  name,
+  fingerprint,
+  recorded,
+  stored,
+  roll,
+  accepts,
+}: {
+  name: string;
+  fingerprint: number;
+  recorded: StoredFlag[] | undefined;
+  stored: StoredFlag[];
+  roll: () => V;
+  accepts?: (value: V) => boolean;
+}): StickyDecision<V> {
+  const already = recorded?.find((f) => f.name === name && f.pct === fingerprint);
+  if (already) return { value: already.value as V, isFresh: false };
+
+  const prev = stored.find((f) => f.name === name);
+  const usable =
+    prev !== undefined &&
+    (prev.pct === -1 || prev.pct === fingerprint) &&
+    (!accepts || accepts(prev.value as V));
+
+  const value = usable ? (prev.value as V) : roll();
+  recorded?.push({ name, value, pct: fingerprint });
+  return { value, isFresh: !usable };
+}
+
+// ---------------------------------------------------------------------------
+// Layer 2 — experiments
+// ---------------------------------------------------------------------------
+
+/** One arm of an experiment, as published by the control plane. */
+export interface ExperimentVariant<P = unknown> {
+  id: string;
+  /** Integer share of traffic. Weights across an experiment must sum to 100. */
+  weight: number;
+  /** Opaque to the runtime — forwarded to the caller untouched. */
+  payload: P;
+}
+
+/** An active experiment. */
+export interface ExperimentDefinition<P = unknown> {
+  key: string;
+  variants: ExperimentVariant<P>[];
+}
+
+/**
+ * Frozen contract 1 — the document written to KV by the control plane's
+ * `EXPERIMENT_ACTIVE_PUBLISH`, keyed by hostname. Only *active* experiments
+ * appear: status and time-window logic live in the control plane, so the
+ * runtime does no date math and parses no status.
+ */
+export interface ExperimentConfig<P = unknown> {
+  version: number;
+  experiments: ExperimentDefinition<P>[];
+}
+
+/** Frozen contract 2 — what a caller gets back. */
+export interface ResolvedVariant<P = unknown> {
+  experimentKey: string;
+  variantId: string;
+  payload: P;
+  /** True when assigned on this request — a first visit or a re-roll. */
+  isFresh: boolean;
+}
+
+/** The slice of a KV namespace this module uses (mirrors `abTesting.ts`). */
+interface ExperimentKV {
+  get<T>(key: string, type: "json"): Promise<T | null>;
+}
+
+/** Default Workers binding holding the published config. */
+export const EXPERIMENTS_KV_BINDING = "EXPERIMENTS_KV";
+
+/** Bag key for the per-request config read, so N loaders share one KV get. */
+const CONFIG_BAG_KEY = "deco:experiments:config";
+/** Bag key for assignments made this request, drained by the cookie writer. */
+const ASSIGNMENTS_BAG_KEY = "deco:experiments:assignments";
+
+/**
+ * Fingerprint of a weight vector. Order-independent (the control plane may
+ * reorder variants without meaning to re-roll anyone) and never `-1`, which is
+ * reserved for "legacy cookie, no fingerprint".
+ */
+export function weightsFingerprint(variants: ExperimentVariant[]): number {
+  const vector = [...variants]
+    .map((v) => `${v.id}:${v.weight}`)
+    .sort()
+    .join("|");
+  return djb2(vector) % 1_000_000;
+}
+
+/**
+ * Draw a variant id from the weight vector. `rand` is a 0-1 sample.
+ *
+ * Weights are treated as shares of their own total rather than of a hardcoded
+ * 100, so a config that violates the sum-to-100 contract still splits traffic
+ * in the intended proportions instead of collapsing onto the first arm.
+ */
+export function pickWeightedVariant(variants: ExperimentVariant[], rand: number): string {
+  const total = variants.reduce((sum, v) => sum + Math.max(0, v.weight), 0);
+  if (total <= 0) return variants[0].id;
+
+  let cursor = rand * total;
+  for (const v of variants) {
+    cursor -= Math.max(0, v.weight);
+    if (cursor < 0) return v.id;
+  }
+  return variants[variants.length - 1].id;
+}
+
+/**
+ * Read the published config for a hostname. Mirrors `abTesting.ts`'s
+ * `kv.get<T>(key, "json")` shape. Returns null when the binding is absent, the
+ * key is unset, or the document is unusable — every one of which must mean
+ * "no experiment", never a thrown request.
+ */
+export async function readExperimentConfig<P = unknown>(
+  kv: ExperimentKV | undefined,
+  hostname: string,
+): Promise<ExperimentConfig<P> | null> {
+  if (!kv) return null;
+  try {
+    const config = await kv.get<ExperimentConfig<P>>(hostname, "json");
+    return Array.isArray(config?.experiments) ? config : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Explicit inputs, for tests and for callers outside a request context.
+ * Omitted fields fall back to the ambient {@link RequestContext} + Workers env.
+ */
+export interface ExperimentContext<P = unknown> {
+  /** Skips the KV read entirely when provided. */
+  config?: ExperimentConfig<P> | null;
+  kv?: ExperimentKV;
+  hostname?: string;
+  /** Raw `deco_segment` cookie value from the request. */
+  segmentCookie?: string;
+  /** Assignment sink; the cookie writer drains it. */
+  assignments?: StoredFlag[];
+  /** Injectable RNG — tests pass a fixed sample. */
+  random?: () => number;
+}
+
+/**
+ * Resolve this visitor's variant for `experimentKey`.
+ *
+ * Returns null when no active experiment matches — no config published, the
+ * key absent, or the experiment has no variants. Callers must behave exactly
+ * as they do today on null.
+ *
+ * The assignment is recorded for persistence into the existing `deco_segment`
+ * cookie under `experimentKey` (frozen contract 4); **the caller does not set
+ * cookies itself**. Because it lands in that cookie, the CDN cache-key folding
+ * already wired in `tanstack/sdk/workerEntry.ts` (`segmentCacheToken` to
+ * `__abf`) covers it with no change, and analytics that already read
+ * `deco_segment` see it for free.
+ *
+ * @example
+ * ```ts
+ * const variant = await resolveExperimentVariant<{ collectionId: string }>("plp-ranking");
+ * if (!variant) return vtexProductListingPage(props, req, ctx); // unchanged path
+ * props.selectedFacets = [
+ *   ...(props.selectedFacets ?? []),
+ *   { key: "productClusterIds", value: variant.payload.collectionId },
+ * ];
+ * ```
+ */
+export async function resolveExperimentVariant<P = unknown>(
+  experimentKey: string,
+  ctx: ExperimentContext<P> = {},
+): Promise<ResolvedVariant<P> | null> {
+  const config = ctx.config !== undefined ? ctx.config : await loadConfig<P>(ctx);
+  const experiment = config?.experiments.find((e) => e.key === experimentKey);
+  if (!experiment?.variants?.length) return null;
+
+  const stored = parseSegmentCookie(ctx.segmentCookie ?? ambientSegmentCookie());
+  const random = ctx.random ?? Math.random;
+  const { value: variantId, isFresh } = stickyDecide<string>({
+    name: experimentKey,
+    fingerprint: weightsFingerprint(experiment.variants),
+    recorded: ctx.assignments ?? ambientAssignments(),
+    stored,
+    roll: () => pickWeightedVariant(experiment.variants, random()),
+    // A variant retired mid-flight leaves visitors holding a dead id. Re-roll
+    // them onto a live arm instead of returning a payload that no longer exists.
+    accepts: (id) => experiment.variants.some((v) => v.id === id),
+  });
+
+  const variant = experiment.variants.find((v) => v.id === variantId) ?? experiment.variants[0];
+  return { experimentKey, variantId: variant.id, payload: variant.payload, isFresh };
+}
+
+// ---------------------------------------------------------------------------
+// Ambient request wiring
+// ---------------------------------------------------------------------------
+
+/**
+ * One KV read per request, shared by every caller, memoised on the in-flight
+ * promise so concurrent section loaders coalesce instead of racing.
+ */
+function loadConfig<P>(ctx: ExperimentContext<P>): Promise<ExperimentConfig<P> | null> {
+  const kv = ctx.kv ?? (getRuntimeEnv()?.[EXPERIMENTS_KV_BINDING] as ExperimentKV | undefined);
+  const hostname = ctx.hostname ?? ambientHostname();
+  if (!kv || !hostname) return Promise.resolve(null);
+
+  const cached = RequestContext.getBag<Promise<ExperimentConfig<P> | null>>(CONFIG_BAG_KEY);
+  if (cached) return cached;
+
+  const pending = readExperimentConfig<P>(kv, hostname);
+  RequestContext.setBag(CONFIG_BAG_KEY, pending);
+  return pending;
+}
+
+function ambientHostname(): string | undefined {
+  const request = RequestContext.current?.request;
+  return request ? new URL(request.url).hostname : undefined;
+}
+
+function ambientSegmentCookie(): string | undefined {
+  const cookies = RequestContext.current?.request?.headers.get("cookie");
+  if (!cookies) return undefined;
+  const match = cookies.match(new RegExp(`(?:^|;\\s*)${SEGMENT_COOKIE}=([^;]+)`));
+  return match?.[1];
+}
+
+function ambientAssignments(): StoredFlag[] | undefined {
+  if (!RequestContext.current) return undefined;
+  const existing = RequestContext.getBag<StoredFlag[]>(ASSIGNMENTS_BAG_KEY);
+  if (existing) return existing;
+  const fresh: StoredFlag[] = [];
+  RequestContext.setBag(ASSIGNMENTS_BAG_KEY, fresh);
+  return fresh;
+}
+
+/**
+ * Assignments recorded this request, for the framework's cookie writer.
+ * Empty when nothing was assigned — callers must not re-issue the cookie then.
+ */
+export function takeExperimentAssignments(): StoredFlag[] {
+  return RequestContext.getBag<StoredFlag[]>(ASSIGNMENTS_BAG_KEY) ?? [];
+}

package/src/sdk/flags.ts

@@ -23,6 +23,12 @@
  *   changes `traffic` and redeploys, the fingerprint no longer matches and the
  *   visitor is re-rolled once, then re-sticks — same self-healing scheme as
  *   {@link ./abTesting.ts}.
+ * - `exp` — `{ experimentKey: variantId }`, the N-way assignments written by
+ *   {@link ./experiments.ts}. `active`/`inactiveDrawn` are boolean buckets and
+ *   physically cannot hold a variant id, so string-valued decisions ride in
+ *   their own map. It is deliberately the same shape Deco Analytics consumes,
+ *   so pointing the collector at it later is a read, not a translation.
+ *   Their re-roll fingerprints share the `pct` map, keyed by experiment key.
  *
  * The cookie MUST be written un-encoded (raw base64) — OneDollarStats reads it
  * with `atob()` directly. Base64's `+ / =` are all valid cookie-value octets
@@ -35,11 +41,19 @@ export const SEGMENT_COOKIE = "deco_segment";
 /** A recorded flag decision: which named flag, the branch taken, and the
  *  `traffic` fingerprint (0–100) it was decided under. */
 export interface StoredFlag {
-  /** Matcher block name, e.g. "TestHero". Stable identity for the cohort. */
+  /** Matcher block name, e.g. "TestHero", or an experiment key, e.g.
+   *  "plp-ranking". Stable identity for the cohort. */
   name: string;
-  /** The branch the visitor was assigned to. */
-  value: boolean;
-  /** `round(traffic * 100)` at assignment time — the re-roll fingerprint. */
+  /**
+   * The branch the visitor was assigned to. A boolean for CMS multivariate
+   * matchers (the historical case); a variant id for N-way experiments.
+   */
+  value: boolean | string;
+  /**
+   * The fingerprint this decision was made under — `round(traffic * 100)` for
+   * a CMS matcher, a weight-vector hash for an experiment. A decision whose
+   * stored fingerprint no longer matches the current one is re-rolled once.
+   */
   pct: number;
 }
 
@@ -49,6 +63,8 @@ interface DecoSegment {
   inactiveDrawn?: string[];
   /** blocks extension: per-flag traffic fingerprint. Ignored by analytics. */
   pct?: Record<string, number>;
+  /** blocks extension: N-way experiment assignments, `{ key: variantId }`. */
+  exp?: Record<string, string>;
 }
 
 /** Convert a 0–1 traffic ratio to the 0–100 integer fingerprint. */
@@ -75,6 +91,9 @@ export function parseSegmentCookie(raw: string | undefined | null): StoredFlag[]
     for (const name of seg.inactiveDrawn ?? []) {
       out.push({ name, value: false, pct: pct[name] ?? -1 });
     }
+    for (const [name, variantId] of Object.entries(seg.exp ?? {})) {
+      out.push({ name, value: variantId, pct: pct[name] ?? -1 });
+    }
     return out;
   } catch {
     return [];
@@ -86,23 +105,34 @@ export function serializeSegmentCookie(flags: StoredFlag[]): string {
   const active: string[] = [];
   const inactiveDrawn: string[] = [];
   const pct: Record<string, number> = {};
+  const exp: Record<string, string> = {};
   for (const f of [...flags].sort((a, b) => a.name.localeCompare(b.name))) {
-    (f.value ? active : inactiveDrawn).push(f.name);
+    if (typeof f.value === "string") {
+      exp[f.name] = f.value;
+    } else {
+      (f.value ? active : inactiveDrawn).push(f.name);
+    }
     pct[f.name] = f.pct;
   }
   const seg: DecoSegment = { active, inactiveDrawn, pct };
+  // Omit `exp` entirely when unused so the cookie stays byte-identical to what
+  // sites emit today — an added empty map would re-issue every visitor's cookie
+  // on deploy and, via segmentCacheToken, cold-start every edge cache entry.
+  if (Object.keys(exp).length) seg.exp = exp;
   return btoa(encodeURIComponent(JSON.stringify(seg)));
 }
 
 /**
  * Stable token for the cache key — includes the `pct` fingerprint so a
- * `traffic` change lands cohorts in fresh buckets. Empty string when there are
- * no flags, so non-A/B pages keep sharing one entry.
+ * `traffic` (or experiment weight) change lands cohorts in fresh buckets.
+ * Empty string when there are no flags, so non-A/B pages keep sharing one
+ * entry. Experiment assignments fold in on the same footing as boolean flags:
+ * without that, two visitors on different variants would share cached HTML.
  */
 export function segmentCacheToken(flags: StoredFlag[]): string {
   if (!flags.length) return "";
   return [...flags]
     .sort((a, b) => a.name.localeCompare(b.name))
-    .map((f) => `${f.name}:${f.value ? "1" : "0"}:${f.pct}`)
+    .map((f) => `${f.name}:${typeof f.value === "string" ? f.value : f.value ? "1" : "0"}:${f.pct}`)
     .join(",");
 }