@drip-apex/sdk 0.1.0 → 0.2.0

package/src/debug-loader.test.ts

@@ -0,0 +1,214 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { loadDebugBuild } from "./debug-loader";
+
+const originalDocument = Object.getOwnPropertyDescriptor(globalThis, "document");
+const originalLocation = Object.getOwnPropertyDescriptor(globalThis, "location");
+const originalLocalStorage = Object.getOwnPropertyDescriptor(globalThis, "localStorage");
+const originalWindow = Object.getOwnPropertyDescriptor(globalThis, "window");
+
+function installBrowser(search = "", persisted = false, nonce = "") {
+  const scripts: Array<Record<string, unknown>> = [];
+  const values = new Map<string, string>();
+  if (persisted) values.set("drip_debug", "1");
+  const appendChild = vi.fn((script: Record<string, unknown>) => {
+    scripts.push(script);
+    return script;
+  });
+  const documentValue = {
+    createElement: vi.fn(() => ({ async: true, dataset: {} })),
+    head: { appendChild },
+    documentElement: { appendChild },
+    currentScript: {
+      nonce,
+      getAttribute: vi.fn((name: string) => name === "nonce" ? nonce : null),
+    },
+  };
+  const locationValue = {
+    href: `https://shop.example.test/${search}`,
+    search,
+  };
+  const localStorageValue = {
+    drip_debug: persisted ? "1" : undefined,
+    getItem: (key: string) => values.get(key) ?? null,
+    removeItem: (key: string) => {
+      values.delete(key);
+      if (key === "drip_debug") localStorageValue.drip_debug = undefined;
+    },
+    setItem: (key: string, value: string) => {
+      values.set(key, value);
+      if (key === "drip_debug") localStorageValue.drip_debug = value;
+    },
+  };
+  Object.defineProperty(globalThis, "document", { configurable: true, value: documentValue });
+  Object.defineProperty(globalThis, "location", { configurable: true, value: locationValue });
+  Object.defineProperty(globalThis, "localStorage", { configurable: true, value: localStorageValue });
+  Object.defineProperty(globalThis, "window", { configurable: true, value: globalThis });
+  return { appendChild, scripts };
+}
+
+function restore(name: "document" | "location" | "localStorage" | "window", descriptor?: PropertyDescriptor) {
+  if (descriptor) Object.defineProperty(globalThis, name, descriptor);
+  else delete (globalThis as Record<string, unknown>)[name];
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+  restore("document", originalDocument);
+  restore("location", originalLocation);
+  restore("localStorage", originalLocalStorage);
+  restore("window", originalWindow);
+});
+
+describe("per-visitor debug build loader", () => {
+  it("activates from the configured query parameter and injects once", () => {
+    const browser = installBrowser("?apex_debug=secret");
+    const settings = {
+      enabled: true,
+      restrictMode: "query_param" as const,
+      queryParam: "apex_debug",
+      tokenRequired: true,
+    };
+
+    expect(loadDebugBuild(settings, "https://events.example.test/s/shop.js?env=staging")).toBe(true);
+    expect(loadDebugBuild(settings, "https://events.example.test/s/shop.js?env=staging")).toBe(true);
+    expect(browser.appendChild).toHaveBeenCalledTimes(1);
+    expect(browser.scripts[0]?.src).toBe(
+      "https://events.example.test/s/shop.js?env=staging&drip_sdk_variant=debug&drip_debug_token=secret",
+    );
+  });
+
+  it.each([
+    ["an empty token", "?apex_debug=", ""],
+    ["the default token", "?apex_debug=1", "1"],
+    ["an encoded token", "?apex_debug=a%2Bb%20c", "a%2Bb+c"],
+  ])("hands %s to the worker for validation", (_label, search, encodedToken) => {
+    const browser = installBrowser(search);
+
+    expect(loadDebugBuild({
+      enabled: true,
+      restrictMode: "query_param",
+      queryParam: "apex_debug",
+      tokenRequired: true,
+    }, "https://events.example.test/s/shop.js")).toBe(true);
+    expect(browser.scripts[0]?.src).toBe(
+      `https://events.example.test/s/shop.js?drip_sdk_variant=debug&drip_debug_token=${encodedToken}`,
+    );
+  });
+
+  it("puts debug parameters before a snippet URL fragment", () => {
+    const browser = installBrowser("?apex_debug=secret");
+
+    expect(loadDebugBuild({
+      enabled: true,
+      restrictMode: "query_param",
+      queryParam: "apex_debug",
+      tokenRequired: true,
+    }, "https://events.example.test/s/shop.js#install")).toBe(true);
+
+    const scriptUrl = new URL(String(browser.scripts[0]?.src));
+    expect(scriptUrl.searchParams.get("drip_sdk_variant")).toBe("debug");
+    expect(scriptUrl.searchParams.get("drip_debug_token")).toBe("secret");
+    expect(scriptUrl.hash).toBe("#install");
+  });
+
+  it("lets an unauthorized marker response initialize the live page exactly once", () => {
+    const browser = installBrowser("?apex_debug=wrong");
+    const settings = {
+      enabled: true,
+      restrictMode: "query_param" as const,
+      queryParam: "apex_debug",
+      tokenRequired: true,
+    };
+    const initializeLive = vi.fn();
+    const runLiveSnippet = (snippetUrl: string) => {
+      if (!loadDebugBuild(settings, snippetUrl)) initializeLive();
+    };
+
+    runLiveSnippet("https://events.example.test/s/shop.js");
+    expect(initializeLive).not.toHaveBeenCalled();
+    expect(browser.appendChild).toHaveBeenCalledTimes(1);
+
+    runLiveSnippet(String(browser.scripts[0]?.src));
+    expect(browser.appendChild).toHaveBeenCalledTimes(1);
+    expect(initializeLive).toHaveBeenCalledTimes(1);
+  });
+
+  it("falls back once when the debug script fails to load", () => {
+    const browser = installBrowser("?drip_debug=1");
+    const assignments: string[] = [];
+    const initializeLive = vi.fn(() => assignments.push("live-assignment"));
+
+    expect(loadDebugBuild({
+      enabled: true,
+      restrictMode: "query_param",
+    }, "https://events.example.test/s/shop.js", initializeLive)).toBe(true);
+
+    const script = browser.scripts[0] as { onerror?: () => void };
+    script.onerror?.();
+    expect(assignments).toEqual(["live-assignment"]);
+    expect(initializeLive).toHaveBeenCalledTimes(1);
+    expect(loadDebugBuild({
+      enabled: true,
+      restrictMode: "query_param",
+    }, "https://events.example.test/s/shop.js", initializeLive)).toBe(false);
+
+    script.onerror?.();
+    expect(assignments).toEqual(["live-assignment"]);
+    expect(initializeLive).toHaveBeenCalledTimes(1);
+  });
+
+  it("copies the current script nonce to the debug script", () => {
+    const browser = installBrowser("?drip_debug=1", false, "request-nonce-123");
+
+    expect(loadDebugBuild({
+      enabled: true,
+      restrictMode: "query_param",
+    }, "https://events.example.test/s/shop.js")).toBe(true);
+
+    expect(browser.scripts[0]?.nonce).toBe("request-nonce-123");
+  });
+
+  it("activates from persisted storage for a user-id restricted shop", () => {
+    const browser = installBrowser("", true);
+
+    expect(loadDebugBuild({
+      enabled: true,
+      restrictMode: "user_ids",
+      persist: true,
+    }, "https://events.example.test/s/shop.js")).toBe(true);
+    expect(browser.appendChild).toHaveBeenCalledTimes(1);
+  });
+
+  it.each([
+    ["absent config", undefined, "?drip_debug=1", false],
+    ["expired config", { enabled: true, restrictMode: "query_param" as const, expiresAt: "2020-01-01T00:00:00.000Z" }, "?drip_debug=1", false],
+    ["unparseable expiry", { enabled: true, restrictMode: "query_param" as const, expiresAt: "not-a-date" }, "?drip_debug=1", false],
+    ["off mode", { enabled: true, restrictMode: "off" as const }, "?drip_debug=1", false],
+    ["no opt-in", { enabled: true, restrictMode: "query_param" as const }, "", false],
+  ])("does not activate for %s", (_label, settings, search, persisted) => {
+    const browser = installBrowser(search, persisted);
+    expect(loadDebugBuild(settings, "https://events.example.test/s/shop.js")).toBe(false);
+    expect(browser.appendChild).not.toHaveBeenCalled();
+  });
+
+  it("aborts public live init before config fetch or event emission", async () => {
+    const browser = installBrowser("?drip_debug=1");
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+    const { init } = await import("./index");
+
+    const result = init({
+      shopId: "shop_123",
+      endpoint: "https://events.example.test/events",
+      snippetUrl: "https://events.example.test/s/shop_123.js",
+      runtimeFeatures: { sdkVariant: "live" },
+      debug: { enabled: true, restrictMode: "query_param" },
+    });
+
+    expect(result).toEqual([]);
+    expect(browser.appendChild).toHaveBeenCalledTimes(1);
+    await Promise.resolve();
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});

package/src/debug-loader.ts

@@ -0,0 +1,41 @@
+import type { DebugSettings } from "./types";
+
+export function loadDebugBuild(
+  settings: DebugSettings | undefined,
+  snippetUrl: string | undefined,
+  onFallback?: () => void,
+): boolean {
+  const expiresAt = settings?.expiresAt ? Date.parse(settings.expiresAt) : null;
+  if (!settings?.enabled || !snippetUrl
+    || settings.restrictMode === "off"
+    || expiresAt !== null && (!Number.isFinite(expiresAt) || expiresAt <= Date.now())) return false;
+  try {
+    const value = new URLSearchParams(location.search).get(settings.queryParam || "drip_debug");
+    const tokenRequired = settings.tokenRequired === true || Boolean(settings.token);
+    if (!tokenRequired && (value == "0" || value == "false")) return false;
+    const queryOptIn = tokenRequired ? value !== null : value == "1" || value == "true";
+    if (!queryOptIn && !(settings.persist && (localStorage as any).drip_debug == "1")) return false;
+    const handoff = (document as any).__dripDL;
+    if (handoff === "failed") return false;
+    if (handoff) {
+      return new URL(snippetUrl, location.href).searchParams.get("drip_sdk_variant") !== "debug";
+    }
+    const currentScript = document.currentScript;
+    const nonce = currentScript && (currentScript.nonce || currentScript.getAttribute("nonce")) || "";
+    const script = document.createElement("script");
+    const debugUrl = new URL(snippetUrl, location.href);
+    debugUrl.searchParams.set("drip_sdk_variant", "debug");
+    if (value !== null) debugUrl.searchParams.set("drip_debug_token", value);
+    script.src = debugUrl.toString();
+    script.nonce = nonce;
+    script.onerror = () => {
+      if ((document as any).__dripDL !== script) return;
+      (document as any).__dripDL = "failed";
+      onFallback?.();
+    };
+    (document as any).__dripDL = document.head.appendChild(script);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/decide-assignments.test.ts

@@ -0,0 +1,196 @@
+import { describe, expect, it } from "vitest";
+import { __assignmentStoreInternals } from "./assignment-store";
+import { chooseVariation, inTrafficAllocation } from "./bucket";
+import {
+  buildAssignment,
+  decideAssignments,
+  type DecideAssignmentsInput,
+} from "./decide-assignments";
+import { hashToFloat, variationHashToFloat } from "./hash";
+import type { Assignment, Experiment } from "./types";
+
+// Hermeticity: weekday tests pin the most recent UTC Monday at 12:00 instead
+// of a literal calendar date.
+const RECENT_MONDAY_NOON = (() => {
+  const d = new Date();
+  d.setUTCDate(d.getUTCDate() - ((d.getUTCDay() + 6) % 7));
+  d.setUTCHours(12, 0, 0, 0);
+  return d;
+})();
+
+function experiment(id: string, weights = [0.5, 0.5], allocation = 1, epoch = 1): Experiment {
+  return {
+    id,
+    status: "running",
+    trafficAllocation: allocation,
+    assignmentEpoch: epoch,
+    variations: weights.map((weight, index) => ({
+      id: `${id}_${index}`,
+      weight,
+      mutations: [],
+      isControl: index === 0,
+    })),
+  };
+}
+
+function legacyDecision(input: DecideAssignmentsInput): Array<Pick<Assignment, "experimentId" | "variationId">> {
+  const pct = input.holdout?.percentage;
+  if (input.holdout?.enabled && typeof pct === "number" && pct > 0 && pct <= 10 &&
+      hashToFloat("apex:global-holdout:v1", input.visitorId) < pct / 100) return [];
+  const provisional = input.experiments.flatMap((exp) => {
+    const epoch = Number.isFinite(exp.assignmentEpoch)
+      ? Math.max(1, Math.floor(exp.assignmentEpoch as number))
+      : 1;
+    const sticky = input.storedAssignments?.[exp.id];
+    if (sticky?.epoch === epoch && exp.variations.some((variation) => variation.id === sticky.variationId)) {
+      return [{ experimentId: exp.id, variationId: sticky.variationId }];
+    }
+    const trafficHash = hashToFloat(exp.id, input.visitorId);
+    const allocation = exp.trafficAllocation ?? 1;
+    if (!inTrafficAllocation(trafficHash, allocation) || !exp.variations.length) return [];
+    const splitHash = allocation >= 1
+      ? trafficHash
+      : variationHashToFloat(exp.id, input.visitorId);
+    const index = chooseVariation(splitHash, exp.variations.map((variation) => variation.weight));
+    return index >= 0
+      ? [{ experimentId: exp.id, variationId: exp.variations[index].id }]
+      : [];
+  });
+  const suppressed = new Set<string>();
+  for (const group of input.exclusionGroups ?? []) {
+    const conflicts = group.members.filter((member) =>
+      provisional.some((assignment) => assignment.experimentId === member.experimentId)
+    );
+    if (conflicts.length <= 1) continue;
+    const epoch = Number.isFinite(group.epoch) ? Math.max(1, Math.floor(group.epoch as number)) : 1;
+    const prior = input.storedGroupSelections?.[group.id];
+    const priorMember = conflicts.find((member) => member.experimentId === prior?.experimentId);
+    const configured = conflicts.map((member) => member.share > 0 ? member.share : 0);
+    const weights = configured.some((weight) => weight > 0) ? configured : configured.map(() => 1);
+    const winner = prior?.epoch === epoch && priorMember && (priorMember.share > 0 || !configured.some((weight) => weight > 0))
+      ? prior.experimentId
+      : conflicts[chooseVariation(hashToFloat(`${group.id}:exclusion`, input.visitorId), weights)].experimentId;
+    for (const conflict of conflicts) if (conflict.experimentId !== winner) suppressed.add(conflict.experimentId);
+  }
+  return provisional.filter((assignment) => !suppressed.has(assignment.experimentId));
+}
+
+function ids(assignments: Assignment[]) {
+  return assignments.map(({ experimentId, variationId }) => ({ experimentId, variationId }));
+}
+
+describe("decideAssignments parity boundary", () => {
+  const cases: Array<[string, DecideAssignmentsInput]> = [
+    ["empty config", { experiments: [], visitorId: "visitor-a", now: 123, url: "/" }],
+    ["single experiment", { experiments: [experiment("a")], visitorId: "visitor-a", now: 123 }],
+    ["multiple experiments", { experiments: [experiment("a"), experiment("b", [0.2, 0.8])], visitorId: "visitor-b", now: 123 }],
+    ["partial traffic allocation", { experiments: [experiment("a", [0.5, 0.5], 0.23)], visitorId: "visitor-c", now: 123 }],
+    ["sticky assignment wins over changed weights", {
+      experiments: [experiment("sticky", [1, 0])], visitorId: "visitor-d", now: 123,
+      storedAssignments: { sticky: { variationId: "sticky_1", epoch: 1, assignedAt: 1 } },
+    }],
+    ["epoch bump rejects sticky assignment", {
+      experiments: [experiment("sticky", [1, 0], 1, 2)], visitorId: "visitor-d", now: 123,
+      storedAssignments: { sticky: { variationId: "sticky_1", epoch: 1, assignedAt: 1 } },
+    }],
+    ["holdout visitor", {
+      experiments: [experiment("a")], visitorId: "holdout-49", now: 123,
+      holdout: { enabled: true, percentage: 10 },
+    }],
+    ["non-holdout visitor", {
+      experiments: [experiment("a")], visitorId: "visitor-outside-holdout", now: 123,
+      holdout: { enabled: true, percentage: 1 },
+    }],
+    ["exclusion group deterministic conflict", {
+      experiments: [experiment("a"), experiment("b")], visitorId: "visitor-e", now: 123,
+      exclusionGroups: [{ id: "group", epoch: 1, members: [{ experimentId: "a", share: 0.5 }, { experimentId: "b", share: 0.5 }] }],
+    }],
+    ["exclusion group sticky winner", {
+      experiments: [experiment("a"), experiment("b")], visitorId: "visitor-e", now: 123,
+      exclusionGroups: [{ id: "group", epoch: 1, members: [{ experimentId: "a", share: 1 }, { experimentId: "b", share: 0 }] }],
+      storedGroupSelections: { group: { experimentId: "b", epoch: 1 } },
+    }],
+  ];
+
+  it.each(cases)("matches the pre-extraction decision for %s", (_name, input) => {
+    expect(ids(decideAssignments(input))).toEqual(legacyDecision(input));
+  });
+
+  it("proves sticky precedence and assignment epoch are independently observable", () => {
+    const base = {
+      experiments: [experiment("money", [1, 0], 1, 1)],
+      visitorId: "money-path-visitor",
+      now: 123,
+      storedAssignments: { money: { variationId: "money_1", epoch: 1, assignedAt: 1 } },
+    } satisfies DecideAssignmentsInput;
+    expect(decideAssignments(base)[0]?.variationId).toBe("money_1");
+    expect(decideAssignments({ ...base, experiments: [experiment("money", [1, 0], 1, 2)] })[0]?.variationId).toBe("money_0");
+  });
+
+  it("blocks an excluded weekday before sticky assignment restore", () => {
+    const scheduled = {
+      ...experiment("weekday", [1, 0]),
+      weekdaySchedule: {
+        excludedDays: ["monday"] as ["monday"],
+        timezone: "UTC",
+      },
+    };
+    expect(decideAssignments({
+      experiments: [scheduled],
+      visitorId: "weekday-visitor",
+      now: RECENT_MONDAY_NOON.getTime(),
+      storedAssignments: {
+        weekday: {
+          variationId: "weekday_1",
+          epoch: 1,
+          assignedAt: 1,
+        },
+      },
+    })).toEqual([]);
+  });
+
+  it.each([undefined, Number.NaN, Number.POSITIVE_INFINITY, -2, 0, 1.9, 3.2])(
+    "matches assignment-store epoch normalization for %s",
+    (assignmentEpoch) => {
+      const config = experiment("epoch", [1], 1, assignmentEpoch);
+      expect(
+        buildAssignment(config, config.variations[0], 0, "visitor").assignmentEpoch,
+      ).toBe(__assignmentStoreInternals.assignmentEpoch(config));
+    },
+  );
+});
+
+describe("per-URL variation blocks", () => {
+  const treatment: Experiment = {
+    id: "multi", status: "running", trafficAllocation: 1,
+    variations: [{ id: "v", weight: 1, mutations: [{ action: "text", selector: "h1", text: "default" }], css: "default-css", js: "default-js", urlBlocks: [
+      { id: "first", name: "First", urlRules: [{ type: "simple", pattern: "*/products/a*" }], mutations: [{ action: "text", selector: "h1", text: "first" }], css: "first-css" },
+      { id: "second", name: "Second", urlRules: [{ type: "simple", pattern: "*/products/*" }], mutations: [{ action: "text", selector: "h1", text: "second" }] },
+    ] }],
+  };
+  it("uses the first matching block", () => {
+    const assignment = decideAssignments({ experiments: [treatment], visitorId: "x", now: 1, url: "https://shop.test/products/a" })[0];
+    expect(assignment.mutations[0]).toMatchObject({ text: "first" });
+    expect(assignment.activeUrlBlockId).toBe("first");
+    expect(assignment.css).toBe("first-css");
+    expect(assignment.js).toBeUndefined();
+  });
+  it("falls back to the flat artifact when no block matches", () => {
+    const assignment = decideAssignments({ experiments: [treatment], visitorId: "x", now: 1, url: "https://shop.test/pages/about" })[0];
+    expect(assignment.mutations[0]).toMatchObject({ text: "default" });
+    expect(assignment.activeUrlBlockId).toBeUndefined();
+    expect(assignment.css).toBe("default-css");
+    expect(assignment.js).toBe("default-js");
+  });
+  it("keeps an empty fallback assigned as a no-op", () => {
+    const noOp = { ...treatment, variations: [{ ...treatment.variations[0], mutations: [], css: undefined, js: undefined }] };
+    const assignment = decideAssignments({ experiments: [noOp], visitorId: "x", now: 1, url: "https://shop.test/pages/about" })[0];
+    expect(assignment.variationId).toBe("v");
+    expect(assignment.mutations).toEqual([]);
+  });
+  it("never applies URL blocks to control", () => {
+    const control = { ...treatment, variations: [{ ...treatment.variations[0], isControl: true }] };
+    const assignment = decideAssignments({ experiments: [control], visitorId: "x", now: 1, url: "https://shop.test/products/a" })[0];
+    expect(assignment.mutations[0]).toMatchObject({ text: "default" });
+  });
+});

package/src/decide-assignments.ts

@@ -0,0 +1,204 @@
+import { matchUrlRules } from "./targeting";
+import type { PersistedAssignmentRecord } from "./assignment-store";
+import { chooseVariation, inTrafficAllocation } from "./bucket";
+import { hashToFloat, variationHashToFloat } from "./hash";
+import { weekdayScheduleBlocksDelivery } from "./weekday-schedule";
+import type {
+  Assignment,
+  ExclusionGroupConfig,
+  Experiment,
+  Variation,
+} from "./types";
+
+export type StoredGroupSelection = {
+  experimentId: string;
+  epoch: number;
+};
+
+export interface DecideAssignmentsInput {
+  experiments: Experiment[];
+  visitorId: string;
+  storedAssignments?: Record<string, PersistedAssignmentRecord>;
+  storedGroupSelections?: Record<string, StoredGroupSelection>;
+  exclusionGroups?: ExclusionGroupConfig[];
+  holdout?: { enabled?: boolean; percentage?: number };
+  /** Supplied by the caller so the decision boundary never reads the clock. */
+  now: number;
+  /** Reserved for the Stage 2 bootstrap's already-targeted payload contract. */
+  url?: string;
+}
+
+function epoch(value: number | null | undefined): number {
+  return Number.isFinite(value) ? Math.max(1, Math.floor(value as number)) : 1;
+}
+
+export function buildAssignment(
+  experiment: Experiment,
+  variation: Variation,
+  index: number,
+  hashValue: string,
+  url?: string,
+): Assignment {
+  const block = !variation.isControl && url
+    ? variation.urlBlocks?.find((candidate) => matchUrlRules(url, candidate.urlRules))
+    : undefined;
+  return {
+    experimentId: experiment.id,
+    experimentName: experiment.name,
+    variationId: variation.id,
+    pageActive: true,
+    activeUrlBlockId: block?.id,
+    index,
+    mutations: block ? block.mutations : variation.mutations,
+    value: variation.value,
+    featureFlag: experiment.featureFlag,
+    personalization: experiment.personalization,
+    kind: experiment.kind ?? (experiment.personalization
+      ? "personalization"
+      : experiment.featureFlag
+        ? "feature_flag"
+        : "experiment"),
+    experimentCss: experiment.css,
+    experimentJs: experiment.js,
+    experimentResetJs: experiment.resetJs,
+    css: block ? block.css : variation.css,
+    js: block ? block.js : variation.js,
+    resetJs: variation.resetJs,
+    externalCssUrl: variation.externalCssUrl,
+    externalJsUrl: variation.externalJsUrl,
+    harnessSession: variation.harnessSession,
+    isControl: Boolean(variation.isControl),
+    redirectUrl: variation.redirectUrl,
+    artifactSource: variation.artifactSource,
+    hashValue,
+    assignmentEpoch: epoch(experiment.assignmentEpoch),
+  };
+}
+
+function decideVariationIndex(
+  experiment: Experiment,
+  visitorId: string,
+  storedAssignments: Record<string, PersistedAssignmentRecord>,
+): number {
+  if (!experiment.variations.length) return -1;
+
+  const stored = storedAssignments[experiment.id];
+  if (stored && stored.epoch === epoch(experiment.assignmentEpoch)) {
+    const index = experiment.variations.findIndex(
+      (variation) => variation.id === stored.variationId,
+    );
+    if (index >= 0) {
+      return index;
+    }
+  }
+
+  const hashValue = hashToFloat(experiment.id, visitorId);
+  const allocation = experiment.trafficAllocation ?? 1;
+  if (!inTrafficAllocation(hashValue, allocation)) return -1;
+  const variationHashValue = allocation >= 1
+    ? hashValue
+    : variationHashToFloat(experiment.id, visitorId);
+  const index = chooseVariation(
+    variationHashValue,
+    experiment.variations.map((variation) => variation.weight),
+  );
+  return index < experiment.variations.length ? index : -1;
+}
+
+function heldOut(input: DecideAssignmentsInput): boolean {
+  const percentage = input.holdout?.percentage;
+  return input.holdout?.enabled === true && typeof percentage === "number" &&
+    percentage > 0 && percentage <= 10 &&
+    hashToFloat("apex:global-holdout:v1", input.visitorId) < percentage / 100;
+}
+
+/** Worker bootstrap entrypoint after its literal status and weekday filters. */
+export function decideVariationIdsPregated(
+  input: DecideAssignmentsInput,
+): Array<[string, string]> {
+  if (heldOut(input)) return [];
+  const out: Array<[string, string]> = [];
+  for (const experiment of input.experiments) {
+    const index = decideVariationIndex(experiment, input.visitorId, input.storedAssignments ?? {});
+    if (index >= 0) out.push([experiment.id, experiment.variations[index].id]);
+  }
+  return out;
+}
+
+/** Compact projection of the same production bucketing decision for pre-paint handoff. */
+export function decideVariationIds(input: DecideAssignmentsInput): Array<[string, string]> {
+  return decideVariationIdsPregated({
+    ...input,
+    experiments: input.experiments.filter((experiment) =>
+      !weekdayScheduleBlocksDelivery(experiment.weekdaySchedule, new Date(input.now))
+    ),
+  });
+}
+
+function applyExclusionGroups(
+  assignments: Assignment[],
+  groups: ExclusionGroupConfig[],
+  visitorId: string,
+  storedSelections: Record<string, StoredGroupSelection>,
+): Assignment[] {
+  const assignedIds = new Set(assignments.map((assignment) => assignment.experimentId));
+  const suppressed = new Set<string>();
+  for (const group of groups) {
+    if (!group?.id || !Array.isArray(group.members)) continue;
+    const conflicting = group.members.filter((member) => assignedIds.has(member.experimentId));
+    if (conflicting.length <= 1) continue;
+    const prior = storedSelections[group.id];
+    const priorMember = prior
+      ? conflicting.find((member) => member.experimentId === prior.experimentId)
+      : undefined;
+    const hasPositiveWeight = conflicting.some((member) => member.share > 0);
+    let winnerId: string;
+    if (
+      prior &&
+      prior.epoch === epoch(group.epoch) &&
+      priorMember &&
+      (priorMember.share > 0 || !hasPositiveWeight)
+    ) {
+      winnerId = prior.experimentId;
+    } else {
+      const configured = conflicting.map((member) =>
+        Number.isFinite(member.share) && member.share > 0 ? member.share : 0
+      );
+      const weights = configured.some((weight) => weight > 0)
+        ? configured
+        : configured.map(() => 1);
+      const index = chooseVariation(
+        hashToFloat(`${group.id}:exclusion`, visitorId),
+        weights,
+      );
+      winnerId = conflicting[Math.max(0, Math.min(index, conflicting.length - 1))].experimentId;
+    }
+    for (const member of conflicting) {
+      if (member.experimentId !== winnerId) suppressed.add(member.experimentId);
+    }
+  }
+  return assignments.filter((assignment) => !suppressed.has(assignment.experimentId));
+}
+
+/**
+ * Pure assignment boundary for the SDK and the future inline bootstrap.
+ * The caller owns targeting, storage reads/writes, time, and exposure effects.
+ */
+export function decideAssignments(input: DecideAssignmentsInput): Assignment[] {
+  if (heldOut(input)) return [];
+
+  const assignments: Assignment[] = [];
+  for (const experiment of input.experiments) {
+    if (weekdayScheduleBlocksDelivery(experiment.weekdaySchedule, new Date(input.now))) {
+      continue;
+    }
+    const index = decideVariationIndex(experiment, input.visitorId, input.storedAssignments ?? {});
+    if (index >= 0) assignments.push(buildAssignment(experiment, experiment.variations[index], index, input.visitorId, input.url));
+  }
+  return applyExclusionGroups(
+    assignments,
+    input.exclusionGroups ?? [],
+    input.visitorId,
+    input.storedGroupSelections ?? {},
+  );
+}