@drip-apex/sdk 0.1.0

package/src/exclusion-groups.test.ts

@@ -0,0 +1,383 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  browserGroupStickyStore,
+  clearBrowserGroupStickyStore,
+  resolveExclusionGroups,
+  createMemoryGroupStickyStore,
+  type GroupStickyStore,
+} from "./exclusion-groups";
+import type { Assignment, ExclusionGroupConfig } from "./types";
+
+function assignment(experimentId: string): Assignment {
+  return {
+    experimentId,
+    variationId: `${experimentId}-v1`,
+    index: 0,
+    mutations: [],
+    isControl: false,
+    hashValue: "0.5",
+  };
+}
+
+function group(
+  id: string,
+  members: Array<[string, number]>,
+  epoch = 1,
+  name?: string,
+): ExclusionGroupConfig {
+  return {
+    id,
+    name,
+    epoch,
+    members: members.map(([experimentId, share]) => ({ experimentId, share })),
+  };
+}
+
+function ids(assignments: Assignment[]): string[] {
+  return assignments.map((a) => a.experimentId);
+}
+
+describe("resolveExclusionGroups", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+  it("ungrouped behavior is unchanged when there are no groups", () => {
+    const store = createMemoryGroupStickyStore();
+    const assignments = [assignment("a"), assignment("b")];
+    const result = resolveExclusionGroups(assignments, undefined, {
+      userId: "u1",
+      store,
+    });
+    expect(result.assignments).toBe(assignments);
+    expect(result.decisions).toEqual([]);
+  });
+
+  it("keeps both members when only one of them is eligible (no overlap)", () => {
+    const store = createMemoryGroupStickyStore();
+    const groups = [
+      group("g1", [
+        ["a", 0.5],
+        ["b", 0.5],
+      ]),
+    ];
+    // only "a" produced an assignment this pass
+    const result = resolveExclusionGroups([assignment("a")], groups, {
+      userId: "u1",
+      store,
+    });
+    expect(ids(result.assignments)).toEqual(["a"]);
+    expect(result.decisions).toEqual([]);
+  });
+
+  it("remembers a lone eligible member when another member overlaps later", () => {
+    const store = createMemoryGroupStickyStore();
+    const groups = [
+      group("g1", [
+        ["a", 0.4],
+        ["b", 0.6],
+      ]),
+    ];
+    resolveExclusionGroups([assignment("a")], groups, {
+      userId: "u1",
+      store,
+    });
+    const overlap = resolveExclusionGroups(
+      [assignment("a"), assignment("b")],
+      groups,
+      { userId: "u1", store },
+    );
+    expect(overlap.decisions[0]).toMatchObject({
+      winnerExperimentId: "a",
+      sticky: true,
+    });
+  });
+
+  it("does not let a lone zero-share member become sticky over a positive-share member", () => {
+    const store = createMemoryGroupStickyStore();
+    const groups = [
+      group("g1", [
+        ["a", 0],
+        ["b", 1],
+      ]),
+    ];
+
+    resolveExclusionGroups([assignment("a")], groups, {
+      userId: "u1",
+      store,
+    });
+    expect(store.read("g1")).toBeNull();
+
+    // Older runtimes may already have persisted this invalid lone selection.
+    store.write("g1", { experimentId: "a", epoch: 1 });
+    const overlap = resolveExclusionGroups(
+      [assignment("a"), assignment("b")],
+      groups,
+      { userId: "u1", store },
+    );
+    expect(overlap.decisions[0]).toMatchObject({
+      winnerExperimentId: "b",
+      sticky: false,
+    });
+  });
+
+  it("keeps exactly one winner when two members overlap", () => {
+    const store = createMemoryGroupStickyStore();
+    const groups = [
+      group("g1", [
+        ["a", 0.5],
+        ["b", 0.5],
+      ]),
+    ];
+    const result = resolveExclusionGroups(
+      [assignment("a"), assignment("b"), assignment("c")],
+      groups,
+      { userId: "u1", store },
+    );
+    // c is ungrouped and always kept
+    expect(result.assignments).toContainEqual(
+      expect.objectContaining({ experimentId: "c" }),
+    );
+    const grouped = ids(result.assignments).filter(
+      (id) => id === "a" || id === "b",
+    );
+    expect(grouped).toHaveLength(1);
+    expect(result.decisions).toHaveLength(1);
+    expect(result.decisions[0].winnerExperimentId).toBe(grouped[0]);
+    expect(result.decisions[0].suppressedExperimentIds).toHaveLength(1);
+  });
+
+  it("is deterministic for the same visitor / group / shares", () => {
+    const groups = [
+      group("g1", [
+        ["a", 0.5],
+        ["b", 0.5],
+      ]),
+    ];
+    const run = () =>
+      resolveExclusionGroups([assignment("a"), assignment("b")], groups, {
+        userId: "stable-user",
+        store: createMemoryGroupStickyStore(),
+      }).decisions[0].winnerExperimentId;
+    const first = run();
+    for (let i = 0; i < 10; i++) {
+      expect(run()).toBe(first);
+    }
+  });
+
+  it("honors share weighting across a population of visitors", () => {
+    const groups = [
+      group("g1", [
+        ["a", 0.9],
+        ["b", 0.1],
+      ]),
+    ];
+    let aWins = 0;
+    const total = 400;
+    for (let i = 0; i < total; i++) {
+      const winner = resolveExclusionGroups(
+        [assignment("a"), assignment("b")],
+        groups,
+        { userId: `user-${i}`, store: createMemoryGroupStickyStore() },
+      ).decisions[0].winnerExperimentId;
+      if (winner === "a") aWins += 1;
+    }
+    // ~90% should go to "a"; allow generous tolerance.
+    expect(aWins / total).toBeGreaterThan(0.75);
+  });
+
+  it("falls back to equal deterministic weights when every overlapping share is zero", () => {
+    const groups = [
+      group("g1", [
+        ["a", 0],
+        ["b", 0],
+      ]),
+    ];
+    const winners = new Set<string>();
+    for (let i = 0; i < 100; i++) {
+      const winner = resolveExclusionGroups(
+        [assignment("a"), assignment("b")],
+        groups,
+        { userId: `zero-${i}`, store: createMemoryGroupStickyStore() },
+      ).decisions[0].winnerExperimentId;
+      if (winner) winners.add(winner);
+    }
+    expect(winners).toEqual(new Set(["a", "b"]));
+  });
+
+  it("keeps a sticky winner while it stays eligible across varying conflicting sets", () => {
+    const store = createMemoryGroupStickyStore();
+    const groups = [
+      group("g1", [
+        ["a", 0.5],
+        ["b", 0.5],
+      ]),
+    ];
+    const first = resolveExclusionGroups(
+      [assignment("a"), assignment("b")],
+      groups,
+      { userId: "u1", store },
+    );
+    const winner = first.decisions[0].winnerExperimentId!;
+    // On a later evaluation both are eligible again → same winner, sticky.
+    const second = resolveExclusionGroups(
+      [assignment("a"), assignment("b")],
+      groups,
+      { userId: "u1", store },
+    );
+    expect(second.decisions[0].winnerExperimentId).toBe(winner);
+    expect(second.decisions[0].sticky).toBe(true);
+  });
+
+  it("reselects when the sticky winner loses eligibility, then re-sticks", () => {
+    const store: GroupStickyStore = createMemoryGroupStickyStore();
+    const groups = [
+      group("g1", [
+        ["a", 1],
+        ["b", 0],
+        ["c", 0],
+      ]),
+    ];
+    // Force winner "a" first.
+    const first = resolveExclusionGroups(
+      [assignment("a"), assignment("b")],
+      groups,
+      { userId: "u1", store },
+    );
+    expect(first.decisions[0].winnerExperimentId).toBe("a");
+
+    // Now "a" is no longer eligible; only b and c overlap → reselect among them.
+    const zeroShareGroup = [
+      group("g1", [
+        ["a", 1],
+        ["b", 0.5],
+        ["c", 0.5],
+      ]),
+    ];
+    const second = resolveExclusionGroups(
+      [assignment("b"), assignment("c")],
+      zeroShareGroup,
+      { userId: "u1", store },
+    );
+    expect(
+      second.decisions[0].winnerExperimentId === "b" ||
+        second.decisions[0].winnerExperimentId === "c",
+    ).toBe(true);
+    expect(second.decisions[0].sticky).toBe(false);
+  });
+
+  it("resets stickiness when the group epoch changes", () => {
+    const store = createMemoryGroupStickyStore();
+    const groupsE1 = [
+      group(
+        "g1",
+        [
+          ["a", 1],
+          ["b", 0],
+        ],
+        1,
+      ),
+    ];
+    const first = resolveExclusionGroups(
+      [assignment("a"), assignment("b")],
+      groupsE1,
+      { userId: "u1", store },
+    );
+    expect(first.decisions[0].winnerExperimentId).toBe("a");
+
+    // Epoch bumps AND shares flip → the stored (epoch 1) selection is ignored.
+    const groupsE2 = [
+      group(
+        "g1",
+        [
+          ["a", 0],
+          ["b", 1],
+        ],
+        2,
+      ),
+    ];
+    const second = resolveExclusionGroups(
+      [assignment("a"), assignment("b")],
+      groupsE2,
+      { userId: "u1", store },
+    );
+    expect(second.decisions[0].winnerExperimentId).toBe("b");
+    expect(second.decisions[0].sticky).toBe(false);
+  });
+
+  it("bypasses exclusion for QA-forced members (preview only)", () => {
+    const store = createMemoryGroupStickyStore();
+    const groups = [
+      group("g1", [
+        ["a", 0.5],
+        ["b", 0.5],
+      ]),
+    ];
+    // "a" is forced; it should always be kept and not compete.
+    const result = resolveExclusionGroups(
+      [assignment("a"), assignment("b")],
+      groups,
+      { userId: "u1", store, forcedExperimentIds: ["a"] },
+    );
+    expect(ids(result.assignments)).toContain("a");
+    expect(ids(result.assignments)).toContain("b");
+    expect(result.decisions).toEqual([]);
+    expect(store.read("g1")).toBeNull();
+  });
+
+  it("does not read or write prior stickiness when persistence is disabled", () => {
+    const store: GroupStickyStore = {
+      read: vi.fn(() => ({ experimentId: "a", epoch: 1 })),
+      write: vi.fn(),
+    };
+    const groups = [
+      group("g1", [
+        ["a", 0.5],
+        ["b", 0.5],
+      ]),
+    ];
+    resolveExclusionGroups([assignment("a"), assignment("b")], groups, {
+      userId: "u1",
+      store,
+      persist: false,
+    });
+    expect(store.read).not.toHaveBeenCalled();
+    expect(store.write).not.toHaveBeenCalled();
+  });
+
+  it("clears browser group stickiness from localStorage and cookies", () => {
+    const removeItem = vi.fn();
+    let cookieWrite = "";
+    vi.stubGlobal("localStorage", { removeItem });
+    vi.stubGlobal("document", {
+      get cookie() {
+        return "";
+      },
+      set cookie(value: string) {
+        cookieWrite = value;
+      },
+    });
+
+    clearBrowserGroupStickyStore();
+
+    expect(removeItem).toHaveBeenCalledWith("drip_xgroups_v1");
+    expect(cookieWrite).toBe(
+      "drip_xgroups_v1=;path=/;max-age=0;samesite=lax",
+    );
+  });
+
+  it("prefers the edge response cookie over stale localStorage", () => {
+    vi.stubGlobal("localStorage", {
+      getItem: vi.fn(() => JSON.stringify({ g1: ["stale", 1] })),
+    });
+    vi.stubGlobal("document", {
+      cookie: `drip_xgroups_v1=${encodeURIComponent(
+        JSON.stringify({ g1: ["edge-winner", 2] }),
+      )}`,
+    });
+
+    expect(browserGroupStickyStore.read("g1")).toEqual({
+      experimentId: "edge-winner",
+      epoch: 2,
+    });
+  });
+});

