@drip-apex/sdk 0.1.0

package/src/commerce-gift.ts

@@ -0,0 +1,979 @@
+import { fetchWithoutShopifyCartMutationNotification } from "./shopify-cart-events";
+import {
+  isShopifyStorefront,
+  shopifyCartPath,
+  shopifyRoutesRoot,
+  type CartAssignment,
+} from "./shopify-cart";
+import type { CommerceOffersSettings } from "./types";
+
+const MARKER = "_apex_gwp";
+const DECLINE_PREFIX = "drip_gwp_declined:";
+const INSERTED_PREFIX = "drip_gwp_inserted:";
+
+type CartLine = {
+  key?: unknown;
+  quantity?: unknown;
+  variant_id?: unknown;
+  final_line_price?: unknown;
+  line_price?: unknown;
+  properties?: unknown;
+};
+type ShopifyCart = { token?: unknown; currency?: unknown; items?: unknown };
+
+// Record value when the cart's identity is unknown — matches any cart.
+const ANY_CART = "*";
+
+export type GiftSyncOptions = {
+  /** Per-arm proof from the CURRENT stamped offers plane. Insertion requires
+   * it: config membership alone can cover an assignment whose offers proof
+   * was refused (e.g. shared price+offers experiment with price-only proof),
+   * and the Function would charge that "gift" at full price. */
+  isArmProven?: (assignment: CartAssignment) => boolean;
+  /** A cart mutation invalidates the once-per-page teardown check. */
+  recheckTeardown?: boolean;
+  /** Fail-closed reconciliation after a FAILED stamp sync: privilege-reducing
+   * cleanup only (threshold/currency/orphan removals, quantity normalization)
+   * — never insert, because no fresh proof exists for a new line. */
+  suppressInsertion?: boolean;
+};
+
+let inFlight: Promise<void> | null = null;
+let queuedArgs: {
+  settings: CommerceOffersSettings | undefined;
+  assignments: CartAssignment[];
+  options: GiftSyncOptions | undefined;
+  generation: number;
+} | null = null;
+// In-memory fallback when localStorage is unavailable (strict privacy modes).
+const insertedThisSession = new Map<string, string>();
+const selectedGiftOptions = new Map<string, { gid: string; tierThreshold: string; pending?: boolean }>();
+const dispatchedChoices = new Set<string>();
+// The choice tier currently applicable per experiment — selections bind to
+// THIS tier, not to whichever prompts were dispatched earlier in the session.
+const activeChoiceTier = new Map<string, string>();
+// Bumped whenever new sync arguments are accepted: an in-flight pass built
+// on older arguments must not repopulate tier liveness after the clear.
+let choiceTierGeneration = 0;
+let latestArgs: { settings: CommerceOffersSettings | undefined; assignments: CartAssignment[]; options?: GiftSyncOptions } | null = null;
+
+type GiftTier = { threshold: string; gift_variant_gid: string; gift_choice_variant_gids?: string[] };
+export type PendingGiftChoice = {
+  experimentId: string;
+  threshold: string;
+  options: string[];
+};
+function giftTiers(variant: Record<string, unknown>): GiftTier[] | null {
+  const raw = Array.isArray(variant.tiers) && variant.tiers.length > 0
+    ? variant.tiers
+    : [{ threshold: variant.threshold, gift_variant_gid: variant.gift_variant_gid }];
+  const tiers: GiftTier[] = [];
+  for (const item of raw) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) return null;
+    const tier = item as Record<string, unknown>;
+    if (typeof tier.threshold !== "string" || !/^\d+$/.test(tier.threshold) ||
+      typeof tier.gift_variant_gid !== "string" ||
+      // Malformed fixed-tier GIDs would reach choice dispatch with a null
+      // giftId and abort reconciliation mid-run; money-path config fails
+      // closed at parse time instead.
+      numericVariantId(tier.gift_variant_gid) === null) return null;
+    const choices = tier.gift_choice_variant_gids;
+    if (choices !== undefined && (!Array.isArray(choices) || choices.length < 2 || choices.length > 4 ||
+      !choices.every((gid) => typeof gid === "string" && numericVariantId(gid) !== null))) return null;
+    tiers.push({ threshold: tier.threshold, gift_variant_gid: tier.gift_variant_gid,
+      ...(choices ? { gift_choice_variant_gids: choices as string[] } : {}) });
+  }
+  if (tiers.length < 1 || tiers.length > 3 || tiers.some((tier, index) =>
+    !Number.isSafeInteger(Number(tier.threshold)) ||
+    (index > 0 && Number(tier.threshold) <= Number(tiers[index - 1].threshold)))) return null;
+  return tiers;
+}
+
+function declined(experimentId: string): boolean {
+  try { return sessionStorage.getItem(`${DECLINE_PREFIX}${experimentId}`) === "1"; } catch { return false; }
+}
+
+function recordDecline(experimentId: string): void {
+  try { sessionStorage.setItem(`${DECLINE_PREFIX}${experimentId}`, "1"); } catch { /* best effort */ }
+}
+
+// Insertion state persists in LOCAL storage: the Shopify cart itself is
+// durable across browser sessions, so the record of "Apex added this line"
+// must outlive the session too — otherwise a shopper returning after the
+// offer stopped would keep a no-longer-discounted gift (teardown cleanup
+// could not know to look), and a manual removal in a fresh session would
+// read as "never inserted" and re-add the gift. The record VALUE is the cart
+// token the insertion happened on, so a normal cart transition (checkout
+// emptied the old cart) is not misread as a manual decline on the new one.
+// This is charge-correctness state (experiment id + cart token), like the
+// cart attribute stamp, not analytics. Decline flags stay session-scoped.
+function insertionRecord(experimentId: string): string | null {
+  try {
+    return localStorage.getItem(`${INSERTED_PREFIX}${experimentId}`)
+      ?? insertedThisSession.get(experimentId) ?? null;
+  } catch { return insertedThisSession.get(experimentId) ?? null; }
+}
+
+function recordCart(record: string): string {
+  if (!record.startsWith("{")) return record;
+  try { const parsed = JSON.parse(record) as { cart?: unknown }; return typeof parsed.cart === "string" ? parsed.cart : record; } catch { return record; }
+}
+function recordVariantGid(record: string): string | null {
+  if (!record.startsWith("{")) return null;
+  try {
+    const parsed = JSON.parse(record) as { variantGid?: unknown };
+    return typeof parsed.variantGid === "string" ? parsed.variantGid : null;
+  } catch { return null; }
+}
+function recordTierThreshold(record: string): string | null {
+  if (!record.startsWith("{")) return null;
+  try {
+    const parsed = JSON.parse(record) as { tierThreshold?: unknown };
+    return typeof parsed.tierThreshold === "string" ? parsed.tierThreshold : null;
+  } catch { return null; }
+}
+function insertionMatchesCart(record: string, cartToken: string | null): boolean {
+  const token = recordCart(record);
+  return token === ANY_CART || cartToken == null || token === cartToken;
+}
+
+function recordInserted(experimentId: string, cartToken: string | null, variantGid?: string, tierThreshold?: string): void {
+  const token = cartToken ?? ANY_CART;
+  const value = variantGid || tierThreshold ? JSON.stringify({ cart: token, variantGid, tierThreshold }) : token;
+  insertedThisSession.set(experimentId, value);
+  try { localStorage.setItem(`${INSERTED_PREFIX}${experimentId}`, value); } catch { /* best effort */ }
+  // The durable record landing IS the settle point for a pending selection —
+  // waiting for another reconciliation pass leaves a last-pass add pending
+  // forever and re-opens the cross-tab revert.
+  const selection = selectedGiftOptions.get(experimentId);
+  if (selection?.pending && selection.gid === variantGid) {
+    selectedGiftOptions.set(experimentId, {
+      gid: selection.gid,
+      tierThreshold: selection.tierThreshold,
+    });
+  }
+}
+
+function clearInserted(experimentId: string): void {
+  insertedThisSession.delete(experimentId);
+  try { localStorage.removeItem(`${INSERTED_PREFIX}${experimentId}`); } catch { /* best effort */ }
+}
+
+function clearDispatchedChoices(experimentId: string): void {
+  dispatchedChoices.forEach((key) => {
+    if (key.startsWith(`${experimentId}:`)) dispatchedChoices.delete(key);
+  });
+}
+
+function listInsertionRecords(): string[] {
+  const ids = new Set<string>(insertedThisSession.keys());
+  try {
+    for (let i = 0; i < localStorage.length; i += 1) {
+      const key = localStorage.key(i);
+      if (key?.startsWith(INSERTED_PREFIX)) ids.add(key.slice(INSERTED_PREFIX.length));
+    }
+  } catch { /* fall through */ }
+  return [...ids];
+}
+
+function hasInsertionRecords(): boolean {
+  return listInsertionRecords().length > 0;
+}
+
+// The teardown read (offers plane tombstoned to an empty experiments list)
+// runs once per PAGE LOAD — not per session — so a login/customer-account
+// cart merge that lands a marked line on a later page is still discovered;
+// in-page cart mutations reset the flag via the tombstone observer.
+let teardownChecked = false;
+
+function markTeardownChecked(): void {
+  teardownChecked = true;
+}
+
+function numericVariantId(gid: string): number | null {
+  const match = /^gid:\/\/shopify\/ProductVariant\/(\d+)$/.exec(gid);
+  if (!match) return null;
+  const id = Number(match[1]);
+  return Number.isSafeInteger(id) && id > 0 ? id : null;
+}
+
+function marker(line: CartLine): string | null {
+  if (!line.properties || typeof line.properties !== "object" || Array.isArray(line.properties)) return null;
+  const value = (line.properties as Record<string, unknown>)[MARKER];
+  return typeof value === "string" ? value : null;
+}
+
+function lineVariantId(line: CartLine): string | null {
+  if (typeof line.variant_id === "number" && Number.isSafeInteger(line.variant_id)) return String(line.variant_id);
+  if (typeof line.variant_id === "string" && /^\d+$/.test(line.variant_id)) return line.variant_id;
+  return null;
+}
+
+function lineAmount(line: CartLine): number | null {
+  // The offer Function compares each non-gift line's cost.subtotalAmount —
+  // the PRE-line-discount amount. Ajax `line_price` is that same basis;
+  // `final_line_price` is post-discount and would disagree on discounted
+  // carts, removing a gift the Function still authorizes.
+  const value = line.line_price;
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+
+async function mutate(path: string, body: unknown): Promise<boolean> {
+  // Never throws: a network-level rejection mid-pass must not discard the
+  // pass's accumulated mutation state (earlier successful removals still
+  // warrant the fixpoint retry and the cart-changed signal).
+  try {
+    const response = await fetchWithoutShopifyCartMutationNotification(path, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+/** Returns true when this pass mutated the cart (caller re-runs to a fixpoint). */
+async function run(
+  settings: CommerceOffersSettings | undefined,
+  assignments: CartAssignment[],
+  options: GiftSyncOptions | undefined,
+  generation: number,
+): Promise<boolean> {
+  if (!isShopifyStorefront() || typeof fetch !== "function") return false;
+  let response: Response;
+  try {
+    response = await fetchWithoutShopifyCartMutationNotification(shopifyCartPath(), {
+      method: "GET", headers: { Accept: "application/json" }, cache: "no-store",
+    });
+  } catch { return false; }
+  if (!response.ok) return false;
+  const cart = await response.json() as ShopifyCart;
+  if (!Array.isArray(cart.items) || typeof cart.currency !== "string") return false;
+  let cartMutated = false;
+  const lines = cart.items.filter((item): item is CartLine => !!item && typeof item === "object");
+  const cartToken = typeof cart.token === "string" && cart.token ? cart.token : null;
+  const assigned = new Map(assignments.map((item) => [item.experimentId, item.variationId]));
+  // Charge-only pins authorize the cart stamp for an off-target page but are
+  // deliberately excluded from DOM, persistence, and exposure — inserting a
+  // physical gift for them would give away inventory the shopper was never
+  // shown. They still count as ACTIVE for removal/keep decisions.
+  const chargeOnlyExperimentIds = new Set(
+    assignments.filter((item) => item.commercePriceOnly).map((item) => item.experimentId),
+  );
+  const experiments = settings?.experiments ?? [];
+  // Only experiments covered by the signed offers authorization may INSERT:
+  // without it the Function cannot discount the added line, so the "gift"
+  // would be charged at full price. Removal/maintenance stays unrestricted.
+  const authorizedOfferExperimentIds = new Set(
+    settings?.authorization?.experimentIds ?? [],
+  );
+  const root = shopifyRoutesRoot();
+  const changePath = `${root}cart/change.js`;
+  // Tracks gift variants inserted within THIS run: two parallel GWP tests
+  // configured with the same gift variant must share one line (the Function
+  // consolidates both candidates onto the first matching line), or the
+  // second marked line would be charged at full price.
+  const insertedVariantIdsThisRun = new Set<string>();
+  // Tracks lines removed within THIS run so presence checks against the
+  // immutable snapshot do not see a line that is already gone — otherwise a
+  // still-qualifying experiment sharing the removed gift's variant would
+  // silently skip its own insertion.
+  const removedLineKeys = new Set<string>();
+  const removeLine = async (line: CartLine): Promise<boolean> => {
+    if (typeof line.key !== "string") return false;
+    if (!(await mutate(changePath, { id: line.key, quantity: 0 }))) return false;
+    removedLineKeys.add(line.key);
+    cartMutated = true;
+    return true;
+  };
+  const linePresent = (line: CartLine): boolean =>
+    typeof line.key === "string" ? !removedLineKeys.has(line.key) : true;
+
+  // Orphan cleanup first: a marked line whose experiment left the offers
+  // projection (stopped, archived, kill-switched), whose assignment is gone,
+  // or whose assigned variant no longer describes a GWP offer (relaunched
+  // under a different offer type) will never be authorized by the discount
+  // Function again — the shopper would be charged full price for it. Remove
+  // it before any insertion logic; keep the insertion record when removal
+  // fails so the next sync retries instead of abandoning the line.
+  const activeGiftExperiments = new Set(
+    experiments
+      .filter((experiment) => {
+        const variationId = assigned.get(experiment.experiment_id);
+        const variant = variationId ? experiment.variants[variationId] : undefined;
+        if (!variant || typeof variant !== "object") return false;
+        // With arm proof available, an assignment absent from the CURRENT
+        // stamped offers plane is not active: the Function will not discount
+        // its line, so keeping it would charge the shopper.
+        if (options?.isArmProven) {
+          const assignment = assignments.find(
+            (candidate) => candidate.experimentId === experiment.experiment_id,
+          );
+          if (!assignment || !options.isArmProven(assignment)) return false;
+        }
+        if ("control" in variant && variant.control === true) return true;
+        return "offer_type" in variant && variant.offer_type === "gwp_threshold"
+          && giftTiers(variant as Record<string, unknown>) !== null;
+      })
+      .map((experiment) => experiment.experiment_id),
+  );
+  for (const line of lines) {
+    const mark = marker(line);
+    if (mark == null || activeGiftExperiments.has(mark)) continue;
+    // Seed the durable record BEFORE attempting removal: if the mutation
+    // fails transiently, the record keeps later syncs (and later sessions)
+    // retrying even after this session's tombstone read is throttled.
+    recordInserted(mark, cartToken);
+    if (await removeLine(line)) clearInserted(mark);
+  }
+  // A record whose experiment is inactive AND whose line is already gone
+  // (checkout consumed the cart, or the shopper removed it before teardown)
+  // has nothing left to reconcile — clear it, or it would trigger a cart
+  // read on every later apply and misread a relaunch as a manual decline.
+  for (const experimentId of listInsertionRecords()) {
+    if (activeGiftExperiments.has(experimentId)) continue;
+    if (lines.some((line) => marker(line) === experimentId && linePresent(line))) continue;
+    clearInserted(experimentId);
+  }
+  // Throttle only once the cart has actually been read this session; failed
+  // orphan removals keep their seeded records, which bypass the throttle.
+  if (settings && experiments.length === 0) markTeardownChecked();
+
+  for (const experiment of experiments) {
+    // Not live until this pass proves the choice prompt eligible: every
+    // early exit (unassigned, control, currency mismatch, unproven arm,
+    // suppression, decline) leaves the tier cleared so a delayed
+    // selectGiftOption callback cannot bind to a phantom prompt.
+    activeChoiceTier.delete(experiment.experiment_id);
+    const variationId = assigned.get(experiment.experiment_id);
+    if (!variationId) continue;
+    const variant = experiment.variants[variationId];
+    if (!variant || typeof variant !== "object") continue;
+    // ALL marked lines for this experiment: concurrent tabs during a
+    // relaunch can leave several (e.g. old and new gift variants), and the
+    // Function discounts at most one unit of the current variant.
+    const managedLines = () => lines.filter(
+      (line) => marker(line) === experiment.experiment_id && linePresent(line),
+    );
+    // Removes every managed line; true when none that could be removed
+    // remains (lines without a usable key were never removable and follow
+    // the historical clear-anyway behavior).
+    const removeAllManaged = async (): Promise<boolean> => {
+      let allRemoved = true;
+      for (const line of managedLines()) {
+        if (typeof line.key !== "string") continue;
+        if (!(await removeLine(line))) {
+          allRemoved = false;
+          // A failed REQUIRED removal (below-threshold, control, currency)
+          // is unresolved work: the Function no longer discounts the line,
+          // so force another fixpoint pass to retry within this
+          // reconciliation instead of waiting for an unrelated cart event.
+          cartMutated = true;
+        }
+      }
+      return allRemoved;
+    };
+    if ("control" in variant && variant.control === true) {
+      if (await removeAllManaged()) clearInserted(experiment.experiment_id);
+      continue;
+    }
+    if (!("offer_type" in variant) || variant.offer_type !== "gwp_threshold") continue;
+    const tiers = giftTiers(variant as Record<string, unknown>);
+    if (!tiers) continue;
+    if (cart.currency.toUpperCase() !== experiment.currency.toUpperCase()) {
+      // The Function refuses cross-currency carts, so a market/currency switch
+      // strands an existing managed line at full price — fail closed by
+      // removing it, not just by skipping insertion. Not a decline: the gift
+      // may re-insert if the shopper switches back.
+      if (await removeAllManaged()) clearInserted(experiment.experiment_id);
+      continue;
+    }
+    const allGiftIds = new Set(tiers.flatMap((tier) => tier.gift_choice_variant_gids ?? [tier.gift_variant_gid])
+      .map(numericVariantId).filter((id): id is number => id !== null).map(String));
+    let subtotal = 0;
+    let valid = true;
+    for (const line of lines) {
+      if (!linePresent(line) || allGiftIds.has(lineVariantId(line) ?? "")) continue;
+      const amount = lineAmount(line);
+      if (amount == null || !Number.isSafeInteger(subtotal + amount)) { valid = false; break; }
+      subtotal += amount;
+    }
+    const applicableTier = valid ? tiers.reduce<GiftTier | null>((chosen, tier) => {
+      const threshold = Number(tier.threshold);
+      return Number.isSafeInteger(threshold) && threshold >= 0 && subtotal >= threshold ? tier : chosen;
+    }, null) : null;
+    if (!valid || tiers.some((tier) => !Number.isSafeInteger(Number(tier.threshold)))) {
+      // Fail closed: an unrepresentable threshold means the Function cannot
+      // legitimately discount this gift — an Apex-managed line left from an
+      // earlier (lower) threshold would charge full price. Remove every
+      // managed line for this experiment before skipping it.
+      for (const line of managedLines()) {
+        if (typeof line.key !== "string") continue;
+        await removeLine(line);
+      }
+      continue;
+    }
+    if (!applicableTier) {
+      clearDispatchedChoices(experiment.experiment_id);
+      activeChoiceTier.delete(experiment.experiment_id);
+      if (await removeAllManaged()) clearInserted(experiment.experiment_id);
+      continue;
+    }
+    const choiceGids = applicableTier.gift_choice_variant_gids;
+    // Every applicable-tier transition re-arms the chooser: keys that do not
+    // belong to the CURRENT tier (including all keys while a fixed tier
+    // applies) are stale. Only the current batch may mutate dedup state.
+    if (generation === choiceTierGeneration) {
+      const currentKey = choiceGids
+        ? `${experiment.experiment_id}:${applicableTier.threshold}:${choiceGids.join(",")}`
+        : null;
+      dispatchedChoices.forEach((key) => {
+        if (key.startsWith(`${experiment.experiment_id}:`) && key !== currentKey) {
+          dispatchedChoices.delete(key);
+        }
+      });
+    }
+    const markChoicePromptLive = () => {
+      if (
+        choiceGids &&
+        !options?.suppressInsertion &&
+        authorizedOfferExperimentIds.has(experiment.experiment_id) &&
+        !declined(experiment.experiment_id)
+      ) {
+        const assignment = assignments.find(
+          (candidate) => candidate.experimentId === experiment.experiment_id,
+        );
+        if (
+          (!options?.isArmProven || (assignment && options.isArmProven(assignment))) &&
+          generation === choiceTierGeneration
+        ) {
+          activeChoiceTier.set(experiment.experiment_id, applicableTier.threshold);
+        }
+      }
+    };
+    const extendedRecord = Array.isArray((variant as Record<string, unknown>).tiers);
+    const persistedRecord = insertionRecord(experiment.experiment_id);
+    const persistedGid = persistedRecord && insertionMatchesCart(persistedRecord, cartToken)
+      ? recordVariantGid(persistedRecord)
+      : null;
+    // A recorded tier that DIFFERS from the applicable tier is a stale
+    // lower-tier gift: entering a choice tier must present the choice. An
+    // ABSENT tier (snapshot-seeded cross-device record, legacy plain-token
+    // record) has no provenance: recover it only while the applicable tier
+    // is the LOWEST choice tier containing that gid — once the subtotal has
+    // crossed into a higher choice tier sharing the GID, the new tier's
+    // prompt must not be suppressed by a tierless record.
+    const lowestChoiceTierThresholdFor = (gid: string | null | undefined) =>
+      gid == null
+        ? undefined
+        : tiers.find((tier) => tier.gift_choice_variant_gids?.includes(gid))?.threshold;
+    const persistedTierThreshold =
+      persistedRecord === null ? null : recordTierThreshold(persistedRecord);
+    const tierlessRecoveryAllowed = (gid: string | null | undefined) =>
+      lowestChoiceTierThresholdFor(gid) === applicableTier.threshold;
+    // In-memory selections are tier-bound: a choice made for another tier
+    // (tier crossing, or a selectGiftOption call while a different tier
+    // applied) must not suppress the new tier's choice prompt.
+    const inMemorySelection = selectedGiftOptions.get(experiment.experiment_id);
+    let inMemoryGid = inMemorySelection?.tierThreshold === applicableTier.threshold
+      ? inMemorySelection.gid
+      : undefined;
+    const markedCurrentTierGid = choiceGids?.find((gid) => {
+      const variantId = numericVariantId(gid);
+      return variantId !== null && lines.some((line) =>
+        linePresent(line) && marker(line) === experiment.experiment_id &&
+        lineVariantId(line) === String(variantId));
+    });
+    const persistedChoiceIsCurrentTier = persistedRecord !== null &&
+      (persistedTierThreshold === applicableTier.threshold ||
+        (persistedTierThreshold === null &&
+          tierlessRecoveryAllowed(persistedGid ?? markedCurrentTierGid)));
+    // Cross-tab arbitration: the durable record is the source of truth once
+    // this tab's own selection has been persisted. A PENDING selection (made
+    // here, not yet recorded) still wins — clobbering the user's fresh click
+    // with an older record would be worse. Once our record lands (gids
+    // match), pending clears; a later differing durable record means another
+    // tab chose — drop the stale local selection instead of reverting theirs.
+    if (inMemorySelection && inMemoryGid) {
+      const persistedCurrentTierGid =
+        persistedChoiceIsCurrentTier && choiceGids?.includes(persistedGid ?? "")
+          ? persistedGid
+          : null;
+      if (inMemorySelection.pending && persistedCurrentTierGid === inMemoryGid) {
+        selectedGiftOptions.set(experiment.experiment_id, {
+          gid: inMemorySelection.gid,
+          tierThreshold: inMemorySelection.tierThreshold,
+        });
+      } else if (
+        !inMemorySelection.pending &&
+        persistedCurrentTierGid &&
+        persistedCurrentTierGid !== inMemoryGid
+      ) {
+        selectedGiftOptions.delete(experiment.experiment_id);
+        inMemoryGid = undefined;
+      }
+    }
+    const selectedGid = choiceGids?.includes(inMemoryGid ?? "")
+      ? inMemoryGid
+      : persistedChoiceIsCurrentTier && choiceGids?.includes(persistedGid ?? "") ? persistedGid!
+        : persistedChoiceIsCurrentTier ? markedCurrentTierGid : undefined;
+    if (selectedGid) {
+      const priorPending =
+        selectedGiftOptions.get(experiment.experiment_id)?.gid === selectedGid &&
+        selectedGiftOptions.get(experiment.experiment_id)?.pending === true;
+      selectedGiftOptions.set(experiment.experiment_id, {
+        gid: selectedGid,
+        tierThreshold: applicableTier.threshold,
+        ...(priorPending ? { pending: true } : {}),
+      });
+    }
+    const desiredGid = choiceGids ? selectedGid : applicableTier.gift_variant_gid;
+    const giftId = desiredGid ? numericVariantId(desiredGid) : null;
+    const allowedCurrentIds = new Set((choiceGids ?? [applicableTier.gift_variant_gid])
+      .map(numericVariantId).filter((id): id is number => id !== null).map(String));
+    // Keep at most ONE line carrying the current gift variant; every other
+    // marked line (stale variant after a relaunch, or a concurrent-tab
+    // duplicate) is removed — the Function will not discount it. Removal
+    // failures skip the experiment: falling through could misread the
+    // shopper's cart as a manual decline.
+    let managed: CartLine | undefined;
+    let staleRemovalFailed = false;
+    let removedStaleForExperiment = false;
+    for (const line of managedLines()) {
+      if (!managed && giftId !== null && lineVariantId(line) === String(giftId)) {
+        managed = line;
+        continue;
+      }
+      if (typeof line.key !== "string") continue;
+      if (await removeLine(line)) removedStaleForExperiment = true;
+      else staleRemovalFailed = true;
+    }
+    // Any failed stale removal is unresolved work: force another fixpoint
+    // pass so the retry happens now, not at the next unrelated cart event —
+    // the Function discounts at most the one current-variant unit.
+    if (staleRemovalFailed) cartMutated = true;
+    if (staleRemovalFailed && !managed) continue;
+    if (!managed && removedStaleForExperiment) {
+      // OUR stale-variant removal, not a shopper decline of the new gift:
+      // clear the record so the decline logic below cannot misread it and
+      // the current gift may insert.
+      clearInserted(experiment.experiment_id);
+    }
+    if (managed && lines.some((line) =>
+      line !== managed && linePresent(line) && marker(line) !== experiment.experiment_id &&
+      allowedCurrentIds.has(lineVariantId(line) ?? ""))) {
+      // The Function picks one allowed option by cart-line id, not by Apex's
+      // marker. If a shopper or another experiment added an allowed option,
+      // our marked gift could therefore become a full-price line. Relinquish
+      // Apex's line and let that other option satisfy the tier.
+      if (typeof managed.key === "string" && await removeLine(managed)) {
+        clearInserted(experiment.experiment_id);
+      } else {
+        cartMutated = true;
+      }
+      continue;
+    }
+    if (!desiredGid || giftId === null) {
+      clearInserted(experiment.experiment_id);
+      markChoicePromptLive();
+      if (!options?.suppressInsertion && authorizedOfferExperimentIds.has(experiment.experiment_id) && !declined(experiment.experiment_id)) {
+        const assignment = assignments.find((candidate) => candidate.experimentId === experiment.experiment_id);
+        if (!options?.isArmProven || (assignment && options.isArmProven(assignment))) {
+          const eventKey = `${experiment.experiment_id}:${applicableTier.threshold}:${choiceGids!.join(",")}`;
+          // Only the current batch may dispatch or record dedup state: a
+          // stale batch consuming the key would mute the queued batch's
+          // valid prompt while its own event points at dead liveness.
+          if (generation === choiceTierGeneration) {
+            if (!dispatchedChoices.has(eventKey) && typeof window !== "undefined") {
+              dispatchedChoices.add(eventKey);
+              // Detail carries a COPY: chooser code mutating the array must
+              // not corrupt the server-authored Function configuration that
+              // selectGiftOption validates against.
+              emitChoicePrompt({ experimentId: experiment.experiment_id, threshold: applicableTier.threshold, options: [...choiceGids!] });
+            }
+          }
+        }
+      }
+      continue;
+    }
+    if (managed) {
+      markChoicePromptLive();
+      if (options?.suppressInsertion) {
+        // Fail-closed pass after a failed stamp refresh: keep the line only
+        // when durable evidence ties it to THIS cart — after a cart-identity
+        // change (customer-cart merge) the old proof does not cover the new
+        // cart and the Function will not discount the line.
+        const record = insertionRecord(experiment.experiment_id);
+        if (!record || !insertionMatchesCart(record, cartToken)) {
+          if (await removeAllManaged()) clearInserted(experiment.experiment_id);
+          continue;
+        }
+      } else {
+        // A correctly marked line is always Apex-inserted (shoppers cannot
+        // set our line property), so seed the insertion record when a fresh
+        // session discovers one — a later disappearance must count as a
+        // manual decline.
+        recordInserted(experiment.experiment_id, cartToken, extendedRecord ? desiredGid : undefined, extendedRecord ? applicableTier.threshold : undefined);
+      }
+      // The Function only zeroes a single unit; extra units on the managed
+      // line would be charged, so normalize a shopper/theme increment to one.
+      if (
+        typeof managed.key === "string" &&
+        typeof managed.quantity === "number" &&
+        managed.quantity !== 1
+      ) {
+        // An off-model quantity always warrants another fixpoint pass — even
+        // when this normalize fails, the re-read retries within the run
+        // instead of leaving an extra charged unit until the next mutation.
+        cartMutated = true;
+        await mutate(changePath, { id: managed.key, quantity: 1 });
+      }
+      continue;
+    }
+    // Off-target charge-only pins never insert, and their line's absence on
+    // this page is not decline evidence — the targeted page owns both calls.
+    if (chargeOnlyExperimentIds.has(experiment.experiment_id)) {
+      // But when WE removed this experiment's shared gift line in this run,
+      // clear the co-owner evidence now: removedByUsThisRun does not survive
+      // the pass, and a later targeted page would misread the absent line as
+      // a shopper decline and never reinsert the still-eligible gift.
+      if (
+        insertionRecord(experiment.experiment_id) != null &&
+        lines.some(
+          (line) => !linePresent(line) && allowedCurrentIds.has(lineVariantId(line) ?? ""),
+        )
+      ) {
+        clearInserted(experiment.experiment_id);
+      }
+      continue;
+    }
+    // A shopper-owned copy of the gift satisfies the offer without giving
+    // Apex ownership of it — as does a copy just inserted for a parallel
+    // GWP test with the same gift variant (the Function consolidates both
+    // experiments' candidates onto that one line). This MUST precede the
+    // decline logic: a co-owner's record with the shared line still present
+    // is not a removal.
+    const satisfyingLine = lines.find(
+      (line) => linePresent(line) && allowedCurrentIds.has(lineVariantId(line) ?? ""),
+    );
+    const insertedAllowedId = [...insertedVariantIdsThisRun].find((id) => allowedCurrentIds.has(id));
+    if (satisfyingLine || insertedAllowedId) {
+      markChoicePromptLive();
+      // Sharing an APEX-INSERTED line makes this experiment a co-owner:
+      // record insertion state so the shopper's later removal declines every
+      // experiment the line represents, not just the one in its marker.
+      // Unmarked shopper-owned copies stay unrecorded — removing one's own
+      // purchase is not a gift decline.
+      if (
+        insertedAllowedId ||
+        (satisfyingLine && marker(satisfyingLine) != null)
+      ) {
+        const satisfyingGid = satisfyingLine
+          ? choiceGids?.find((gid) => String(numericVariantId(gid)) === lineVariantId(satisfyingLine))
+          : choiceGids?.find((gid) => String(numericVariantId(gid)) === insertedAllowedId);
+        recordInserted(experiment.experiment_id, cartToken, extendedRecord ? satisfyingGid ?? desiredGid : undefined, extendedRecord ? applicableTier.threshold : undefined);
+      }
+      continue;
+    }
+    const record = insertionRecord(experiment.experiment_id);
+    if (record != null) {
+      clearInserted(experiment.experiment_id);
+      // Only a missing line on the SAME cart the gift was inserted on is a
+      // manual decline. A new cart (checkout consumed the old one) starts
+      // clean, and a shared line WE removed this run (its owner entered
+      // control or lost eligibility) lets a still-qualifying co-owner take
+      // ownership instead of being marked declined.
+      const removedByUsThisRun = lines.some(
+        (line) => !linePresent(line) && lineVariantId(line) === String(giftId),
+      );
+      if (!removedByUsThisRun && insertionMatchesCart(record, cartToken)) {
+        recordDecline(experiment.experiment_id);
+        continue;
+      }
+    }
+    if (declined(experiment.experiment_id)) continue;
+    if (options?.suppressInsertion) continue;
+    if (!authorizedOfferExperimentIds.has(experiment.experiment_id)) continue;
+    if (options?.isArmProven) {
+      const localAssignment = assignments.find(
+        (candidate) => candidate.experimentId === experiment.experiment_id,
+      );
+      if (!localAssignment || !options.isArmProven(localAssignment)) continue;
+    }
+    const addResponse = await fetchWithoutShopifyCartMutationNotification(`${root}cart/add.js`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        items: [{ id: giftId, quantity: 1, properties: { [MARKER]: experiment.experiment_id } }],
+      }),
+    }).catch(() => null);
+    if (!addResponse?.ok) {
+      // A failed add for an explicit CHOICE dead-ends the shopper: the
+      // pending selection would keep retrying the same variant while the
+      // cleared tier liveness rejects any new selectGiftOption call. Drop
+      // the failed selection and re-arm the prompt so another option can
+      // be chosen.
+      const failedSelection = selectedGiftOptions.get(experiment.experiment_id);
+      if (choiceGids && failedSelection?.gid === desiredGid) {
+        selectedGiftOptions.delete(experiment.experiment_id);
+        clearDispatchedChoices(experiment.experiment_id);
+        // Re-arm immediately: the pass-start tier clear plus a failed add
+        // with no cart mutation means no follow-up pass runs, so the chooser
+        // would stay dead (selection ignored, no pending prompts) until an
+        // unrelated reconciliation. Restore tier liveness and re-dispatch so
+        // an alternative option can be chosen right away.
+        markChoicePromptLive();
+        if (generation === choiceTierGeneration && typeof window !== "undefined") {
+          const retryKey = `${experiment.experiment_id}:${applicableTier.threshold}:${choiceGids.join(",")}`;
+          if (!dispatchedChoices.has(retryKey)) {
+            dispatchedChoices.add(retryKey);
+            emitChoicePrompt({ experimentId: experiment.experiment_id, threshold: applicableTier.threshold, options: [...choiceGids] });
+          }
+        }
+      }
+      continue;
+    }
+    if (addResponse?.ok) {
+      cartMutated = true;
+      recordInserted(experiment.experiment_id, cartToken, extendedRecord ? desiredGid : undefined, extendedRecord ? applicableTier.threshold : undefined);
+      insertedVariantIdsThisRun.add(String(giftId));
+      // Concurrent tabs can both add; Shopify consolidates identical
+      // variant+property lines by bumping quantity while the Function only
+      // discounts one unit. Verify from the add response and normalize.
+      try {
+        const body = await addResponse.json() as { items?: unknown };
+        const addedLine = Array.isArray(body.items)
+          ? body.items.find((item): item is CartLine =>
+              !!item && typeof item === "object" &&
+              marker(item as CartLine) === experiment.experiment_id)
+          : undefined;
+        if (
+          addedLine && typeof addedLine.key === "string" &&
+          typeof addedLine.quantity === "number" && addedLine.quantity > 1
+        ) {
+          // Detected consolidation always forces a follow-up fixpoint pass:
+          // even if this normalize fails, the re-read sees quantity > 1 on
+          // the managed line and retries rather than leaving a charged unit.
+          cartMutated = true;
+          await mutate(changePath, { id: addedLine.key, quantity: 1 });
+        }
+      } catch { /* best effort */ }
+    }
+  }
+  return cartMutated;
+}
+
+/**
+ * Seed durable insertion records from any cart snapshot that passes through
+ * the SDK (e.g. the /cart/update.js stamp-write response). Marked lines can
+ * only originate from Apex, so seeing one IS the insertion evidence — this is
+ * how a fresh device or a cleared-storage session over a persistent (or
+ * customer-synced) cart rediscovers gifts it must reconcile or tear down.
+ * Returns true when a marked line was found.
+ */
+export function noteCartSnapshotForGifts(cart: unknown): boolean {
+  const snapshot = cart as { token?: unknown; items?: unknown } | null;
+  if (!Array.isArray(snapshot?.items)) return false;
+  const cartToken = typeof snapshot.token === "string" && snapshot.token ? snapshot.token : null;
+  let found = false;
+  for (const item of snapshot.items) {
+    if (!item || typeof item !== "object") continue;
+    const mark = marker(item as CartLine);
+    if (mark == null) continue;
+    const variantId = lineVariantId(item as CartLine);
+    // A snapshot write must not erase tier ownership an in-flow record
+    // already carries: overwriting a tier-bound choice with a variant-only
+    // record would let a later tier crossing adopt it without re-prompting.
+    const existing = insertionRecord(mark);
+    const existingTier = existing && insertionMatchesCart(existing, cartToken)
+      ? recordTierThreshold(existing)
+      : null;
+    recordInserted(mark, cartToken, variantId
+      ? `gid://shopify/ProductVariant/${variantId}`
+      : undefined, existingTier ?? undefined);
+    found = true;
+  }
+  return found;
+}
+
+export function syncGiftWithPurchase(
+  settings: CommerceOffersSettings | undefined,
+  assignments: CartAssignment[],
+  options?: GiftSyncOptions,
+): Promise<void> {
+  latestArgs = { settings, assignments, options };
+  installChoiceRequestListener();
+  // Liveness derives from the PREVIOUS eligibility state until the async
+  // reconciliation below re-proves it; clear synchronously and advance the
+  // generation so neither a chooser callback nor an in-flight pass built on
+  // the old arguments can resurrect a stale proven tier.
+  choiceTierGeneration += 1;
+  const batchGeneration = choiceTierGeneration;
+  activeChoiceTier.clear();
+  if (options?.recheckTeardown) teardownChecked = false;
+  if (!settings?.experiments.length && !hasInsertionRecords()) {
+    // No offers plane at all: nothing to reconcile (shops that never ran
+    // offers have no tombstone). A present-but-empty plane is the teardown
+    // tombstone — read the cart once per page load (reset on cart mutations)
+    // so an orphaned gift is discovered even when local insertion records
+    // are gone (cleared storage, another device over a customer-synced cart).
+    if (!settings || teardownChecked) return Promise.resolve();
+  }
+  if (inFlight) {
+    // The active run may have read the cart before the mutation that
+    // triggered this call — queue one trailing run (latest args win) instead
+    // of dropping the reconciliation.
+    queuedArgs = { settings, assignments, options, generation: batchGeneration };
+    return inFlight;
+  }
+  // Any pass that mutates the cart re-reads and re-verifies its decisions
+  // (bounded): the cart may have changed between the read and the mutation
+  // (e.g. the subtotal dropped below threshold before the gift add landed),
+  // and shared-line decisions must be order-independent across experiments.
+  const runToFixpoint = async (
+    nextSettings: CommerceOffersSettings | undefined,
+    nextAssignments: CartAssignment[],
+    nextOptions: GiftSyncOptions | undefined,
+    // Fixed per argument batch: a later batch bumps the global counter, and
+    // every remaining pass of THIS batch must keep failing the liveness
+    // check rather than re-reading the now-current generation.
+    generation: number,
+  ) => {
+    let anyMutated = false;
+    for (let pass = 0; pass < 3; pass += 1) {
+      const mutated = await run(nextSettings, nextAssignments, nextOptions, generation).catch(() => false);
+      if (mutated) anyMutated = true;
+      if (!mutated) break;
+    }
+    if (anyMutated && typeof window !== "undefined") {
+      // Our mutations suppress the SDK's own cart observer, so themes whose
+      // drawers render from their original add/change responses would show a
+      // stale cart. Publish a documented signal for themes/integrators to
+      // re-render from /cart.js (checkout charges are correct regardless —
+      // the backend cart is authoritative; this is display freshness).
+      try {
+        window.dispatchEvent(
+          new CustomEvent("apex:cart:changed", { detail: { source: "gwp_gift" } }),
+        );
+      } catch { /* best effort */ }
+    }
+  };
+  const pending = (async () => {
+    await runToFixpoint(settings, assignments, options, batchGeneration);
+    while (queuedArgs) {
+      const next = queuedArgs;
+      queuedArgs = null;
+      await runToFixpoint(next.settings, next.assignments, next.options, next.generation);
+    }
+    if (choiceReplayRequested) getPendingGiftChoices().forEach(emitChoicePrompt);
+    choiceReplayRequested = false;
+  })().finally(() => {
+    if (inFlight === pending) inFlight = null;
+    if (!inFlight && queuedArgs) {
+      const next = queuedArgs;
+      queuedArgs = null;
+      void syncGiftWithPurchase(next.settings, next.assignments, next.options);
+    }
+  });
+  inFlight = pending;
+  return pending;
+}
+
+/** Selects an option previously offered by `apex:gwp:choice`. The next
+ * reconciliation validates the current signed arm/tier before mutating. */
+export function selectGiftOption(experimentId: string, variantGid: string): Promise<void> {
+  if (!latestArgs || numericVariantId(variantGid) === null) return Promise.resolve();
+  const experiment = latestArgs.settings?.experiments.find((item) => item.experiment_id === experimentId);
+  const variationId = latestArgs.assignments.find((item) => item.experimentId === experimentId)?.variationId;
+  const variant = variationId ? experiment?.variants[variationId] : undefined;
+  if (!variant || typeof variant !== "object") return Promise.resolve();
+  const tiers = giftTiers(variant as Record<string, unknown>);
+  const containingTiers = tiers?.filter((tier) =>
+    tier.gift_choice_variant_gids?.includes(variantGid)) ?? [];
+  // The same GID can be a valid choice in several tiers: bind the selection
+  // to the tier that is applicable right now (tracked each reconciliation
+  // pass), so answering the live prompt records the live tier — dispatched
+  // keys from earlier tier crossings must not decide this.
+  const applicableThreshold = activeChoiceTier.get(experimentId);
+  // No live choice tier (shopper dropped below threshold, or moved to a
+  // fixed tier) → a delayed chooser callback must be ignored, not recorded
+  // against a tier that is no longer prompting.
+  const owningTier = containingTiers.find(
+    (tier) => tier.threshold === applicableThreshold,
+  );
+  if (!owningTier) return Promise.resolve();
+  selectedGiftOptions.set(experimentId, {
+    gid: variantGid,
+    tierThreshold: owningTier.threshold,
+    pending: true,
+  });
+  clearDispatchedChoices(experimentId);
+  return syncGiftWithPurchase(latestArgs.settings, latestArgs.assignments, latestArgs.options);
+}
+
+function emitChoicePrompt(detail: PendingGiftChoice): void {
+  dispatchEvent(new CustomEvent("apex:gwp:choice", { detail }));
+}
+
+// Documented replay contract: dispatching apex:gwp:choice:request makes the
+// SDK re-emit apex:gwp:choice for every live, unanswered prompt, so choosers
+// mounted after the initial dispatch can recover it. Registered lazily from
+// the sync path so importing this module (e.g. via the @drip-apex/sdk/chooser
+// entry) stays free of runtime side effects.
+let choiceRequestListenerInstalled = false;
+let choiceReplayRequested = false;
+function installChoiceRequestListener(): void {
+  if (choiceRequestListenerInstalled || typeof window === "undefined") return;
+  choiceRequestListenerInstalled = true;
+  window.addEventListener("apex:gwp:choice:request", () => {
+    if (inFlight) choiceReplayRequested = true;
+    getPendingGiftChoices().forEach(emitChoicePrompt);
+  });
+}
+
+/** Returns live, unanswered gift-choice prompts. This replayable query lets a
+ * chooser mounted after `apex:gwp:choice` was dispatched discover the same
+ * prompt; pass an experiment id to restrict the result. Returned option
+ * arrays are copies and may be safely modified by caller code. */
+export function getPendingGiftChoices(experimentId?: string): PendingGiftChoice[] {
+  if (!latestArgs) return [];
+  const prompts: PendingGiftChoice[] = [];
+  for (const [activeExperimentId, threshold] of activeChoiceTier) {
+    if (experimentId !== undefined && activeExperimentId !== experimentId) continue;
+    const selected = selectedGiftOptions.get(activeExperimentId);
+    if (selected?.tierThreshold === threshold) continue;
+    const experiment = latestArgs.settings?.experiments.find(
+      (item) => item.experiment_id === activeExperimentId,
+    );
+    const variationId = latestArgs.assignments.find(
+      (item) => item.experimentId === activeExperimentId,
+    )?.variationId;
+    const variant = variationId ? experiment?.variants[variationId] : undefined;
+    if (!variant || typeof variant !== "object") continue;
+    const tier = giftTiers(variant as Record<string, unknown>)?.find(
+      (candidate) => candidate.threshold === threshold,
+    );
+    if (!tier?.gift_choice_variant_gids) continue;
+    prompts.push({
+      experimentId: activeExperimentId,
+      threshold,
+      options: [...tier.gift_choice_variant_gids],
+    });
+  }
+  return prompts;
+}
+
+export const __giftManagerInternals = {
+  reset() {
+    inFlight = null;
+    queuedArgs = null;
+    insertedThisSession.clear();
+    selectedGiftOptions.clear();
+    activeChoiceTier.clear();
+    dispatchedChoices.clear();
+    latestArgs = null;
+    teardownChecked = false;
+  },
+};