@drip-apex/sdk 0.1.0 → 0.3.0

package/src/shopify-cart.test.ts

@@ -24,12 +24,277 @@ describe("syncShopifyCartAttributes", () => {
   });
 
   afterEach(() => {
+    vi.useRealTimers();
     vi.restoreAllMocks();
     (globalThis as any).window = originalWindow;
     (globalThis as any).sessionStorage = originalSessionStorage;
     globalThis.fetch = originalFetch;
   });
 
+  it("serializes cross-signature writes so the newest state is submitted last", async () => {
+    let resolveFirst!: (response: Response) => void;
+    globalThis.fetch = vi.fn(() => new Promise<Response>((resolve) => {
+      resolveFirst = resolve;
+    })) as any;
+    const { syncShopifyCartAttributes } = await import("./shopify-cart");
+    const first = syncShopifyCartAttributes({
+      assignments: [{ experimentId: "exp_123", variationId: "var_old" }],
+      visitorId: "visitor_123",
+      sessionId: "session_old",
+    });
+    await vi.waitFor(() => expect(globalThis.fetch).toHaveBeenCalledTimes(1));
+    const newest = syncShopifyCartAttributes({
+      assignments: [{ experimentId: "exp_123", variationId: "var_new" }],
+      visitorId: "visitor_123",
+      sessionId: "session_new",
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(globalThis.fetch).toHaveBeenCalledTimes(1);
+    resolveFirst(new Response("{}", { status: 200 }));
+    await vi.waitFor(() => expect(globalThis.fetch).toHaveBeenCalledTimes(2));
+    const finalBody = JSON.parse(String(vi.mocked(globalThis.fetch).mock.calls[1]?.[1]?.body));
+    expect(JSON.parse(finalBody.attributes.apex_assignments)).toEqual([
+      { e: "exp_123", v: "var_new" },
+    ]);
+    expect(finalBody.attributes.apex_session_id).toBe("session_new");
+    resolveFirst(new Response("{}", { status: 200 }));
+    await expect(Promise.all([first, newest])).resolves.toEqual([
+      { status: "skipped", reason: "superseded" },
+      { status: "sent" },
+    ]);
+  });
+
+  it("coalesces overlapping mutations into exactly one newest trailing write", async () => {
+    let resolveWrite!: (response: Response) => void;
+    globalThis.fetch = vi.fn(() => new Promise<Response>((resolve) => {
+      resolveWrite = resolve;
+    })) as any;
+    const { syncShopifyCartAttributes } = await import("./shopify-cart");
+    const inputs = ["old", "middle", "newest"].map((variationId) => ({
+      assignments: [{ experimentId: "exp_123", variationId }],
+      visitorId: "visitor_123",
+      sessionId: `session_${variationId}`,
+    }));
+
+    const writes = [syncShopifyCartAttributes(inputs[0]!)];
+    await vi.waitFor(() => expect(globalThis.fetch).toHaveBeenCalledTimes(1));
+    writes.push(syncShopifyCartAttributes(inputs[1]!));
+    await Promise.resolve();
+    writes.push(syncShopifyCartAttributes(inputs[2]!));
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(globalThis.fetch).toHaveBeenCalledTimes(1);
+    resolveWrite(new Response("{}", { status: 200 }));
+    await vi.waitFor(() => expect(globalThis.fetch).toHaveBeenCalledTimes(2));
+    expect(JSON.parse(
+      JSON.parse(String(vi.mocked(globalThis.fetch).mock.calls[1]?.[1]?.body))
+        .attributes.apex_assignments,
+    )).toEqual([{ e: "exp_123", v: "newest" }]);
+    resolveWrite(new Response("{}", { status: 200 }));
+    await expect(Promise.all(writes)).resolves.toEqual([
+      { status: "skipped", reason: "superseded" },
+      { status: "skipped", reason: "superseded" },
+      { status: "sent" },
+    ]);
+    expect(globalThis.fetch).toHaveBeenCalledTimes(2);
+  });
+
+  it("atomically drains a write queued in the writer's exit microtask window", async () => {
+    vi.useFakeTimers();
+    let resolveWrite!: (response: Response) => void;
+    globalThis.fetch = vi.fn(() => new Promise<Response>((resolve) => {
+      resolveWrite = resolve;
+    })) as any;
+    const { syncShopifyCartAttributes } = await import("./shopify-cart");
+    const input = {
+      assignments: [{ experimentId: "exp_123", variationId: "treatment" }],
+      visitorId: "visitor_123",
+      sessionId: "session_123",
+    };
+
+    const first = syncShopifyCartAttributes(input);
+    await vi.advanceTimersByTimeAsync(0);
+    expect(globalThis.fetch).toHaveBeenCalledTimes(1);
+    let reissued!: ReturnType<typeof syncShopifyCartAttributes>;
+    queueMicrotask(() => {
+      reissued = syncShopifyCartAttributes(input, { force: true });
+    });
+    resolveWrite(new Response("{}", { status: 200 }));
+    await vi.advanceTimersByTimeAsync(0);
+    expect(globalThis.fetch).toHaveBeenCalledTimes(2);
+    resolveWrite(new Response("{}", { status: 200 }));
+    await vi.advanceTimersByTimeAsync(0);
+
+    await expect(Promise.all([first, reissued])).resolves.toEqual([
+      { status: "skipped", reason: "superseded" },
+      { status: "sent" },
+    ]);
+  });
+
+  it("discards a queued cart write when sync state is invalidated", async () => {
+    vi.useFakeTimers();
+    globalThis.fetch = vi.fn(() => new Promise<Response>(() => {})) as any;
+    const {
+      invalidateShopifyCartAttributeSync,
+      syncShopifyCartAttributes,
+    } = await import("./shopify-cart");
+
+    const active = syncShopifyCartAttributes({
+      assignments: [{ experimentId: "exp_123", variationId: "old" }],
+      visitorId: "visitor_123",
+      sessionId: "session_old",
+    });
+    await vi.advanceTimersByTimeAsync(0);
+    const queued = syncShopifyCartAttributes({
+      assignments: [{ experimentId: "exp_123", variationId: "queued" }],
+      visitorId: "visitor_123",
+      sessionId: "session_queued",
+    });
+
+    invalidateShopifyCartAttributeSync();
+    await vi.advanceTimersByTimeAsync(0);
+
+    await expect(queued).resolves.toEqual({ status: "skipped", reason: "superseded" });
+    await expect(active).resolves.toEqual({ status: "failed", reason: "cart_write_aborted" });
+    expect(globalThis.fetch).toHaveBeenCalledTimes(1);
+  });
+
+  it("discards an ABA re-issue scheduled before sync state is invalidated", async () => {
+    vi.useFakeTimers();
+    globalThis.fetch = vi.fn(() => new Promise<Response>(() => {})) as any;
+    const {
+      invalidateShopifyCartAttributeSync,
+      syncShopifyCartAttributes,
+    } = await import("./shopify-cart");
+    const input = (variationId: string) => ({
+      assignments: [{ experimentId: "exp_123", variationId }],
+      visitorId: "visitor_123",
+      sessionId: `session_${variationId}`,
+    });
+
+    const firstA = syncShopifyCartAttributes(input("a"));
+    await vi.advanceTimersByTimeAsync(0);
+    expect(globalThis.fetch).toHaveBeenCalledTimes(1);
+    const middleB = syncShopifyCartAttributes(input("b"));
+    const finalA = syncShopifyCartAttributes(input("a"));
+
+    invalidateShopifyCartAttributeSync();
+    await vi.advanceTimersByTimeAsync(0);
+
+    await expect(firstA).resolves.toEqual({ status: "failed", reason: "cart_write_aborted" });
+    await expect(middleB).resolves.toEqual({ status: "skipped", reason: "superseded" });
+    await expect(finalA).resolves.toEqual({ status: "skipped", reason: "superseded" });
+    expect(globalThis.fetch).toHaveBeenCalledTimes(1);
+  });
+
+  it("times out a stalled write and lets the newest queued sync proceed", async () => {
+    vi.useFakeTimers();
+    globalThis.fetch = vi.fn()
+      .mockImplementationOnce(() => new Promise<Response>(() => {}))
+      .mockResolvedValueOnce(new Response("{}", { status: 200 })) as any;
+    const { syncShopifyCartAttributes } = await import("./shopify-cart");
+
+    const stalled = syncShopifyCartAttributes({
+      assignments: [{ experimentId: "exp_123", variationId: "stalled" }],
+      visitorId: "visitor_123",
+      sessionId: "session_stalled",
+    });
+    await vi.advanceTimersByTimeAsync(0);
+    const newest = syncShopifyCartAttributes({
+      assignments: [{ experimentId: "exp_123", variationId: "newest" }],
+      visitorId: "visitor_123",
+      sessionId: "session_newest",
+    });
+
+    await vi.advanceTimersByTimeAsync(10_000);
+    await expect(stalled).resolves.toEqual({ status: "failed", reason: "cart_write_timeout" });
+    await expect(newest).resolves.toEqual({ status: "sent" });
+    expect(globalThis.fetch).toHaveBeenCalledTimes(2);
+  });
+
+  it("classifies an AbortError caused by the writer deadline as timeout", async () => {
+    vi.useFakeTimers();
+    globalThis.fetch = vi.fn((_url, init) => new Promise<Response>((_resolve, reject) => {
+      init?.signal?.addEventListener("abort", () => {
+        reject(new DOMException("ambient abort text", "AbortError"));
+      }, { once: true });
+    })) as any;
+    const { syncShopifyCartAttributes } = await import("./shopify-cart");
+
+    const write = syncShopifyCartAttributes({
+      assignments: [{ experimentId: "exp_123", variationId: "stalled" }],
+      visitorId: "visitor_123",
+      sessionId: "session_stalled",
+    });
+    await vi.advanceTimersByTimeAsync(10_000);
+
+    await expect(write).resolves.toEqual({ status: "failed", reason: "cart_write_timeout" });
+  });
+
+  it("re-issues A after an intervening B even while the first A is in flight", async () => {
+    const resolvers: Array<(response: Response) => void> = [];
+    globalThis.fetch = vi.fn(() => new Promise<Response>((resolve) => {
+      resolvers.push(resolve);
+    })) as any;
+    const { syncShopifyCartAttributes } = await import("./shopify-cart");
+    const input = (variationId: string) => ({
+      assignments: [{ experimentId: "exp_123", variationId }],
+      visitorId: "visitor_123",
+      sessionId: `session_${variationId}`,
+    });
+
+    const firstA = syncShopifyCartAttributes(input("A"));
+    await vi.waitFor(() => expect(resolvers).toHaveLength(1));
+    const writeB = syncShopifyCartAttributes(input("B"));
+    const finalA = syncShopifyCartAttributes(input("A"));
+
+    resolvers[0]!(new Response("{}", { status: 200 }));
+    await vi.waitFor(() => expect(resolvers).toHaveLength(2));
+    resolvers[1]!(new Response("{}", { status: 200 }));
+    await vi.waitFor(() => expect(resolvers).toHaveLength(3));
+    const finalBody = JSON.parse(String(vi.mocked(globalThis.fetch).mock.calls[2]?.[1]?.body));
+    expect(JSON.parse(finalBody.attributes.apex_assignments)).toEqual([{ e: "exp_123", v: "A" }]);
+    resolvers[2]!(new Response("{}", { status: 200 }));
+
+    await expect(Promise.all([firstA, writeB, finalA])).resolves.toEqual([
+      { status: "skipped", reason: "superseded" },
+      { status: "skipped", reason: "superseded" },
+      { status: "sent" },
+    ]);
+  });
+
+  it("re-drives the newest mutation after an in-flight write fails", async () => {
+    let rejectFirst!: (error: Error) => void;
+    globalThis.fetch = vi.fn()
+      .mockImplementationOnce(() => new Promise<Response>((_resolve, reject) => {
+        rejectFirst = reject;
+      }))
+      .mockResolvedValueOnce(new Response("{}", { status: 200 })) as any;
+    const { syncShopifyCartAttributes } = await import("./shopify-cart");
+    const first = syncShopifyCartAttributes({
+      assignments: [{ experimentId: "exp_123", variationId: "var_old" }],
+      visitorId: "visitor_123",
+      sessionId: "session_old",
+    });
+    await vi.waitFor(() => expect(rejectFirst).toBeTypeOf("function"));
+    const newest = syncShopifyCartAttributes({
+      assignments: [{ experimentId: "exp_123", variationId: "var_new" }],
+      visitorId: "visitor_123",
+      sessionId: "session_new",
+    });
+
+    rejectFirst(new Error("cart unavailable"));
+    await expect(Promise.all([first, newest])).resolves.toEqual([
+      { status: "failed", reason: "cart unavailable" },
+      { status: "sent" },
+    ]);
+    expect(globalThis.fetch).toHaveBeenCalledTimes(2);
+    const finalBody = JSON.parse(String(vi.mocked(globalThis.fetch).mock.calls[1]?.[1]?.body));
+    expect(JSON.parse(finalBody.attributes.apex_assignments)).toEqual([
+      { e: "exp_123", v: "var_new" },
+    ]);
+  });
+
   it("posts all Apex assignments plus primary attribution keys to the Shopify cart", async () => {
     const { syncShopifyCartAttributes } = await import("./shopify-cart");
 
@@ -81,7 +346,7 @@ describe("syncShopifyCartAttributes", () => {
   });
 
   it("builds ordered Storefront API cart attribute entries with compact assignment keys", async () => {
-    const { buildCartAttributeEntries } = await import("./shopify-cart");
+    const { APEX_CART_ATTRIBUTE_KEYS, buildCartAttributeEntries } = await import("./shopify-cart");
 
     const entries = buildCartAttributeEntries({
       assignments: [
@@ -101,6 +366,15 @@ describe("syncShopifyCartAttributes", () => {
       "apex_visitor_id",
       "apex_session_id",
     ]);
+    expect(entries.every((entry) => APEX_CART_ATTRIBUTE_KEYS.has(entry.key))).toBe(true);
+    expect(
+      buildCartAttributeEntries({
+        assignments: [],
+        identityOnly: true,
+        visitorId: "visitor_123",
+        sessionId: "session_123",
+      }).every((entry) => APEX_CART_ATTRIBUTE_KEYS.has(entry.key)),
+    ).toBe(true);
     expect(JSON.parse(entries[0]!.value)).toEqual([
       { e: "exp_123", v: "var_123", ep: 2 },
       { e: "exp_456", v: "var_456" },
@@ -119,6 +393,264 @@ describe("syncShopifyCartAttributes", () => {
     });
   });
 
+  it("keeps the consent-pending stamp to arm labels only against the consented fixture", async () => {
+    const { buildCartAttributeEntries } = await import("./shopify-cart");
+    const fixture = {
+      assignments: [
+        { experimentId: "exp_first", variationId: "var_first", assignmentEpoch: 4 },
+        { experimentId: "exp_second", variationId: "var_second", assignmentEpoch: 2 },
+      ],
+      visitorId: "visitor_123",
+      sessionId: "session_123",
+    };
+    const consented = buildCartAttributeEntries(fixture, "signed-envelope");
+    const sdkCartMint = buildCartAttributeEntries({ ...fixture, visitorId: "", sessionId: "" });
+
+    expect(sdkCartMint).toEqual([
+      {
+        key: "apex_assignments",
+        value: JSON.stringify([
+          { e: "exp_first", v: "var_first", ep: 4 },
+          { e: "exp_second", v: "var_second", ep: 2 },
+        ]),
+      },
+      { key: "apex_assignment_authorization", value: "" },
+      { key: "apex_experiment_id", value: "" },
+      { key: "apex_variation_id", value: "" },
+      { key: "apex_assignment_epoch", value: "" },
+      { key: "apex_visitor_id", value: "" },
+      { key: "apex_session_id", value: "" },
+    ]);
+    const identityKeys = consented
+      .map(({ key }) => key)
+      .filter((key) => [
+        "apex_assignment_authorization",
+        "apex_visitor_id",
+        "apex_session_id",
+      ].includes(key));
+    expect(identityKeys).toEqual([
+      "apex_assignment_authorization",
+      "apex_visitor_id",
+      "apex_session_id",
+    ]);
+    expect(sdkCartMint.filter(({ value }) => value !== "").map(({ key }) => key)).toEqual([
+      "apex_assignments",
+    ]);
+    expect(sdkCartMint.map(({ key }) => key)).toEqual(expect.arrayContaining(identityKeys));
+  });
+
+  it("clears stale consented identity when a consent-pending arm stamp merges into the cart", async () => {
+    const { buildCartAttributeEntries } = await import("./shopify-cart");
+    const staleCartAttributes = {
+      apex_assignments: JSON.stringify([{ e: "exp_prior", v: "var_prior", ep: 8 }]),
+      apex_assignment_authorization: "signed-prior-treatment",
+      apex_experiment_id: "exp_prior",
+      apex_variation_id: "var_prior",
+      apex_assignment_epoch: "8",
+      apex_visitor_id: "visitor_prior",
+      apex_session_id: "session_prior",
+    };
+    const sdkCartMintEntries = buildCartAttributeEntries({
+      assignments: [{
+        experimentId: "exp_sdk_cart_mint",
+        variationId: "var_sdk_cart_mint",
+        assignmentEpoch: 3,
+      }],
+      visitorId: "",
+      sessionId: "",
+    });
+    const merged = {
+      ...staleCartAttributes,
+      ...Object.fromEntries(sdkCartMintEntries.map(({ key, value }) => [key, value])),
+    };
+
+    expect(merged).toEqual({
+      apex_assignments: JSON.stringify([{ e: "exp_sdk_cart_mint", v: "var_sdk_cart_mint", ep: 3 }]),
+      apex_assignment_authorization: "",
+      apex_experiment_id: "",
+      apex_variation_id: "",
+      apex_assignment_epoch: "",
+      apex_visitor_id: "",
+      apex_session_id: "",
+    });
+  });
+
+  it("maps non-empty cart attributes 1:1 to composite metafield keys and type metadata", async () => {
+    const { buildCartAttributeEntries, buildCartMetafieldInputs } = await import("./shopify-cart");
+    const input = {
+      assignments: [{ experimentId: "exp_123", variationId: "var_123", assignmentEpoch: 2 }],
+      visitorId: "visitor_123",
+      sessionId: "session_123",
+    };
+    const attributes = buildCartAttributeEntries(input);
+    const metafields = buildCartMetafieldInputs(input);
+
+    const nonEmptyAttributes = attributes.filter(({ value }) => value !== "");
+    expect(metafields.map(({ key, value }) => ({
+      key: key.replace(/^apex\./, ""),
+      value,
+    }))).toEqual(nonEmptyAttributes);
+    expect(metafields.every((entry) => entry.key.startsWith("apex."))).toBe(true);
+    expect(metafields.map((entry) => entry.type)).toEqual([
+      "json",
+      ...Array(nonEmptyAttributes.length - 1).fill("single_line_text_field"),
+    ]);
+    expect(buildCartMetafieldInputs(input, "merchant_bi").every(
+      (entry) => entry.key.startsWith("merchant_bi."),
+    )).toBe(true);
+  });
+
+  it("omits cart attributes whose metafield values would be empty", async () => {
+    const { buildCartMetafieldInputs } = await import("./shopify-cart");
+    const metafields = buildCartMetafieldInputs({
+      assignments: [{ experimentId: "exp_123", variationId: "var_123" }],
+      visitorId: "visitor_123",
+      sessionId: "session_123",
+    });
+
+    expect(metafields.some(({ value }) => value === "")).toBe(false);
+    expect(metafields.map(({ key }) => key)).not.toContain("apex.apex_assignment_authorization");
+    expect(metafields.map(({ key }) => key)).not.toContain("apex.apex_assignment_epoch");
+  });
+
+  it("returns the complement of the current cart-metafield mirror", async () => {
+    const { getCartMetafieldStaleKeys } = await import("./shopify-cart");
+
+    expect(getCartMetafieldStaleKeys([
+      { key: "merchant_bi.apex_assignments" },
+      { key: "merchant_bi.apex_experiment_id" },
+      { key: "merchant_bi.apex_visitor_id" },
+    ], "merchant_bi")).toEqual([
+      "merchant_bi.apex_assignment_authorization",
+      "merchant_bi.apex_variation_id",
+      "merchant_bi.apex_assignment_epoch",
+      "merchant_bi.apex_session_id",
+    ]);
+  });
+
+  it("returns every cart-metafield key when the current mirror is empty", async () => {
+    const { getCartMetafieldStaleKeys } = await import("./shopify-cart");
+
+    expect(getCartMetafieldStaleKeys([])).toEqual([
+      "apex.apex_assignments",
+      "apex.apex_assignment_authorization",
+      "apex.apex_experiment_id",
+      "apex.apex_variation_id",
+      "apex.apex_assignment_epoch",
+      "apex.apex_visitor_id",
+      "apex.apex_session_id",
+    ]);
+  });
+
+  it("returns no stale keys when the current cart-metafield mirror is full", async () => {
+    const { APEX_CART_ATTRIBUTE_KEYS, getCartMetafieldStaleKeys } = await import("./shopify-cart");
+    const fullMirror = Array.from(APEX_CART_ATTRIBUTE_KEYS, (key) => ({ key: `apex.${key}` }));
+
+    expect(getCartMetafieldStaleKeys(fullMirror)).toEqual([]);
+  });
+
+  it("builds only the visitor cart metafield for identity-only input", async () => {
+    const { buildCartMetafieldInputs } = await import("./shopify-cart");
+    expect(buildCartMetafieldInputs({
+      assignments: [],
+      identityOnly: true,
+      visitorId: "visitor_123",
+      sessionId: "session_123",
+    })).toEqual([{
+      key: "apex.apex_visitor_id",
+      type: "single_line_text_field",
+      value: "visitor_123",
+    }]);
+  });
+
+  it("does not let an identity-only stamp suppress a later holdout control clear", async () => {
+    const { syncShopifyCartAttributes } = await import("./shopify-cart");
+    const identity = {
+      assignments: [],
+      visitorId: "visitor_123",
+      sessionId: "session_123",
+    };
+
+    await expect(syncShopifyCartAttributes({
+      ...identity,
+      identityOnly: true,
+    })).resolves.toEqual({ status: "sent" });
+    await expect(syncShopifyCartAttributes({
+      ...identity,
+      controlStamp: true,
+    })).resolves.toEqual({ status: "sent" });
+
+    const writes = vi.mocked(globalThis.fetch).mock.calls.map(([, init]) =>
+      JSON.parse(String(init?.body)).attributes
+    );
+    expect(writes).toEqual([
+      { apex_visitor_id: "visitor_123" },
+      {
+        apex_assignments: "[]",
+        apex_assignment_authorization: "",
+        apex_experiment_id: "",
+        apex_variation_id: "",
+        apex_assignment_epoch: "",
+        apex_visitor_id: "visitor_123",
+        apex_session_id: "session_123",
+      },
+    ]);
+  });
+
+  it("stops cart writes for the session after Shopify returns 405", async () => {
+    globalThis.fetch = vi.fn()
+      .mockResolvedValueOnce(new Response("method not allowed", { status: 405 })) as any;
+    const { syncShopifyCartAttributes } = await import("./shopify-cart");
+    const input = {
+      assignments: [{ experimentId: "exp_405", variationId: "var_405" }],
+      visitorId: "visitor_405",
+      sessionId: "session_405",
+    };
+
+    await expect(syncShopifyCartAttributes(input)).resolves.toEqual({
+      status: "failed",
+      reason: "cart_update_405",
+    });
+    await expect(syncShopifyCartAttributes({
+      ...input,
+      sessionId: "session_after_405",
+    })).resolves.toEqual({
+      status: "skipped",
+      reason: "cart_update_405_circuit_break",
+    });
+
+    expect(globalThis.fetch).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps the 405 circuit breaker active when sessionStorage throws", async () => {
+    (globalThis as any).sessionStorage = {
+      getItem: () => { throw new Error("storage blocked"); },
+      setItem: () => { throw new Error("storage blocked"); },
+    };
+    globalThis.fetch = vi.fn(async () =>
+      new Response("method not allowed", { status: 405 })) as any;
+    const { syncShopifyCartAttributes } = await import("./shopify-cart");
+    const input = {
+      assignments: [{ experimentId: "exp_405_blocked_storage", variationId: "var_405" }],
+      visitorId: "visitor_405",
+      sessionId: "session_405",
+    };
+
+    await expect(syncShopifyCartAttributes(input)).resolves.toEqual({
+      status: "failed",
+      reason: "cart_update_405",
+    });
+    await expect(syncShopifyCartAttributes({
+      ...input,
+      sessionId: "session_after_405",
+    })).resolves.toEqual({
+      status: "skipped",
+      reason: "cart_update_405_circuit_break",
+    });
+
+    expect(globalThis.fetch).toHaveBeenCalledTimes(1);
+  });
+
   it("keeps ordinary cart attribution best-effort when assignment proof is unavailable", async () => {
     globalThis.fetch = vi.fn()
       .mockResolvedValueOnce(new Response("unavailable", { status: 503 }))
@@ -486,8 +1018,8 @@ describe("syncShopifyCartAttributes", () => {
       assignments: [],
     }));
     await expect(older).resolves.toEqual({
-      status: "failed",
-      reason: "authorization_failed",
+      status: "skipped",
+      reason: "superseded",
     });
 
     expect(globalThis.fetch).toHaveBeenCalledTimes(3);
@@ -1249,6 +1781,170 @@ describe("syncShopifyCartAttributes", () => {
     });
   });
 
+  it("keeps page-inactive attribution out of authoritative price adoption", async () => {
+    const token = JSON.stringify({
+      v: 2,
+      p: {
+        price: {
+          v: 1,
+          r: 3,
+          c: "b".repeat(64),
+          x: "2026-07-20",
+          cartHash: "c".repeat(64),
+          a: [{ e: "exp_price", v: "var_treatment", ep: 2 }],
+          s: "d".repeat(64),
+        },
+      },
+    });
+    globalThis.fetch = vi.fn()
+      .mockResolvedValueOnce(Response.json({
+        assignments: [{
+          experiment_id: "exp_price",
+          variation_id: "var_treatment",
+          assignment_epoch: 2,
+          commerce_price_only: true,
+        }],
+        commerce_authorization: token,
+      }))
+      .mockResolvedValueOnce(new Response("ok", { status: 200 })) as any;
+    const { syncShopifyCartAttributes } = await import("./shopify-cart");
+    const adoptPriceAssignments = vi.fn(() => true);
+
+    await expect(syncShopifyCartAttributes({
+      assignments: [{
+        experimentId: "exp_price",
+        variationId: "var_treatment",
+        assignmentEpoch: 2,
+        pageActive: false,
+      }],
+      visitorId: "visitor_123",
+      sessionId: "session_123",
+      shopId: "shop_123",
+      endpoint: "https://events.example.com/events",
+      ingestSignature: "ingest-token",
+      cartToken: "cart-token",
+      priceAuthorizationRevision: 3,
+      priceExperimentIds: ["exp_price"],
+      adoptPriceAssignments,
+    })).resolves.toEqual({ status: "sent" });
+
+    expect(adoptPriceAssignments).not.toHaveBeenCalled();
+    const cartUpdateBody = JSON.parse(
+      String(vi.mocked(globalThis.fetch).mock.calls[1]?.[1]?.body),
+    );
+    expect(cartUpdateBody.attributes).toMatchObject({
+      apex_assignments: JSON.stringify([{ e: "exp_price", v: "var_treatment", ep: 2 }]),
+      apex_assignment_authorization: token,
+    });
+  });
+
+  it("preserves page-inactive price attribution across a signed empty price plane", async () => {
+    const token = JSON.stringify({
+      v: 2,
+      p: {
+        price: {
+          v: 1,
+          r: 3,
+          c: "b".repeat(64),
+          x: "2026-07-20",
+          cartHash: "c".repeat(64),
+          a: [],
+          s: "d".repeat(64),
+        },
+      },
+    });
+    globalThis.fetch = vi.fn()
+      .mockResolvedValueOnce(Response.json({
+        assignments: [],
+        commerce_authorization: token,
+      }))
+      .mockResolvedValueOnce(new Response("ok", { status: 200 })) as any;
+    const { syncShopifyCartAttributes } = await import("./shopify-cart");
+    const adoptPriceAssignments = vi.fn(() => true);
+
+    await expect(syncShopifyCartAttributes({
+      assignments: [{
+        experimentId: "exp_price",
+        variationId: "var_treatment",
+        assignmentEpoch: 2,
+        pageActive: false,
+      }],
+      visitorId: "visitor_123",
+      sessionId: "session_123",
+      shopId: "shop_123",
+      endpoint: "https://events.example.com/events",
+      ingestSignature: "ingest-token",
+      cartToken: "cart-token",
+      priceAuthorizationRevision: 3,
+      priceExperimentIds: ["exp_price"],
+      adoptPriceAssignments,
+    })).resolves.toEqual({ status: "sent" });
+
+    expect(adoptPriceAssignments).not.toHaveBeenCalled();
+    const cartUpdateBody = JSON.parse(
+      String(vi.mocked(globalThis.fetch).mock.calls[1]?.[1]?.body),
+    );
+    expect(JSON.parse(cartUpdateBody.attributes.apex_assignments)).toEqual([
+      { e: "exp_price", v: "var_treatment", ep: 2 },
+    ]);
+    expect(cartUpdateBody.attributes.apex_assignment_authorization).toBe(token);
+  });
+
+  it("keeps a page-inactive offer pin out of adoption without duplicating attribution", async () => {
+    const token = JSON.stringify({
+      v: 2,
+      p: {
+        offers: {
+          v: 1,
+          a: [{ e: "exp_offer", v: "var_treatment", ep: 3 }],
+        },
+      },
+    });
+    globalThis.fetch = vi.fn()
+      .mockResolvedValueOnce(Response.json({
+        assignments: [{
+          experiment_id: "exp_offer",
+          variation_id: "var_treatment",
+          assignment_epoch: 3,
+          commerce_price_only: true,
+        }],
+        commerce_authorization: token,
+      }))
+      .mockResolvedValueOnce(new Response("ok", { status: 200 })) as any;
+    const { syncShopifyCartAttributes } = await import("./shopify-cart");
+    const adoptOffersAssignments = vi.fn(() => true);
+    const canAdoptOffersAssignments = vi.fn(() => true);
+
+    await expect(syncShopifyCartAttributes({
+      assignments: [{
+        experimentId: "exp_offer",
+        variationId: "var_treatment",
+        assignmentEpoch: 3,
+        pageActive: false,
+      }],
+      visitorId: "visitor_123",
+      sessionId: "session_123",
+      shopId: "shop_123",
+      endpoint: "https://events.example.com/events",
+      ingestSignature: "ingest-token",
+      cartToken: "cart-token",
+      offersAuthorizationRevision: 5,
+      offersExperimentIds: ["exp_offer"],
+      adoptOffersAssignments,
+      canAdoptOffersAssignments,
+    })).resolves.toEqual({ status: "sent" });
+
+    expect(canAdoptOffersAssignments).not.toHaveBeenCalled();
+    expect(adoptOffersAssignments).not.toHaveBeenCalled();
+    const cartUpdateBody = JSON.parse(
+      String(vi.mocked(globalThis.fetch).mock.calls[1]?.[1]?.body),
+    );
+    expect(JSON.parse(cartUpdateBody.attributes.apex_assignments)).toEqual([
+      { e: "exp_offer", v: "var_treatment", ep: 3 },
+    ]);
+    expect(cartUpdateBody.attributes.apex_assignment_authorization).toBe(token);
+  });
+
   it("adopts null pins only inside the V2 evaluated set and preserves browser-only assignments", async () => {
     const browserOnlyAssignment = {
       experimentId: "exp_browser_only",
@@ -1437,8 +2133,8 @@ describe("syncShopifyCartAttributes", () => {
       commerce_authorization: olderToken,
     }));
     await expect(older).resolves.toEqual({
-      status: "failed",
-      reason: "authorization_failed",
+      status: "skipped",
+      reason: "superseded",
     });
     expect(adoptPriceAssignments).toHaveBeenCalledOnce();
     expect(runtimeAssignments).toEqual([{
@@ -1528,8 +2224,8 @@ describe("syncShopifyCartAttributes", () => {
       commerce_authorization: nullPinToken,
     }));
     await expect(older).resolves.toEqual({
-      status: "failed",
-      reason: "authorization_failed",
+      status: "skipped",
+      reason: "superseded",
     });
     expect(adoptPriceAssignments).toHaveBeenCalledOnce();
     expect(runtimeAssignments).toEqual([{
@@ -1915,6 +2611,7 @@ describe("syncShopifyCartAttributes", () => {
       cartHash,
       a: [{ e: assignment.experimentId, v: assignment.variationId, ep: assignment.assignmentEpoch }],
     });
+    const onCartToken = vi.fn();
     globalThis.fetch = vi.fn((url) => {
       if (url === "/cart.js") {
         cartReads += 1;
@@ -1951,6 +2648,7 @@ describe("syncShopifyCartAttributes", () => {
       ingestSignature: "ingest-token",
       priceAuthorizationRevision: 3,
       priceExperimentIds: [assignment.experimentId],
+      onCartToken,
     };
 
     const cartA = syncShopifyCartAttributes(input);
@@ -1960,8 +2658,8 @@ describe("syncShopifyCartAttributes", () => {
 
     resolveCartA(Response.json({ token: "cart-a?key=a" }));
     await expect(cartA).resolves.toEqual({
-      status: "failed",
-      reason: "authorization_failed",
+      status: "skipped",
+      reason: "superseded",
     });
     await expect(cartB).resolves.toEqual({ status: "sent" });
 
@@ -1970,6 +2668,8 @@ describe("syncShopifyCartAttributes", () => {
       .filter(([url]) => url === "https://events.example.com/v1/assign")
       .map(([, init]) => JSON.parse(String(init?.body)).cart_token);
     expect(authorizationCartTokens).toEqual(["cart-a?key=a", "cart-b?key=b"]);
+    expect(onCartToken).toHaveBeenCalledWith("cart-a");
+    expect(onCartToken).toHaveBeenCalledWith("cart-b");
     const cartUpdates = calls.filter(([url]) => url === "/cart/update.js");
     expect(cartUpdates).toHaveLength(1);
     expect(JSON.parse(String(cartUpdates[0]?.[1]?.body)).attributes)
@@ -2035,8 +2735,8 @@ describe("syncShopifyCartAttributes", () => {
 
     resolveCartA(Response.json({ token: "cart-a?key=a" }));
     await expect(cartA).resolves.toEqual({
-      status: "failed",
-      reason: "authorization_failed",
+      status: "skipped",
+      reason: "superseded",
     });
     await expect(cartB).resolves.toEqual({
       status: "failed",
@@ -2163,17 +2863,18 @@ describe("syncShopifyCartAttributes", () => {
     const first = syncShopifyCartAttributes(firstInput);
     await vi.waitFor(() => expect(globalThis.fetch).toHaveBeenCalledTimes(1));
     const second = syncShopifyCartAttributes(secondInput);
-    await vi.waitFor(() => expect(globalThis.fetch).toHaveBeenCalledTimes(2));
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(globalThis.fetch).toHaveBeenCalledTimes(1);
 
+    resolveFirst(new Response("ok", { status: 200 }));
+    await vi.waitFor(() => expect(globalThis.fetch).toHaveBeenCalledTimes(2));
+    expect(sessionStorage.getItem("drip_cart_attr")).toBeNull();
     resolveSecond(new Response("ok", { status: 200 }));
     await expect(second).resolves.toEqual({ status: "sent" });
+    await expect(first).resolves.toEqual({ status: "skipped", reason: "superseded" });
     const newestStamp = sessionStorage.getItem("drip_cart_attr");
     expect(newestStamp).toContain("exp_new");
 
-    resolveFirst(new Response("ok", { status: 200 }));
-    await expect(first).resolves.toEqual({ status: "sent" });
-    expect(sessionStorage.getItem("drip_cart_attr")).toBe(newestStamp);
-
     vi.mocked(globalThis.fetch).mockClear();
     await expect(syncShopifyCartAttributes(secondInput)).resolves.toEqual({
       status: "sent",
@@ -2183,6 +2884,7 @@ describe("syncShopifyCartAttributes", () => {
   });
 
   it("does not let stale authorization mutate the Shopify cart", async () => {
+    vi.useFakeTimers();
     let resolveOlderAuthorization!: (response: Response) => void;
     let resolveNewerAuthorization!: (response: Response) => void;
     globalThis.fetch = vi.fn((url) => {
@@ -2210,9 +2912,11 @@ describe("syncShopifyCartAttributes", () => {
     });
 
     const older = syncShopifyCartAttributes(input("exp_old", "var_old", 1));
-    await vi.waitFor(() => expect(globalThis.fetch).toHaveBeenCalledTimes(1));
+    await vi.advanceTimersByTimeAsync(0);
+    expect(globalThis.fetch).toHaveBeenCalledTimes(1);
     const newer = syncShopifyCartAttributes(input("exp_new", "var_new", 2));
-    await vi.waitFor(() => expect(globalThis.fetch).toHaveBeenCalledTimes(2));
+    await vi.advanceTimersByTimeAsync(0);
+    expect(globalThis.fetch).toHaveBeenCalledTimes(2);
 
     resolveNewerAuthorization(new Response(JSON.stringify({
       assignments: [{
@@ -2234,8 +2938,8 @@ describe("syncShopifyCartAttributes", () => {
       commerce_authorization: "older-proof",
     }), { status: 200, headers: { "Content-Type": "application/json" } }));
     await expect(older).resolves.toEqual({
-      status: "failed",
-      reason: "authorization_failed",
+      status: "skipped",
+      reason: "superseded",
     });
     expect(globalThis.fetch).toHaveBeenCalledTimes(3);
 
@@ -2250,6 +2954,7 @@ describe("syncShopifyCartAttributes", () => {
   });
 
   it("lets price-plane teardown invalidate an in-flight cart authorization before it writes", async () => {
+    vi.useFakeTimers();
     let resolveAuthorization!: (response: Response) => void;
     globalThis.fetch = vi.fn((url) => {
       if (url === "/cart.js") {
@@ -2287,9 +2992,11 @@ describe("syncShopifyCartAttributes", () => {
       commerce_authorization: "stale-proof",
     }));
 
+    await vi.advanceTimersByTimeAsync(0);
+
     await expect(sync).resolves.toEqual({
-      status: "failed",
-      reason: "authorization_failed",
+      status: "skipped",
+      reason: "superseded",
     });
     expect(globalThis.fetch).toHaveBeenCalledTimes(2);
     expect(sessionStorage.getItem("drip_cart_attr")).toBeNull();
@@ -2326,7 +3033,7 @@ describe("syncShopifyCartAttributes", () => {
     })).resolves.toEqual({ status: "sent", reason: "already_stamped" });
 
     resolveOlder(new Response("ok", { status: 200 }));
-    await expect(older).resolves.toEqual({ status: "sent" });
+    await expect(older).resolves.toEqual({ status: "skipped", reason: "superseded" });
     expect(sessionStorage.getItem("drip_cart_attr")).toBe(newestStamp);
   });
 
@@ -2344,6 +3051,8 @@ describe("syncShopifyCartAttributes", () => {
           assignment_epoch: 2,
         }],
         commerce_authorization: "signed-envelope",
+        handoff_persisted: false,
+        handoff_stale_risk: false,
       }))
       .mockResolvedValueOnce(new Response("ok", { status: 200 })) as any;
     const { syncShopifyCartAttributes } = await import("./shopify-cart");
@@ -2770,6 +3479,7 @@ describe("syncShopifyCartAttributes", () => {
 
     const proofBody = JSON.parse(String(vi.mocked(globalThis.fetch).mock.calls[0]?.[1]?.body));
     expect(proofBody.cart_token).toBe("gid://shopify/Cart/headless?key=headless-secret");
+    expect(proofBody.persist_function_handoff).toBe(true);
     const cartUpdateBody = JSON.parse(
       String(vi.mocked(globalThis.fetch).mock.calls[1]?.[1]?.body),
     );