package/src/exclusion-groups.ts

@@ -0,0 +1,270 @@
+import type { Assignment, ExclusionGroupConfig } from "./types";
+import { hashToFloat } from "./hash";
+import { chooseVariation } from "./bucket";
+import { deleteCookie, readCookie, writeCookie } from "./guards";
+
+const STORAGE_KEY = "drip_xgroups_v1"; // gitleaks:allow — public storage key name, not a credential
+const COOKIE_NAME = "drip_xgroups_v1";
+const COOKIE_MAX_AGE_SECONDS = 365 * 24 * 60 * 60;
+
+/** A remembered group decision: which member won and at what group epoch. */
+export type PersistedGroupSelection = {
+  experimentId: string;
+  epoch: number;
+};
+
+/** Pluggable persistence so the runtime uses browser storage and tests use memory. */
+export interface GroupStickyStore {
+  read(groupId: string): PersistedGroupSelection | null;
+  write(groupId: string, selection: PersistedGroupSelection): void;
+}
+
+type CompactSelection = [string, number];
+type CompactStore = Record<string, CompactSelection>;
+
+function normalizeEpoch(epoch: number | null | undefined): number {
+  return Number.isFinite(epoch) ? Math.max(1, Math.floor(epoch as number)) : 1;
+}
+
+function parseStore(raw: string | null): CompactStore {
+  if (!raw) return {};
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as CompactStore)
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+function readLocalStorage(): string | null {
+  try {
+    return globalThis.localStorage?.getItem(STORAGE_KEY) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function readCompactStore(): CompactStore {
+  return {
+    ...parseStore(readLocalStorage()),
+    ...parseStore(readCookie(COOKIE_NAME)),
+  };
+}
+
+function writeCompactStore(store: CompactStore): void {
+  const serialized = JSON.stringify(store);
+  try {
+    globalThis.localStorage?.setItem(STORAGE_KEY, serialized);
+  } catch {
+    // best-effort
+  }
+  writeCookie(COOKIE_NAME, serialized, COOKIE_MAX_AGE_SECONDS);
+}
+
+/** Browser-backed store (localStorage + cookie mirror) used by the live runtime. */
+export const browserGroupStickyStore: GroupStickyStore = {
+  read(groupId) {
+    const record = readCompactStore()[groupId];
+    return Array.isArray(record) &&
+      typeof record[0] === "string" &&
+      typeof record[1] === "number"
+      ? { experimentId: record[0], epoch: record[1] }
+      : null;
+  },
+  write(groupId, selection) {
+    const store = readCompactStore();
+    store[groupId] = [selection.experimentId, normalizeEpoch(selection.epoch)];
+    writeCompactStore(store);
+  },
+};
+
+/** Remove consent-gated group stickiness from both browser persistence planes. */
+export function clearBrowserGroupStickyStore(): void {
+  try {
+    globalThis.localStorage?.removeItem(STORAGE_KEY);
+  } catch {
+    // best-effort
+  }
+  deleteCookie(COOKIE_NAME);
+}
+
+/** In-memory store for tests and non-persistent (QA / no-consent) contexts. */
+export function createMemoryGroupStickyStore(): GroupStickyStore {
+  const map = new Map<string, PersistedGroupSelection>();
+  return {
+    read: (groupId) => map.get(groupId) ?? null,
+    write: (groupId, selection) =>
+      void map.set(groupId, {
+        experimentId: selection.experimentId,
+        epoch: normalizeEpoch(selection.epoch),
+      }),
+  };
+}
+
+export interface ExclusionGroupDecision {
+  groupId: string;
+  /** Eligible, non-forced members that overlapped for this visitor. */
+  conflictingExperimentIds: string[];
+  winnerExperimentId: string | null;
+  suppressedExperimentIds: string[];
+  /** True when the winner was carried over from a prior sticky selection. */
+  sticky: boolean;
+}
+
+export interface ResolveExclusionGroupsResult {
+  assignments: Assignment[];
+  decisions: ExclusionGroupDecision[];
+}
+
+/**
+ * Second pass of the overlap-then-pick model.
+ *
+ * `assignments` are the pass-one winners (each experiment already evaluated its
+ * own status, targeting, exposure, sticky assignment and variation split). Here
+ * we detect members of the same exclusion group that BOTH became eligible for
+ * this visitor (overlap) and keep exactly one — chosen by a group-deterministic
+ * hash weighted by each conflicting member's share, re-normalized across only
+ * the conflicting members. A previously assigned member stays sticky while it
+ * remains eligible; if it drops out we reselect among the current conflicting
+ * members. Forced (QA preview) members bypass exclusion entirely.
+ */
+export function resolveExclusionGroups(
+  assignments: Assignment[],
+  groups: ExclusionGroupConfig[] | undefined,
+  ctx: {
+    userId: string;
+    forcedExperimentIds?: Iterable<string>;
+    store?: GroupStickyStore;
+    persist?: boolean;
+  },
+): ResolveExclusionGroupsResult {
+  const decisions: ExclusionGroupDecision[] = [];
+  if (!groups || groups.length === 0) {
+    return { assignments, decisions };
+  }
+
+  const persist = ctx.persist !== false;
+  const forced = new Set(ctx.forcedExperimentIds ?? []);
+  // Persistence-disabled contexts skip sticky reads and writes below, so they
+  // cannot inherit a prior browser or injected winner.
+  const store = ctx.store ?? browserGroupStickyStore;
+
+  // experimentId -> its pass-one assignment (only eligible experiments appear).
+  const assignedById = new Map<string, Assignment>();
+  for (const assignment of assignments) {
+    assignedById.set(assignment.experimentId, assignment);
+  }
+
+  const suppressed = new Set<string>();
+
+  for (const group of groups) {
+    if (
+      !group?.id ||
+      !Array.isArray(group.members) ||
+      group.members.length === 0
+    ) {
+      continue;
+    }
+    const epoch = normalizeEpoch(group.epoch);
+    const hasForcedAssignment = group.members.some(
+      (member) =>
+        assignedById.has(member.experimentId) &&
+        forced.has(member.experimentId),
+    );
+    const persistGroupSelection = persist && !hasForcedAssignment;
+
+    // Conflicting = eligible (assigned this pass) AND not forced for QA preview.
+    const conflicting = group.members.filter(
+      (member) =>
+        assignedById.has(member.experimentId) &&
+        !forced.has(member.experimentId),
+    );
+
+    if (conflicting.length <= 1) {
+      // Zero or one eligible member → no exclusion decision. Remember a lone
+      // positive-share member so it stays sticky if another member overlaps
+      // later. A 0% member must never gain priority merely by appearing alone.
+      if (
+        conflicting.length === 1 &&
+        conflicting[0].share > 0 &&
+        persistGroupSelection
+      ) {
+        store.write(group.id, {
+          experimentId: conflicting[0].experimentId,
+          epoch,
+        });
+      }
+      continue;
+    }
+
+    const conflictingIds = conflicting.map((member) => member.experimentId);
+
+    // Sticky: keep the prior winner while it stays eligible at the current epoch.
+    const prior = persistGroupSelection ? store.read(group.id) : null;
+    let winnerId: string;
+    let sticky = false;
+    const priorMember = prior
+      ? conflicting.find((member) => member.experimentId === prior.experimentId)
+      : undefined;
+    const hasPositiveWeight = conflicting.some((member) => member.share > 0);
+    if (
+      prior &&
+      prior.epoch === epoch &&
+      priorMember &&
+      (priorMember.share > 0 || !hasPositiveWeight)
+    ) {
+      winnerId = prior.experimentId;
+      sticky = true;
+    } else {
+      // Deterministic pick across only the conflicting members, weighted by share.
+      const configuredWeights = conflicting.map((member) =>
+        Number.isFinite(member.share) && member.share > 0 ? member.share : 0,
+      );
+      // A degenerate all-zero conflicting subset can happen after eligibility
+      // filtering. Keep the decision fair and deterministic instead of letting
+      // the generic bucket helper silently favor the first member.
+      const weights = configuredWeights.some((weight) => weight > 0)
+        ? configuredWeights
+        : configuredWeights.map(() => 1);
+      const hashValue = hashToFloat(`${group.id}:exclusion`, ctx.userId);
+      const index = chooseVariation(hashValue, weights);
+      winnerId =
+        conflicting[Math.max(0, Math.min(index, conflicting.length - 1))]
+          .experimentId;
+      if (persistGroupSelection) {
+        store.write(group.id, { experimentId: winnerId, epoch });
+      }
+    }
+
+    const suppressedIds = conflictingIds.filter((id) => id !== winnerId);
+    for (const id of suppressedIds) suppressed.add(id);
+
+    decisions.push({
+      groupId: group.id,
+      conflictingExperimentIds: conflictingIds,
+      winnerExperimentId: winnerId,
+      suppressedExperimentIds: suppressedIds,
+      sticky,
+    });
+  }
+
+  if (suppressed.size === 0) {
+    return { assignments, decisions };
+  }
+
+  return {
+    assignments: assignments.filter(
+      (assignment) => !suppressed.has(assignment.experimentId),
+    ),
+    decisions,
+  };
+}
+
+export const __exclusionGroupInternals = {
+  STORAGE_KEY,
+  COOKIE_NAME,
+  parseStore,
+  normalizeEpoch,
+};