@drip-apex/sdk 0.1.0 → 0.2.0

package/src/shopify-cart.ts

@@ -1,16 +1,24 @@
 import { fetchWithoutShopifyCartMutationNotification } from "./shopify-cart-events";
+import { normalizeEndpoint } from "./endpoint";
 
 const CART_ATTRIBUTE_SYNC_KEY = "drip_cart_attr";
+const CART_ATTRIBUTE_WRITE_CIRCUIT_BREAK_KEY = "drip_cart_attr_write_405";
+const CART_WRITE_TIMEOUT_MS = 10_000;
 
 export type CartAssignment = {
   experimentId: string;
   variationId: string;
   assignmentEpoch?: number;
   commercePriceOnly?: boolean;
+  pageActive?: boolean;
 };
 
 export type CartAttributeSyncInput = {
   assignments: CartAssignment[];
+  /** Allows an explicit empty control stamp to clear prior treatment attributes. */
+  controlStamp?: boolean;
+  /** Writes only storefront identity without disturbing existing treatment attributes. */
+  identityOnly?: boolean;
   requiredAssignments?: CartAssignment[];
   visitorId: string;
   sessionId: string;
@@ -19,6 +27,8 @@ export type CartAttributeSyncInput = {
   ingestSignature?: string;
   url?: string;
   environment?: string;
+  platform?: string;
+  onAttributionEnvelope?: (envelope: string) => void;
   cartToken?: string;
   offersAuthorizationRevision?: number;
   offersExperimentIds?: string[];
@@ -35,6 +45,8 @@ export type CartAttributeSyncInput = {
   authorizePriceDisplayAssignments?: (assignments: CartAssignment[]) => void;
   authorizeShippingDisplayAssignments?: (assignments: CartAssignment[]) => void;
   authorizeOffersDisplayAssignments?: (assignments: CartAssignment[]) => void;
+  /** Receives the normalized Shopify cart token already observed by this sync. */
+  onCartToken?: (cartToken: string) => void;
   /** Receives the parsed /cart/update.js response body after a successful stamp write. */
   onCartSnapshot?: (cart: unknown) => void;
   exclusionGroupSelections?: Array<{
@@ -45,6 +57,57 @@ export type CartAttributeSyncInput = {
 };
 
 export type CartAttributeEntry = { key: string; value: string };
+export type CartMetafieldInput = {
+  key: string;
+  type: string;
+  value: string;
+};
+
+export type CartMetafieldKeyInput = Pick<CartMetafieldInput, "key">;
+
+const APEX_CART_ATTRIBUTE_KEY_VALUES = [
+  "apex_assignments",
+  "apex_assignment_authorization",
+  "apex_experiment_id",
+  "apex_variation_id",
+  "apex_assignment_epoch",
+  "apex_visitor_id",
+  "apex_session_id",
+] as const;
+
+type ApexCartAttributeKey = (typeof APEX_CART_ATTRIBUTE_KEY_VALUES)[number];
+
+/** Every Shopify cart attribute key owned and replaced by Apex. */
+export const APEX_CART_ATTRIBUTE_KEYS: ReadonlySet<string> = new Set(
+  APEX_CART_ATTRIBUTE_KEY_VALUES,
+);
+
+/** Normalize Shopify metafield namespaces accepted by the Apex cart mirror. */
+export function normalizeCartMetafieldNamespace(namespace?: string): string {
+  const requestedNamespace = namespace?.trim();
+  return requestedNamespace && /^[A-Za-z0-9_-]{2,255}$/.test(requestedNamespace)
+    ? requestedNamespace
+    : "apex";
+}
+
+/** Return every Apex cart-metafield key missing from the supplied mirror. */
+export function getCartMetafieldStaleKeys(
+  currentMetafields: readonly CartMetafieldKeyInput[],
+  namespace = "apex",
+): string[] {
+  const normalizedNamespace = normalizeCartMetafieldNamespace(namespace);
+  const currentKeys = new Set(currentMetafields.map(({ key }) => key));
+  return APEX_CART_ATTRIBUTE_KEY_VALUES
+    .map((key) => `${normalizedNamespace}.${key}`)
+    .filter((key) => !currentKeys.has(key));
+}
+
+function apexCartAttributeEntry(
+  key: ApexCartAttributeKey,
+  value: string,
+): CartAttributeEntry {
+  return { key, value };
+}
 
 export type CartAttributeSyncResult = {
   status: "sent" | "skipped" | "failed";
@@ -56,7 +119,10 @@ export type CartAttributeSyncOptions = {
   force?: boolean;
 };
 
-const inFlightBySignature = new Map<string, Promise<CartAttributeSyncResult>>();
+const inFlightBySignature = new Map<string, {
+  generation: number;
+  promise: Promise<CartAttributeSyncResult>;
+}>();
 const validatedAuthorizationSignatures = new Set<string>();
 let authorizedAssignmentsBySignature: {
   price: Map<string, CartAssignment[]>;
@@ -64,10 +130,31 @@ let authorizedAssignmentsBySignature: {
   offers: Map<string, CartAssignment[]>;
 } | null = null;
 let latestSyncGeneration = 0;
+let pendingCartAttributeWrite: {
+  generation: number;
+  submit: (signal: AbortSignal | undefined) => Promise<Response>;
+  resolve: (outcome: CartAttributeWriteOutcome) => void;
+} | null = null;
+type CartAttributeWriterState =
+  | { status: "idle" }
+  | {
+      status: "in-flight";
+      generation: number;
+      controller: AbortController | null;
+      abortReason: "cart_write_aborted" | "cart_write_timeout" | null;
+    };
+let cartAttributeWriterState: CartAttributeWriterState = { status: "idle" };
+let cartAttributeWriteCircuitBrokenInMemory = false;
 
-/** Prevent an obsolete authorization response from reaching the cart write. */
+/** Prevent an obsolete authorization response or pending request from reaching the cart. */
 export function invalidateShopifyCartAttributeSync(): void {
   latestSyncGeneration += 1;
+  pendingCartAttributeWrite?.resolve({ status: "superseded" });
+  pendingCartAttributeWrite = null;
+  if (cartAttributeWriterState.status === "in-flight") {
+    cartAttributeWriterState.abortReason = "cart_write_aborted";
+    cartAttributeWriterState.controller?.abort();
+  }
 }
 
 function ensureAuthorizedAssignmentCache() {
@@ -153,6 +240,26 @@ function writeStampedSignature(signature: string): void {
   }
 }
 
+function cartAttributeWriteCircuitBroken(): boolean {
+  if (cartAttributeWriteCircuitBrokenInMemory) return true;
+  try {
+    cartAttributeWriteCircuitBrokenInMemory =
+      sessionStorage.getItem(CART_ATTRIBUTE_WRITE_CIRCUIT_BREAK_KEY) === "1";
+    return cartAttributeWriteCircuitBrokenInMemory;
+  } catch {
+    return false;
+  }
+}
+
+function breakCartAttributeWriteCircuit(): void {
+  cartAttributeWriteCircuitBrokenInMemory = true;
+  try {
+    sessionStorage.setItem(CART_ATTRIBUTE_WRITE_CIRCUIT_BREAK_KEY, "1");
+  } catch {
+    // Storage persistence is best-effort; the module-level breaker remains active.
+  }
+}
+
 function normalizeTargetingUrl(value: unknown): string | null {
   if (typeof value !== "string") return null;
   const trimmed = value.trim();
@@ -171,6 +278,11 @@ function normalizeTargetingUrl(value: unknown): string | null {
 
 function syncSignature(input: CartAttributeSyncInput): string {
   return JSON.stringify({
+    ...(input.controlStamp
+      ? { mode: "control" }
+      : input.identityOnly
+        ? { mode: "identity" }
+        : {}),
     assignments: input.assignments
       .map((assignment) => [
         assignment.experimentId,
@@ -244,10 +356,26 @@ function normalizeProofCartToken(value: unknown): string | null {
   return typeof value === "string" && normalizeCartToken(value) ? value.trim() : null;
 }
 
+function observeCartToken(
+  input: CartAttributeSyncInput,
+  value: unknown,
+): string | null {
+  const proofToken = normalizeProofCartToken(value);
+  const cartToken = normalizeCartToken(proofToken);
+  if (cartToken) {
+    try {
+      input.onCartToken?.(cartToken);
+    } catch {
+      // Cart-token observers must not affect cart authorization or writes.
+    }
+  }
+  return proofToken;
+}
+
 async function resolveChargeAuthorizationCartToken(
   input: CartAttributeSyncInput,
 ): Promise<string | null> {
-  const supplied = normalizeProofCartToken(input.cartToken);
+  const supplied = observeCartToken(input, input.cartToken);
   if (supplied) return supplied;
   if (
     input.priceAuthorizationRevision == null &&
@@ -261,7 +389,7 @@ async function resolveChargeAuthorizationCartToken(
       cache: "no-store",
     });
     if (!response.ok) return null;
-    return normalizeProofCartToken(((await response.json()) as { token?: unknown }).token);
+    return observeCartToken(input, ((await response.json()) as { token?: unknown }).token);
   } catch {
     return null;
   }
@@ -272,9 +400,20 @@ export function syncShopifyCartAttributes(
   options: CartAttributeSyncOptions = {},
 ): Promise<CartAttributeSyncResult> {
   try {
+    // An empty visitor ID is the fail-closed sentinel for the identity-free
+    // consent-pending input built by index.ts.
+    const armOnly = input.assignments.length > 0 && !input.visitorId;
     if (!isShopifyStorefront()) return Promise.resolve({ status: "skipped", reason: "not_shopify" });
     if (typeof fetch !== "function") return Promise.resolve({ status: "skipped", reason: "fetch_missing" });
-    if (!input.assignments[0] && !requiresCommerceAuthorization(input)) {
+    if (cartAttributeWriteCircuitBroken()) {
+      return Promise.resolve({ status: "skipped", reason: "cart_update_405_circuit_break" });
+    }
+    if (
+      !input.assignments[0] &&
+      !input.controlStamp &&
+      !input.identityOnly &&
+      !requiresCommerceAuthorization(input)
+    ) {
       return Promise.resolve({ status: "skipped", reason: "no_assignments" });
     }
     if (cannotRequestRequiredCommerceAuthorization(input)) {
@@ -284,17 +423,35 @@ export function syncShopifyCartAttributes(
     const signature = syncSignature(input);
     const existingInFlight = inFlightBySignature.get(signature);
     if (existingInFlight) {
-      if (!options.force) return existingInFlight;
+      if (!options.force && existingInFlight.generation === latestSyncGeneration) {
+        return existingInFlight.promise;
+      }
+      if (!options.force) {
+        // A -> B -> A must not attach the final A to the first A. B may write
+        // after that request, so enqueue a fresh A once the original settles.
+        const continuationGeneration = latestSyncGeneration;
+        return existingInFlight.promise.then(() =>
+          continuationGeneration === latestSyncGeneration
+            ? syncShopifyCartAttributes(input, options)
+            : { status: "skipped", reason: "superseded" },
+        );
+      }
       // A forced sync follows a real cart mutation, so cart identity may have
       // changed underneath the pending request. Invalidate it immediately;
       // ordinary overlaps still share the existing request.
       latestSyncGeneration += 1;
-      return existingInFlight.then(() => syncShopifyCartAttributes(input, options));
+      const continuationGeneration = latestSyncGeneration;
+      return existingInFlight.promise.then(() =>
+        continuationGeneration === latestSyncGeneration
+          ? syncShopifyCartAttributes(input, options)
+          : { status: "skipped", reason: "superseded" },
+      );
     }
     const generation = ++latestSyncGeneration;
     const requiresCurrentAssignmentProof = requiresCommerceAuthorization(input);
     if (
       !options.force &&
+      !armOnly &&
       readStampedSignature() === signature &&
       (!requiresCurrentAssignmentProof || validatedAuthorizationSignatures.has(signature))
     ) {
@@ -328,20 +485,36 @@ export function syncShopifyCartAttributes(
       }): Promise<{
         response: Response | null;
         authorizationCompleted: boolean;
+        writeCircuitBroken: boolean;
         authorizedSignature: string;
         authorizedPriceAssignments: CartAssignment[];
         authorizedShippingAssignments: CartAssignment[];
         authorizedOffersAssignments: CartAssignment[];
         offersAdoptionAssignments?: CartAssignment[];
+        writeOutcome: CartAttributeWriteOutcome;
       }> => {
-        if (!cartWriteAllowed || generation !== latestSyncGeneration) {
+        if (generation !== latestSyncGeneration) {
+          return {
+            response: null,
+            authorizationCompleted: completed,
+            writeCircuitBroken: false,
+            authorizedSignature,
+            authorizedPriceAssignments: [],
+            authorizedShippingAssignments: [],
+            authorizedOffersAssignments: [],
+            writeOutcome: { status: "superseded" },
+          };
+        }
+        if (!cartWriteAllowed) {
           return {
             response: null,
             authorizationCompleted: false,
+            writeCircuitBroken: false,
             authorizedSignature,
             authorizedPriceAssignments: [],
             authorizedShippingAssignments: [],
             authorizedOffersAssignments: [],
+            writeOutcome: { status: "failed", reason: "authorization_failed" },
           };
         }
         const authorizedInput = { ...input, assignments };
@@ -367,31 +540,65 @@ export function syncShopifyCartAttributes(
         const attributes = Object.fromEntries(
           buildCartAttributeEntries(authorizedInput, token).map((entry) => [entry.key, entry.value]),
         );
-        const response = await fetchWithoutShopifyCartMutationNotification("/cart/update.js", {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ attributes }),
-          keepalive: true,
-        });
+        if (cartAttributeWriteCircuitBroken()) {
+          return {
+            response: null,
+            authorizationCompleted: completed,
+            writeCircuitBroken: true,
+            authorizedSignature,
+            authorizedPriceAssignments,
+            authorizedShippingAssignments,
+            authorizedOffersAssignments,
+            offersAdoptionAssignments,
+            writeOutcome: { status: "failed", reason: "cart_update_405_circuit_break" },
+          };
+        }
+        const writeOutcome = await submitNewestCartAttributeWrite(generation, (signal) =>
+          fetchWithoutShopifyCartMutationNotification("/cart/update.js", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ attributes }),
+            keepalive: true,
+            signal,
+          })
+        );
+        const response = writeOutcome.status === "sent" ? writeOutcome.response : null;
+        if (response?.status === 405) breakCartAttributeWriteCircuit();
         return {
           response,
           authorizationCompleted: completed,
+          writeCircuitBroken: false,
           authorizedSignature,
           authorizedPriceAssignments,
           authorizedShippingAssignments,
           authorizedOffersAssignments,
           offersAdoptionAssignments,
+          writeOutcome,
         };
       })
       .then(({
         response,
         authorizationCompleted,
+        writeCircuitBroken,
         authorizedSignature: completedSignature,
         authorizedPriceAssignments,
         authorizedShippingAssignments,
         authorizedOffersAssignments,
         offersAdoptionAssignments,
+        writeOutcome,
       }) => {
+        if (writeOutcome.status === "superseded") {
+          return { status: "skipped", reason: "superseded" } as const;
+        }
+        if (writeCircuitBroken) {
+          return { status: "skipped", reason: "cart_update_405_circuit_break" } as const;
+        }
+        if (writeOutcome.status === "aborted" || writeOutcome.status === "timeout") {
+          return { status: "failed", reason: writeOutcome.reason } as const;
+        }
+        if (writeOutcome.status === "failed") {
+          return { status: "failed", reason: writeOutcome.reason } as const;
+        }
         if (!authorizationCompleted) {
           return { status: "failed", reason: "authorization_failed" } as const;
         }
@@ -411,7 +618,7 @@ export function syncShopifyCartAttributes(
           ) {
             return { status: "failed", reason: "offers_adoption_failed" } as const;
           }
-          if (input.onCartSnapshot) {
+          if (input.onCartSnapshot || input.onCartToken) {
             // The stamp-write response body is the full updated cart — a free
             // snapshot consumers use to rediscover Apex-managed lines without
             // an extra request (best-effort; never blocks the sync result).
@@ -420,10 +627,13 @@ export function syncShopifyCartAttributes(
             // stamped envelope does not authorize could retain or insert a
             // gift the Function will not discount.
             void response.clone().json()
-              .then((cart) => input.onCartSnapshot?.(cart))
+              .then((cart) => {
+                observeCartToken(input, (cart as { token?: unknown })?.token);
+                input.onCartSnapshot?.(cart);
+              })
               .catch(() => {});
           }
-          writeStampedSignature(completedSignature);
+          if (!armOnly) writeStampedSignature(completedSignature);
           if (requiresCurrentAssignmentProof) {
             validatedAuthorizationSignatures.clear();
             validatedAuthorizationSignatures.add(completedSignature);
@@ -463,11 +673,11 @@ export function syncShopifyCartAttributes(
         reason: error instanceof Error ? error.message : String(error),
       }) as const)
       .finally(() => {
-        if (inFlightBySignature.get(signature) === pending) {
+        if (inFlightBySignature.get(signature)?.promise === pending) {
           inFlightBySignature.delete(signature);
         }
       });
-    inFlightBySignature.set(signature, pending);
+    inFlightBySignature.set(signature, { generation, promise: pending });
     return pending;
   } catch {
     // Shopify cart attribution must never block or break assignment rendering.
@@ -475,6 +685,93 @@ export function syncShopifyCartAttributes(
   }
 }
 
+function submitNewestCartAttributeWrite(
+  generation: number,
+  submit: (signal: AbortSignal | undefined) => Promise<Response>,
+): Promise<CartAttributeWriteOutcome> {
+  const outcome = new Promise<CartAttributeWriteOutcome>((resolve) => {
+    const requested = { generation, submit, resolve };
+    if (!pendingCartAttributeWrite || generation >= pendingCartAttributeWrite.generation) {
+      pendingCartAttributeWrite?.resolve({ status: "superseded" });
+      pendingCartAttributeWrite = requested;
+    } else {
+      resolve({ status: "superseded" });
+    }
+  });
+  if (cartAttributeWriterState.status === "idle") drainCartAttributeWrites();
+  return outcome;
+}
+
+function drainCartAttributeWrites(): void {
+  if (cartAttributeWriterState.status !== "idle") return;
+  const requested = pendingCartAttributeWrite;
+  pendingCartAttributeWrite = null;
+  if (!requested) return;
+  if (requested.generation !== latestSyncGeneration) {
+    requested.resolve({ status: "superseded" });
+    drainCartAttributeWrites();
+    return;
+  }
+
+  const controller = typeof AbortController === "undefined" ? null : new AbortController();
+  const inFlight: Extract<CartAttributeWriterState, { status: "in-flight" }> = {
+    status: "in-flight",
+    generation: requested.generation,
+    controller,
+    abortReason: null,
+  };
+  cartAttributeWriterState = inFlight;
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<never>((_resolve, reject) => {
+    timeout = setTimeout(() => {
+      inFlight.abortReason = "cart_write_timeout";
+      controller?.abort();
+      reject(new Error("cart_write_timeout"));
+    }, CART_WRITE_TIMEOUT_MS);
+    controller?.signal.addEventListener("abort", () => {
+      reject(new Error(inFlight.abortReason ?? "cart_write_aborted"));
+    }, { once: true });
+  });
+
+  Promise.race([requested.submit(controller?.signal), deadline])
+    .then((response) => {
+      requested.resolve(requested.generation === latestSyncGeneration
+        ? { status: "sent", response }
+        : { status: "superseded" });
+    })
+    .catch((error: unknown) => {
+      if (inFlight.abortReason === "cart_write_aborted") {
+        requested.resolve({ status: "aborted", reason: "cart_write_aborted" });
+      } else if (inFlight.abortReason === "cart_write_timeout") {
+        requested.resolve({ status: "timeout", reason: "cart_write_timeout" });
+      } else {
+        requested.resolve({
+          status: "failed",
+          reason: error instanceof Error ? error.message : String(error),
+        });
+      }
+    })
+    .finally(() => {
+      if (timeout !== undefined) clearTimeout(timeout);
+      // Publish idle and consume the pending slot synchronously. An enqueue can
+      // therefore observe either this in-flight state or an idle writer that it
+      // starts itself, never an unowned pending request.
+      cartAttributeWriterState = { status: "idle" };
+      drainCartAttributeWrites();
+    });
+}
+
+type CartAttributeWriteOutcome =
+  | { status: "sent"; response: Response }
+  | { status: "superseded" }
+  | { status: "aborted"; reason: "cart_write_aborted" }
+  | { status: "timeout"; reason: "cart_write_timeout" }
+  | { status: "failed"; reason: string };
+
+export async function mintShopwareAttributionEnvelope(input: CartAttributeSyncInput): Promise<void> {
+  await requestCommerceAuthorization({ ...input, platform: "shopware" });
+}
+
 async function requestCommerceAuthorization(
   input: CartAttributeSyncInput,
   generation?: number,
@@ -486,6 +783,10 @@ async function requestCommerceAuthorization(
   /** Adoption validated pre-write; the caller applies it only after the cart write is confirmed. */
   offersAdoptionAssignments?: CartAssignment[];
 }> {
+  // Page-inactive assignments remain attribution state. Keep them visible
+  // while reconciling the Worker's cart pin so the same arm does not look
+  // like a new commerce-only assignment that needs adoption.
+  let authorizedAssignments = input.assignments;
   const priceWriteRequiresProof = hasActivePriceAuthorizationPlane(input);
   const offersWriteRequiresProof = hasActiveOffersAuthorizationPlane(input);
   const configuredOffersExperimentIds = offersExperimentIds(input);
@@ -525,7 +826,7 @@ async function requestCommerceAuthorization(
       assignments: input.assignments,
     };
   }
-  const endpoint = input.endpoint.replace(/\/+$/, "").replace(/\/events$/, "");
+  const endpoint = normalizeEndpoint(input.endpoint);
   try {
     const cartToken = await resolveChargeAuthorizationCartToken(input);
     if (
@@ -541,7 +842,7 @@ async function requestCommerceAuthorization(
       };
     }
     const requestedExperimentIds = [...new Set([
-      ...input.assignments.map((assignment) => assignment.experimentId),
+      ...authorizedAssignments.map((assignment) => assignment.experimentId),
       ...(hasActivePriceAuthorizationPlane(input) ? input.priceExperimentIds ?? [] : []),
       ...(hasActiveOffersAuthorizationPlane(input) ? input.offersExperimentIds ?? [] : []),
     ])];
@@ -557,7 +858,15 @@ async function requestCommerceAuthorization(
         user_id: input.visitorId,
         url: input.url,
         environment: input.environment,
-        ...(cartToken ? { cart_token: cartToken } : {}),
+        platform: input.platform,
+        ...(cartToken
+          ? {
+              cart_token: cartToken,
+              // Ask the authenticated Worker to persist its signed decision in
+              // the Function-owned cart plane before the client fallback runs.
+              persist_function_handoff: true,
+            }
+          : {}),
         experiments: requestedExperimentIds,
         exclusion_group_selections: input.exclusionGroupSelections?.map((selection) => ({
           group_id: selection.groupId,
@@ -579,7 +888,13 @@ async function requestCommerceAuthorization(
     const payload = (await response.json()) as {
       assignments?: unknown;
       commerce_authorization?: unknown;
+      handoff_persisted?: boolean;
+      handoff_stale_risk?: boolean;
+      attribution_envelope?: unknown;
     };
+    if (typeof payload.attribution_envelope === "string" && payload.attribution_envelope.length <= 4096) {
+      input.onAttributionEnvelope?.(payload.attribution_envelope);
+    }
     const token =
       typeof payload.commerce_authorization === "string" &&
       payload.commerce_authorization
@@ -602,7 +917,6 @@ async function requestCommerceAuthorization(
         assignments: input.assignments,
       };
     }
-    let authorizedAssignments = input.assignments;
     let requiredAssignments = input.requiredAssignments;
     let resolvedPriceAssignments: ReturnType<
       typeof resolveAuthoritativePriceAssignments
@@ -627,7 +941,7 @@ async function requestCommerceAuthorization(
       if (priceExperimentIds.size > 0) {
         resolvedPriceAssignments = resolveAuthoritativePriceAssignments(
           payload.assignments,
-          input.assignments,
+          authorizedAssignments,
           evaluatedPriceExperimentIds,
         );
         if (!resolvedPriceAssignments) {
@@ -1099,22 +1413,26 @@ function resolveAuthoritativePriceAssignments(
     priceAssignments.map((assignment) => [assignment.experimentId, assignment]),
   );
   const adoptionRequired = localPriceAssignments.some(
-    (assignment) => !authoritativeByExperimentId.has(assignment.experimentId),
+    (assignment) => assignment.pageActive !== false &&
+      !authoritativeByExperimentId.has(assignment.experimentId),
   ) || priceAssignments.some((assignment) => {
     const local = localPriceAssignments.find(
       (candidate) => candidate.experimentId === assignment.experimentId,
     );
     return local?.variationId !== assignment.variationId ||
       local.assignmentEpoch !== assignment.assignmentEpoch ||
-      local.commercePriceOnly !== assignment.commercePriceOnly;
+      (local?.pageActive !== false &&
+        local.commercePriceOnly !== assignment.commercePriceOnly);
   });
   const remainingPriceAssignments = new Map(authoritativeByExperimentId);
   const assignments = localAssignments.map((assignment) => {
     if (!evaluatedPriceExperimentIds.has(assignment.experimentId)) return assignment;
     const authoritative = remainingPriceAssignments.get(assignment.experimentId);
-    if (!authoritative) return null;
+    if (!authoritative) return assignment.pageActive === false ? assignment : null;
     remainingPriceAssignments.delete(assignment.experimentId);
-    return authoritative;
+    return assignment.pageActive === undefined
+      ? authoritative
+      : { ...authoritative, pageActive: assignment.pageActive };
   }).filter((assignment): assignment is CartAssignment => assignment !== null);
   for (const assignment of priceAssignments) {
     if (remainingPriceAssignments.has(assignment.experimentId)) {
@@ -1215,42 +1533,77 @@ export function buildCartAttributeEntries(
   input: CartAttributeSyncInput,
   commerceAuthorization: string | null = null,
 ): CartAttributeEntry[] {
+  // An empty visitor ID marks the identity-free consent-pending stamp. Empty
+  // named keys actively replace identity left by an earlier consented visit.
+  if (input.assignments.length > 0 && !input.visitorId) {
+    return [
+      apexCartAttributeEntry(
+        "apex_assignments",
+        JSON.stringify(input.assignments.map((assignment) => ({
+          e: assignment.experimentId,
+          v: assignment.variationId,
+          ep: assignment.assignmentEpoch,
+        }))),
+      ),
+      apexCartAttributeEntry("apex_assignment_authorization", ""),
+      apexCartAttributeEntry("apex_experiment_id", ""),
+      apexCartAttributeEntry("apex_variation_id", ""),
+      apexCartAttributeEntry("apex_assignment_epoch", ""),
+      apexCartAttributeEntry("apex_visitor_id", ""),
+      apexCartAttributeEntry("apex_session_id", ""),
+    ];
+  }
+  if (input.identityOnly) {
+    return [apexCartAttributeEntry("apex_visitor_id", input.visitorId)];
+  }
   const primaryAssignment = input.assignments[0];
   const entries: CartAttributeEntry[] = [
-    {
-      key: "apex_assignments",
-      value: JSON.stringify(
+    apexCartAttributeEntry(
+      "apex_assignments",
+      JSON.stringify(
         input.assignments.map((assignment) => ({
           e: assignment.experimentId,
           v: assignment.variationId,
           ep: assignment.assignmentEpoch,
         })),
       ),
-    },
-    {
-      key: "apex_assignment_authorization",
-      value: commerceAuthorization ?? "",
-    },
+    ),
+    apexCartAttributeEntry("apex_assignment_authorization", commerceAuthorization ?? ""),
   ];
   if (!primaryAssignment) {
     return [
       ...entries,
-      { key: "apex_experiment_id", value: "" },
-      { key: "apex_variation_id", value: "" },
-      { key: "apex_assignment_epoch", value: "" },
-      { key: "apex_visitor_id", value: input.visitorId },
-      { key: "apex_session_id", value: input.sessionId },
+      apexCartAttributeEntry("apex_experiment_id", ""),
+      apexCartAttributeEntry("apex_variation_id", ""),
+      apexCartAttributeEntry("apex_assignment_epoch", ""),
+      apexCartAttributeEntry("apex_visitor_id", input.visitorId),
+      apexCartAttributeEntry("apex_session_id", input.sessionId),
     ];
   }
   return [
     ...entries,
-    { key: "apex_experiment_id", value: primaryAssignment.experimentId },
-    { key: "apex_variation_id", value: primaryAssignment.variationId },
-    {
-      key: "apex_assignment_epoch",
-      value: String(primaryAssignment.assignmentEpoch ?? ""),
-    },
-    { key: "apex_visitor_id", value: input.visitorId },
-    { key: "apex_session_id", value: input.sessionId },
+    apexCartAttributeEntry("apex_experiment_id", primaryAssignment.experimentId),
+    apexCartAttributeEntry("apex_variation_id", primaryAssignment.variationId),
+    apexCartAttributeEntry(
+      "apex_assignment_epoch",
+      String(primaryAssignment.assignmentEpoch ?? ""),
+    ),
+    apexCartAttributeEntry("apex_visitor_id", input.visitorId),
+    apexCartAttributeEntry("apex_session_id", input.sessionId),
   ];
 }
+
+/** Build a Storefront API cart-metafield mirror of the canonical attribution stamp. */
+export function buildCartMetafieldInputs(
+  input: CartAttributeSyncInput,
+  namespace = "apex",
+): CartMetafieldInput[] {
+  const normalizedNamespace = normalizeCartMetafieldNamespace(namespace);
+  return buildCartAttributeEntries(input)
+    .filter(({ value }) => value !== "")
+    .map(({ key, value }) => ({
+      key: `${normalizedNamespace}.${key}`,
+      type: key === "apex_assignments" ? "json" : "single_line_text_field",
+      value,
+    }));
+}