@nextcommerce/campaigns-os 1.41.2 → 1.43.2

package/src/qa-browser.mjs

@@ -55,6 +55,7 @@ import {
   placeholderTextResidueMatches,
   referencedDemoAssetBasenames,
   summarizePlaceholderTerms,
+  withoutHiddenPaymentLogos,
 } from "./template-brand-contract.mjs";
 
 const DEFAULT_BROWSER_TIMEOUT_MS = 30000;
@@ -256,6 +257,11 @@ async function dispatchTestOrderPlans({ context, plans, checkoutPage, args = {},
         // reader could be surprised by. Over-charging costs at worst one unspent
         // planned path; under-charging costs a real order nobody budgeted for.
         creationBudget.consume({ plan_id: identifier, kind: "hosted_checkout_redirect" });
+      } else if (firstAttempt.upsell_unverified) {
+        // Created, and every check passed except an accepted upsell nothing
+        // could prove or disprove. A re-run would buy a second order to ask
+        // again, and recovery cannot re-check an upsell read-only, so the
+        // attempt stands and goes to manual review.
       } else if (!firstAttempt.ok) {
         const classification = classifyTestOrderCreation(firstAttempt);
         if (classification.creation === "not_created") {
@@ -401,7 +407,7 @@ async function dispatchTestOrderPlans({ context, plans, checkoutPage, args = {},
 // with --analytics-baseline's legacy receipt, and identity resolution cannot
 // derive a receipt page yet (receipt-aware capture is out of packet 01's
 // scope). Absent that override, the candidate IS the resolved target.
-function analyticsParityCaptureAssertions({ baseline, candidate, baselineUrl, candidateUrl }) {
+function analyticsParityCaptureAssertions({ baseline, candidate, baselineUrl, candidateUrl, capturePage = null, rootFallback = null }) {
   const baselinePublicUrl = redactUrlQuery(baselineUrl);
   const candidatePublicUrl = redactUrlQuery(candidateUrl);
   const analyticsPage = { page_id: "analytics", url: candidatePublicUrl || baselinePublicUrl || undefined };
@@ -421,6 +427,8 @@ function analyticsParityCaptureAssertions({ baseline, candidate, baselineUrl, ca
       candidate_event_count: candidate.eventNames.length,
       baseline_inventory: Object.fromEntries(Object.entries(baseline.inventory).map(([k, v]) => [k, v.length])),
       candidate_inventory: Object.fromEntries(Object.entries(candidate.inventory).map(([k, v]) => [k, v.length])),
+      ...(capturePage ? { capture_page: capturePage } : {}),
+      ...(rootFallback ? { root_fallback: rootFallback } : {}),
     },
   }));
   return assertions;
@@ -474,9 +482,14 @@ export async function runAnalyticsParityChecks(args = {}, options = {}) {
     extraHTTPHeaders: args["auth-cookie"] ? { Cookie: String(args["auth-cookie"]) } : undefined,
   });
   try {
-    const baseline = await captureAnalyticsForUrl(context, baselineUrl, args, extraHosts);
-    const candidate = await captureAnalyticsForUrl(context, candidateUrl, args, extraHosts);
-    return analyticsParityCaptureAssertions({ baseline, candidate, baselineUrl, candidateUrl });
+    // An explicit --analytics-candidate (the receipt pairing above) is the
+    // page the operator named, so it is captured as given.
+    if (trim(args["analytics-candidate"])) {
+      const baseline = await captureAnalyticsForUrl(context, baselineUrl, args, extraHosts);
+      const candidate = await captureAnalyticsForUrl(context, candidateUrl, args, extraHosts);
+      return analyticsParityCaptureAssertions({ baseline, candidate, baselineUrl, candidateUrl });
+    }
+    return await captureAnalyticsParityInContext(context, baselineUrl, candidateUrl, args, extraHosts, options);
   } catch (error) {
     return [analyticsParityRunnerFailureAssertion({ baselineUrl, candidateUrl, error })];
   } finally {
@@ -485,16 +498,57 @@ export async function runAnalyticsParityChecks(args = {}, options = {}) {
   }
 }
 
-// Analytics CORRECTNESS inventory leg: capture ONE campaign-root page and
-// assess only declared tags/pixels. Purchase is finalized later from the
-// canonical typed-card order's recognized receipt; this root visit is never
-// treated as Purchase authority.
+// #503: the resolved-target candidate gets the same partial-scope fallback as
+// the correctness inventory (#493). A partial build has no page at the
+// identity root, so the candidate is the first built in-scope entry, and a
+// root that answers non-2xx falls back the same way. The candidate is picked
+// first: when nothing in scope answers, the leg reports
+// no_in_scope_page_captured (skipped) or no_capture_page_answered (blocker)
+// without loading the baseline, instead of diffing the baseline against an
+// empty or generic page.
+async function captureAnalyticsParityInContext(context, baselineUrl, targetUrl, args, extraHosts, options = {}) {
+  const selected = await captureFirstAnsweringAnalyticsPage(context, targetUrl, args, extraHosts, options);
+  if (!selected.capture) {
+    return [analyticsCorrectnessNoCapturePageAssertion({ rootUrl: targetUrl, attempts: selected.attempts, family: "analytics-parity" })];
+  }
+  const baseline = await captureAnalyticsForUrl(context, baselineUrl, args, extraHosts);
+  return analyticsParityCaptureAssertions({
+    baseline,
+    candidate: selected.capture,
+    baselineUrl,
+    candidateUrl: selected.url,
+    capturePage: selected.capturePage,
+    rootFallback: selected.rootFallback,
+  });
+}
+
+// Analytics CORRECTNESS inventory leg: capture ONE page and assess only
+// declared tags/pixels. Purchase is finalized later from the canonical
+// typed-card order's recognized receipt; this inventory visit is never treated
+// as Purchase authority.
 // `options.target` is the capture target resolved from the campaign's
 // identity (public_route_slug + route_root) in qa-node — packet 01 / INV-2:
 // this leg no longer reads --analytics-candidate or --base-url; the URL it
 // visits is a function of resolved identity, recorded on every assertion.
-function analyticsCorrectnessCaptureAssertions({ capture, contract, url }) {
+//
+// #493: a partial build can have no page at that campaign root (the built
+// entry is deeper, e.g. checkout/). When qa-node reports the root out of the
+// built scope (`options.rootInScope === false`), or the root answers non-2xx,
+// the leg captures the first built in-scope entry instead
+// (`options.fallbackTargets`, the same entry the partial-scope planner
+// selects) and records which page it used. When nothing in scope can be
+// captured, the leg is skipped when the build has no capturable page, and
+// fails as a blocker when candidates existed but none answered 2xx; neither
+// case fails every declared vendor against an empty page.
+// #500: the URL the capture page actually settled on, after redirects, keyed by
+// the capture object so the parity capture shape stays unchanged. Local-serve
+// review (qa-node) downgrades a silent pixel only when this is loopback: a
+// localhost root that redirects to a production host measured production.
+const ANALYTICS_CAPTURE_DOCUMENT_URL = new WeakMap();
+
+function analyticsCorrectnessCaptureAssertions({ capture, contract, url, capturePage = null, rootFallback = null, finalUrl = ANALYTICS_CAPTURE_DOCUMENT_URL.get(capture) ?? null }) {
   const publicUrl = redactUrlQuery(url);
+  const publicFinalUrl = redactUrlQuery(finalUrl) || null;
   const analyticsPage = { page_id: "analytics", url: publicUrl || undefined };
   const assertions = assessAnalyticsInventory(capture, contract || {}, { url: publicUrl });
   assertions.unshift(assertion({
@@ -503,18 +557,63 @@ function analyticsCorrectnessCaptureAssertions({ capture, contract, url }) {
     page: analyticsPage,
     status: STATUS.PASS,
     expected: "live dataLayer + tag-fire capture on the candidate page",
-    actual: `events=${capture.eventNames.length}, tags=${Object.values(capture.inventory).flat().length}`,
+    actual: `events=${capture.eventNames.length}, tags=${Object.values(capture.inventory).flat().length}`
+      + (rootFallback ? ` (captured built entry ${publicUrl}; campaign root ${rootFallback.reason === "non_2xx" ? `answered HTTP ${rootFallback.http_status}` : "is out of the built scope"})` : ""),
     // Counts only. Root capture is provider/tag inventory, never Purchase
     // authority, even if a stray Purchase happens to appear there.
     evidence: {
       url: publicUrl,
       event_count: capture.eventNames.length,
       inventory: Object.fromEntries(Object.entries(capture.inventory).map(([k, v]) => [k, v.length])),
+      // The page URL after redirects and settling; `capture_page.url` and
+      // `url` are the URL requested.
+      final_url: publicFinalUrl,
+      ...(capturePage ? { capture_page: capturePage } : {}),
+      ...(rootFallback ? { root_fallback: rootFallback } : {}),
     },
   }));
   return assertions;
 }
 
+// No page was captured. Two cases, kept apart so a failed capture never
+// silently removes analytics gating:
+// - nothing built was capturable (the root is out of the built scope and no
+//   built entry exists): SKIPPED, disposition-neutral, since there is no page
+//   whose tags could be measured;
+// - candidates existed but none answered 2xx (e.g. transient 503s): the
+//   declared vendors went unmeasured, which is a blocker naming each attempt,
+//   so a later successful order cannot report the run ready.
+// The parity leg (#503) reports the same two outcomes under its own family.
+function analyticsCorrectnessNoCapturePageAssertion({ rootUrl, attempts, family = "analytics-correctness" }) {
+  const publicUrl = redactUrlQuery(rootUrl);
+  const page = { page_id: "analytics", url: publicUrl || undefined };
+  const expected = "live dataLayer + tag-fire capture on the campaign root or the first built in-scope page";
+  const loaded = attempts.filter((attempt) => attempt.outcome === "non_2xx" || attempt.outcome === "navigation_error");
+  if (!loaded.length) {
+    return assertion({
+      id: `${family}:capture`,
+      family,
+      page,
+      status: STATUS.SKIPPED,
+      expected,
+      actual: "no_in_scope_page_captured: the campaign root is out of the built scope and the build has no in-scope entry page to capture",
+      evidence: { url: publicUrl, reason: "no_in_scope_page_captured", attempts },
+    });
+  }
+  return assertion({
+    id: `${family}:capture`,
+    family,
+    page,
+    status: STATUS.FAIL,
+    severity: SEVERITY.BLOCKER,
+    expected,
+    actual: `no_capture_page_answered: declared analytics went unmeasured; ${loaded.map((attempt) => (attempt.outcome === "navigation_error"
+      ? `${attempt.url} failed to load (${attempt.error_code})`
+      : `${attempt.url} answered HTTP ${attempt.http_status}`)).join(", ")}`,
+    evidence: { url: publicUrl, reason: "no_capture_page_answered", attempts },
+  });
+}
+
 function analyticsCorrectnessRunnerFailureAssertion({ url, error }) {
   const publicUrl = redactUrlQuery(url);
   const captureError = projectAnalyticsCaptureError(error, { fallbackKind: "unreadable" });
@@ -530,6 +629,147 @@ function analyticsCorrectnessRunnerFailureAssertion({ url, error }) {
   });
 }
 
+function isHttpOk(status) {
+  // A null status (same-document or non-HTTP navigation) is not evidence of
+  // a missing page, so it keeps the capture.
+  return status == null || (status >= 200 && status < 300);
+}
+
+// One capture per page: `/campaign`, `/campaign/` and `/campaign/index.html`
+// are the same page, so a topology URL written differently from the root is
+// not loaded twice.
+// #503: step routing is path-based in every certified family (page-kit builds
+// each page to its own `<route>/index.html`; a spec route has its query
+// stripped), so a query string does not normally name a different page. A
+// URL that declares its own query (`/campaign/?step=checkout`) is still kept
+// apart from a page without that query: merging it into the root on path alone
+// measured the root's generic answer instead of that entry. A URL without a
+// query of its own names the page on any query (an operator's `?preview=` on
+// the root does not split it from the built page at that path).
+function analyticsCapturePageKey(value) {
+  try {
+    const parsed = new URL(value);
+    const path = parsed.pathname.replace(/(?:^|\/)index\.html$/, "/").replace(/\/+$/, "");
+    parsed.searchParams.sort();
+    return { path: `${parsed.origin}${path}/`, query: parsed.searchParams.toString() };
+  } catch {
+    return typeof value === "string" && value.trim() ? { path: redactUrlQuery(value), query: "" } : null;
+  }
+}
+
+// True when `candidate` is the page `known` already names (see
+// analyticsCapturePageKey). Shared with qa-node's root-in-scope judgment so
+// scope and deduplication cannot disagree about which page is the root.
+export function isSameAnalyticsCapturePage(candidate, known) {
+  const a = analyticsCapturePageKey(candidate);
+  const b = analyticsCapturePageKey(known);
+  if (!a || !b || a.path !== b.path) return false;
+  return !a.query || a.query === b.query;
+}
+
+// A URL on `root`'s path told apart from it by a query of its own: the entry
+// `isSameAnalyticsCapturePage` keeps separate from the root although its
+// redacted URL reads as the root.
+function isQueryRoutedFrom(value, root) {
+  const a = analyticsCapturePageKey(value);
+  const b = analyticsCapturePageKey(root);
+  return !!a && !!b && a.path === b.path && !!a.query && a.query !== b.query;
+}
+
+function analyticsCaptureCandidates(url, options = {}) {
+  const candidates = [];
+  const seen = [];
+  const add = (candidate) => {
+    if (!candidate.url || seen.some((known) => isSameAnalyticsCapturePage(candidate.url, known))) return;
+    seen.push(candidate.url);
+    candidates.push(candidate);
+  };
+  const rootInScope = options.rootInScope !== false;
+  if (rootInScope) add({ url, source: "campaign_root" });
+  // An out-of-scope root stays unvisited even if a fallback names it.
+  else if (url) seen.push(url);
+  for (const entry of Array.isArray(options.fallbackTargets) ? options.fallbackTargets : []) {
+    if (!entry || !trim(entry.url)) continue;
+    add({
+      url: trim(entry.url),
+      source: "built_entry",
+      page_id: entry.page_id || null,
+      funnel_id: entry.funnel_id || null,
+      // The query value is redacted from every record; this says the entry
+      // was told apart from the root by its query alone.
+      ...(url && isQueryRoutedFrom(trim(entry.url), url) ? { query_routed: true } : {}),
+    });
+  }
+  return { candidates, rootInScope, rootKey: redactUrlQuery(url) };
+}
+
+// Walks the capture candidates (the campaign root when in scope, then the
+// built entries) and captures the first page that answers 2xx. Shared by the
+// correctness inventory (#493) and the opt-in parity candidate (#503) so both
+// legs pick the same page. Returns `{ capture, url, capturePage, rootFallback }`
+// for the page it used, or `{ capture: null, attempts }` when none answered.
+async function captureFirstAnsweringAnalyticsPage(context, url, args, extraHosts, options = {}, { strictCollect = false } = {}) {
+  const { candidates, rootInScope, rootKey } = analyticsCaptureCandidates(url, options);
+  const attempts = [];
+  if (!rootInScope) attempts.push({ url: rootKey, source: "campaign_root", outcome: "out_of_built_scope", http_status: null });
+  let rootFallback = rootInScope ? null : { url: rootKey, reason: "out_of_built_scope", http_status: null };
+  const queryRouted = (candidate) => (candidate.query_routed ? { query_routed: true } : {});
+  for (const candidate of candidates) {
+    const { capture, httpStatus, navigationError } = await captureAnalyticsPage(
+      context, candidate.url, args, extraHosts, { perPageNavigationErrors: true, strictCollect },
+    );
+    if (navigationError) {
+      // One page failing to load (a timeout, a refused connection) moves on to
+      // the next candidate; the blocker lists it if none answers.
+      attempts.push({ url: redactUrlQuery(candidate.url), source: candidate.source, ...queryRouted(candidate), outcome: "navigation_error", http_status: null, error_code: navigationError });
+      if (candidate.source === "campaign_root") {
+        rootFallback = { url: rootKey, reason: "navigation_error", http_status: null, error_code: navigationError };
+      }
+      continue;
+    }
+    if (isHttpOk(httpStatus)) {
+      const usedFallback = candidate.source !== "campaign_root";
+      return {
+        capture,
+        url: candidate.url,
+        capturePage: {
+          url: redactUrlQuery(candidate.url),
+          source: candidate.source,
+          ...(candidate.page_id ? { page_id: candidate.page_id } : {}),
+          ...(candidate.funnel_id ? { funnel_id: candidate.funnel_id } : {}),
+          ...queryRouted(candidate),
+          http_status: httpStatus ?? null,
+        },
+        rootFallback: usedFallback ? rootFallback : null,
+      };
+    }
+    attempts.push({ url: redactUrlQuery(candidate.url), source: candidate.source, ...queryRouted(candidate), outcome: "non_2xx", http_status: httpStatus });
+    if (candidate.source === "campaign_root") {
+      rootFallback = { url: rootKey, reason: "non_2xx", http_status: httpStatus };
+    }
+  }
+  return { capture: null, attempts };
+}
+
+// Browser-owning half split out so a real-browser test can drive the fallback
+// against a route-fulfilled context without a second Chromium launch policy.
+async function captureAnalyticsCorrectnessInContext(context, url, contract, args, extraHosts, options = {}) {
+  // strictCollect: a page.evaluate() that fails during collection (the
+  // execution context destroyed by a reload, a crashed page) must not read
+  // as a clean empty capture. It propagates and becomes the
+  // analytics-correctness:runner blocker, so no tag check is emitted from an
+  // unmeasured page and local-serve review has nothing to downgrade (#500).
+  const selected = await captureFirstAnsweringAnalyticsPage(context, url, args, extraHosts, options, { strictCollect: true });
+  if (!selected.capture) return [analyticsCorrectnessNoCapturePageAssertion({ rootUrl: url, attempts: selected.attempts })];
+  return analyticsCorrectnessCaptureAssertions({
+    capture: selected.capture,
+    contract,
+    url: selected.url,
+    capturePage: selected.capturePage,
+    rootFallback: selected.rootFallback,
+  });
+}
+
 export async function runAnalyticsCorrectnessChecks(args = {}, contract = {}, options = {}) {
   const url = trim(options.target?.url) || null;
   const correctnessPage = { page_id: "analytics", url: redactUrlQuery(url) || undefined };
@@ -545,12 +785,7 @@ export async function runAnalyticsCorrectnessChecks(args = {}, contract = {}, op
     })];
   }
 
-  // Seed the host filter with declared out-of-band vendor names so vendors whose
-  // host contains their name (everflow, northbeam, …) get captured.
-  const vendorHosts = ((contract && contract.out_of_band_pixels) || [])
-    .map((p) => (p && p.vendor ? String(p.vendor) : null))
-    .filter(Boolean);
-  const extraHosts = [...analyticsExtraHosts(args), ...vendorHosts];
+  const extraHosts = analyticsCorrectnessExtraHosts(args, contract);
 
   const browser = await launchChromium(args);
   const context = await browser.newContext({
@@ -558,8 +793,7 @@ export async function runAnalyticsCorrectnessChecks(args = {}, contract = {}, op
     extraHTTPHeaders: args["auth-cookie"] ? { Cookie: String(args["auth-cookie"]) } : undefined,
   });
   try {
-    const capture = await captureAnalyticsForUrl(context, url, args, extraHosts);
-    return analyticsCorrectnessCaptureAssertions({ capture, contract, url });
+    return await captureAnalyticsCorrectnessInContext(context, url, contract, args, extraHosts, options);
   } catch (error) {
     return [analyticsCorrectnessRunnerFailureAssertion({ url, error })];
   } finally {
@@ -568,6 +802,15 @@ export async function runAnalyticsCorrectnessChecks(args = {}, contract = {}, op
   }
 }
 
+// Seed the host filter with declared out-of-band vendor names so vendors whose
+// host contains their name (everflow, northbeam, …) get captured.
+function analyticsCorrectnessExtraHosts(args, contract) {
+  const vendorHosts = ((contract && contract.out_of_band_pixels) || [])
+    .map((p) => (p && p.vendor ? String(p.vendor) : null))
+    .filter(Boolean);
+  return [...analyticsExtraHosts(args), ...vendorHosts];
+}
+
 function analyticsExtraHosts(args) {
   const raw = args["analytics-hosts"];
   if (!raw) return [];
@@ -575,6 +818,22 @@ function analyticsExtraHosts(args) {
 }
 
 export async function captureAnalyticsForUrl(context, url, args, extraHosts = []) {
+  return (await captureAnalyticsPage(context, url, args, extraHosts)).capture;
+}
+
+// Same capture, plus the main-document HTTP status, which the correctness leg
+// uses to tell an empty page from a missing one (#493). Kept off the capture
+// object so parity comparisons never see it.
+// A stable code for a failed navigation: Playwright's TimeoutError, or the
+// net::ERR_* token Chromium reports. The raw message is dropped because it
+// echoes the URL (query included) and a call log.
+function analyticsNavigationErrorCode(error) {
+  if (error?.name === "TimeoutError") return "navigation_timeout";
+  const netError = String(error?.message || "").match(/net::ERR_[A-Z0-9_]+/);
+  return netError ? netError[0] : "navigation_failed";
+}
+
+async function captureAnalyticsPage(context, url, args, extraHosts = [], options = {}) {
   const page = await context.newPage();
   const capture = await attachAnalyticsCapture(page, { extraHosts });
   const timeoutMs = numberArg(args["browser-timeout"], DEFAULT_BROWSER_TIMEOUT_MS);
@@ -583,11 +842,27 @@ export async function captureAnalyticsForUrl(context, url, args, extraHosts = []
     // domcontentloaded (not "load") so a single stuck analytics beacon — exactly
     // the kind of subresource we're capturing — can't starve the goto timeout.
     // Mirrors runPageBrowserChecks; the settle wait below lets async tags fire.
-    await page.goto(url, { waitUntil: "domcontentloaded", timeout: timeoutMs });
+    let response;
+    try {
+      response = await page.goto(url, { waitUntil: "domcontentloaded", timeout: timeoutMs });
+    } catch (error) {
+      // Only the navigation is per-page. A closed page or a disconnected
+      // browser is the runner failing, not this URL, so it stays an error.
+      if (!options.perPageNavigationErrors || page.isClosed() || context.browser()?.isConnected() === false) throw error;
+      return { capture: null, httpStatus: null, navigationError: analyticsNavigationErrorCode(error) };
+    }
+    let httpStatus = null;
+    try { httpStatus = typeof response?.status === "function" ? response.status() : null; } catch { httpStatus = null; }
     await page.waitForLoadState("networkidle", { timeout: settleMs }).catch(() => {});
     // Let async GTM/pixel tags and deferred dataLayer pushes fire before reading.
     await page.waitForTimeout(settleMs);
-    return await capture.collect();
+    // Parity keeps the historical best-effort read; the correctness leg
+    // collects strictly (see captureAnalyticsCorrectnessInContext).
+    const collected = await capture.collect({ strict: options.strictCollect === true });
+    let finalUrl = null;
+    try { finalUrl = page.url() || null; } catch { finalUrl = null; }
+    if (collected && typeof collected === "object" && finalUrl) ANALYTICS_CAPTURE_DOCUMENT_URL.set(collected, finalUrl);
+    return { capture: collected, httpStatus };
   } finally {
     capture.detach();
     await page.close().catch(() => {});
@@ -1732,7 +2007,9 @@ async function templateResidueAssertions(browserPage, page, options = {}) {
   if (chrome && Array.isArray(supported) && supported.length) {
     const unsupported = (chrome.methods || []).filter((method) => !supported.includes(method));
     if (unsupported.length) {
-      const html = await browserPage.content().catch(() => "");
+      // Logos the template still keeps hidden (payment-logos.html) are gated,
+      // not residue; a revealed one stays in the HTML and is judged below.
+      const html = withoutHiddenPaymentLogos(await browserPage.content().catch(() => ""));
       // One evaluate for ALL unsupported methods' selectors; partition the
       // visibility results per method in JS to keep browser round-trips flat.
       const artifactsByMethod = new Map(unsupported.map((method) => [method, methodPaymentArtifacts(chrome, method)]));
@@ -2776,6 +3053,11 @@ async function collectOrderAnalytics({
   deadline,
   now = () => Date.now(),
   wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  // The page's document location, read right after the settled collection
+  // (#500). The order's final_url is recorded before this settle window, so a
+  // receipt that redirects while analytics settle would otherwise be judged
+  // by where it started, not where Purchase was measured.
+  readDocumentUrl = null,
 }) {
   const result = {};
   if (!captureHandle) return result;
@@ -2806,14 +3088,17 @@ async function collectOrderAnalytics({
 
   const collection = deadlineConsumed
     ? { timedOut: true }
-    : await runWithinAnalyticsDeadline(async () => (
-      typeof captureHandle.collectScopes === "function"
-        ? captureHandle.collectScopes({ strict: true })
+    : await runWithinAnalyticsDeadline(async () => {
+      const scopes = typeof captureHandle.collectScopes === "function"
+        ? await captureHandle.collectScopes({ strict: true })
         : {
             journey: await captureHandle.collect({ strict: true }),
             currentDocument: await captureHandle.collect({ strict: true, scope: "current-document" }),
-          }
-    ), { deadline, now });
+          };
+      let documentUrl = null;
+      try { documentUrl = typeof readDocumentUrl === "function" ? (readDocumentUrl() || null) : null; } catch { documentUrl = null; }
+      return { ...scopes, documentUrl };
+    }, { deadline, now });
   if (collection.timedOut || now() > deadline) {
     result.journeyCaptureError = analyticsCaptureError("collectionDeadline");
     if (receiptRecognized && !settleError) {
@@ -2824,7 +3109,10 @@ async function collectOrderAnalytics({
     if (receiptRecognized && !settleError) result.receiptCaptureError = analyticsCaptureError("unreadable");
   } else {
     result.journeyCapture = collection.value.journey;
-    if (receiptRecognized && !settleError) result.receiptCapture = collection.value.currentDocument;
+    if (receiptRecognized && !settleError) {
+      result.receiptCapture = collection.value.currentDocument;
+      if (collection.value.documentUrl) result.receiptDocumentUrl = collection.value.documentUrl;
+    }
   }
   if (receiptRecognized && settleError) result.receiptCaptureError = settleError;
   return result;
@@ -2952,11 +3240,13 @@ async function runSingleBrowserTestOrder(context, checkoutPage, plan, args, runI
         receiptRecognized,
         settleMs: numberArg(planArgs["analytics-settle"], DEFAULT_SETTLE_TIMEOUT_MS),
         deadline: orderDeadline ?? Date.now(),
+        readDocumentUrl: () => (page ? safePageUrl(page) : null),
       });
       if (captures.journeyCapture) result.analytics_journey_capture = captures.journeyCapture;
       if (captures.journeyCaptureError) result.analytics_journey_capture_error = captures.journeyCaptureError;
       if (captures.receiptCapture) result.receipt_analytics_capture = captures.receiptCapture;
       if (captures.receiptCaptureError) result.receipt_analytics_capture_error = captures.receiptCaptureError;
+      if (captures.receiptDocumentUrl) result.receipt_document_url = captures.receiptDocumentUrl;
     } else if (analyticsAttachError) {
       result.analytics_journey_capture_error = analyticsAttachError;
       if (receiptRecognized) result.receipt_analytics_capture_error = analyticsAttachError;
@@ -3089,6 +3379,11 @@ function receiptAnalyticsAttempt(plan, result) {
     planId: id,
     receiptRecognized,
     receiptUrl: redactUrlQuery(finalUrl),
+    // Where the receipt page actually was once its analytics settled and were
+    // collected; absent when that reading was not taken.
+    ...(receiptRecognized && result?.receipt_document_url
+      ? { receiptDocumentUrl: redactUrlQuery(result.receipt_document_url) }
+      : {}),
     ...(receiptRecognized && result?.receipt_analytics_capture
       ? { capture: result.receipt_analytics_capture }
       : {}),
@@ -3260,19 +3555,29 @@ async function executeTestOrderPath({ page, events, email, ladder, checkoutPage,
     }
     const step = upsellSteps[stepIndex];
     const actionTrace = createUpsellActionTrace({ page, events, topologyPlan, stepIndex, path: step });
+    const stepBudgetMs = budget();
+    const stepStartedMs = Date.now();
     await ladder.run("upsell_action", async () => {
       const initialLineItems = order.receipt_line_items.slice();
       const initialUpsellMutationCount = upsellMutationCount(events);
       await actionTrace.inspect();
       await waitForUpsellPageReady(page, args);
       await actionTrace.inspect();
+      const responseIndexBefore = events.responses.length;
       const upsell = await clickUpsellPath(page, step, { events, stepIndex, trace: actionTrace });
       const preferredOrderBody = upsell.api_response_order_body || null;
       delete upsell.api_response_order_body;
       order.upsell = upsell;
       order.upsell_steps.push(upsell);
       order.final_url = safePageUrl(page);
-      const refreshed = await buildOrderEvidence({ page, events, path, email, checkoutPage, args, preferredOrderBody });
+      const { refreshed, lateUpsellEvidence } = await refreshUpsellStepEvidence({
+        page, events, path, email, checkoutPage, args, step, upsell, preferredOrderBody, initialLineItems, responseIndexBefore,
+        // Keep the rest of the step's budget for the read-back after the wait.
+        lateWaitMs: Math.min(
+          LATE_UPSELL_EVIDENCE_TIMEOUT_MS,
+          stepBudgetMs - (Date.now() - stepStartedMs) - LATE_UPSELL_EVIDENCE_RESERVE_MS,
+        ),
+      });
       order.final_receipt_line_items = refreshed.receipt_line_items;
       if (refreshed.receipt_line_items.length) {
         order.cart_state = refreshed.cart_state;
@@ -3284,9 +3589,9 @@ async function executeTestOrderPath({ page, events, email, ladder, checkoutPage,
         order.verification.currency = refreshed.verification.currency;
       }
       if (step === "accept") {
-        const proof = acceptedUpsellProof(order.receipt_line_items, initialLineItems, upsell.expected_items, events);
+        const proof = acceptedUpsellStepProof(upsell, lateUpsellEvidence, acceptedUpsellProof(order.receipt_line_items, initialLineItems, upsell.expected_items, events));
         upsell.verification = {
-          accepted_upsell_line_present: proof.ok,
+          accepted_upsell_line_present: proof.unverified ? null : proof.ok,
           accepted_upsell_match: proof,
           upsell_api_response_seen: upsell.api_response_seen,
           upsell_api_response_status: upsell.api_response_status,
@@ -3304,7 +3609,7 @@ async function executeTestOrderPath({ page, events, email, ladder, checkoutPage,
       actionTrace.markStepCompleted();
       return `step ${stepIndex + 1}: ${step}`;
     }, {
-      timeoutMs: budget(),
+      timeoutMs: stepBudgetMs,
       evidence: actionTrace.summary,
       formatError: actionTrace.formatError,
     });
@@ -3336,7 +3641,19 @@ async function executeTestOrderPath({ page, events, email, ladder, checkoutPage,
 
   const acceptedSteps = (order.upsell_steps || []).filter((step) => step.path === "accept");
   if (acceptedSteps.length) {
-    order.verification.accepted_upsell_line_present = acceptedSteps.every((step) => step.verification?.accepted_upsell_line_present === true);
+    const unverifiedSteps = acceptedSteps.filter((step) => step.verification?.accepted_upsell_match?.unverified === true);
+    const confirmedMissing = acceptedSteps.some((step) => step.verification?.accepted_upsell_line_present === false);
+    // Unknown, not false, when every step that is not proven is only
+    // unverified: false would read as a confirmed missing line.
+    order.verification.accepted_upsell_line_present = unverifiedSteps.length && !confirmedMissing
+      ? null
+      : acceptedSteps.every((step) => step.verification?.accepted_upsell_line_present === true);
+    if (unverifiedSteps.length) {
+      order.verification.upsell_unverified = unverifiedSteps.map((step) => step.verification.accepted_upsell_match.reason);
+      // Whatever else the path finds, an order whose accepted upsell nothing
+      // proved is not a verified order (#505).
+      order.verification.verified = false;
+    }
     order.verification.upsell_api_response_seen = acceptedSteps.every((step) => step.verification?.upsell_api_response_seen === true);
     order.verification.accepted_upsell_matches = acceptedSteps.map((step) => step.verification?.accepted_upsell_match).filter(Boolean);
   }
@@ -3362,10 +3679,20 @@ async function executeTestOrderPath({ page, events, email, ladder, checkoutPage,
   }
 
   const pathFailures = [...stepFailures, ...receiptFailures, ...couponFailures];
-  const ok = order.ok && pathFailures.length === 0;
+  const clean = order.ok && pathFailures.length === 0;
+  // A path whose only open question is an unverified accepted upsell is not
+  // a pass: nothing proved the line was added. `ok` stays false so no reader
+  // of the result or the order takes it as proven, and `upsell_unverified`
+  // tells it apart from a failure: the dispatcher neither re-runs it (that
+  // would buy a second order) nor recovers it, and the assertion reports it
+  // for manual review (#505). The order itself was created and read back, so
+  // order.ok keeps saying so; only its verification drops to unverified.
+  const upsellUnverified = clean ? order.verification.upsell_unverified || null : null;
+  const ok = clean && !upsellUnverified;
   return {
     ok,
-    error: ok ? null : order.error || order.upsell?.error || pathFailures.join("; ") || "accepted upsell did not appear in final order lines",
+    ...(upsellUnverified ? { upsell_unverified: upsellUnverified } : {}),
+    error: clean ? null : order.error || order.upsell?.error || pathFailures.join("; ") || "accepted upsell did not appear in final order lines",
     order,
     events: sanitizedEvents(events),
   };
@@ -3466,10 +3793,8 @@ async function enterCartViaLanding({ page, checkoutPage, entryPage, selectedPack
   // The index is the control's position among what its own locator matches,
   // so it replays with nth(); no selector is rebuilt from an attribute value.
   const target = page.locator(control.kind === "add_to_cart" ? CART_ENTRY_CONTROL_SELECTOR : "a[href]").nth(control.index);
-  await target.scrollIntoViewIfNeeded().catch(() => {});
-  await target.click({ timeout: 8000 }).catch(async () => {
-    await target.click({ force: true, timeout: 8000 });
-  });
+  const perpetual = await scrollControlIntoView(target);
+  await clickControl(target, { timeout: 8000, perpetual });
 
   // The SDK owns the navigation (data-next-url, or the link the SDK reads
   // forcePackageId from on arrival). Waiting for the URL is what proves the
@@ -3763,8 +4088,8 @@ async function selectRequestedCart(page, args) {
   for (const item of cart) {
     const target = page.locator(packageCardClickSelector({ package_id: item.packageId })).first();
     if (await target.count().catch(() => 0)) {
-      await target.scrollIntoViewIfNeeded().catch(() => {});
-      await target.click({ timeout: 5000 }).catch(() => {});
+      const perpetual = await scrollControlIntoView(target);
+      await clickControl(target, { timeout: 5000, forceFallback: false, perpetual }).catch(() => {});
     }
   }
 }
@@ -3789,10 +4114,8 @@ async function selectPackageCard(page, item) {
   const candidate = resolvePackageCardCandidate(await renderedPackageCardCandidates(page), item);
   const selector = packageCardClickSelector(candidate);
   const target = page.locator(selector).first();
-  await target.scrollIntoViewIfNeeded().catch(() => {});
-  await target.click({ timeout: 5000 }).catch(async () => {
-    await target.click({ force: true, timeout: 5000 });
-  });
+  const perpetual = await scrollControlIntoView(target);
+  await clickControl(target, { timeout: 5000, perpetual });
   const state = await packageCardSelectionState(page, selector);
   if (state === "unselected") {
     throw new Error(`--select-package ${item.packageId}: card matched ${selector} but did not enter a selected state after click`);
@@ -4390,8 +4713,8 @@ async function submitCheckout(page) {
   await closeAddressAutocomplete(page);
   const submit = page.locator('button.submit-button[os-checkout-payment="combo"], button[os-checkout-payment="combo"], button[type="submit"]').first();
   await submit.waitFor({ state: "visible" });
-  await submit.scrollIntoViewIfNeeded();
-  await submit.click();
+  const perpetual = await scrollControlIntoView(submit);
+  await clickControl(submit, { forceFallback: false, perpetual });
 }
 
 // When events are supplied (the post-submit wait), a platform-rejected order
@@ -4536,6 +4859,81 @@ async function waitForLateOrderEvidence(page, events, { timeoutMs = 4000, interv
   }
 }
 
+// Playwright waits for an element to be "stable" (the same box on two
+// consecutive animation frames) before scrollIntoViewIfNeeded() and click().
+// A control under an infinite geometry animation never is: stock upsell accept
+// buttons carry pb-animate="pulse-upsell", which the shared next-core.css
+// scales forever with !important and no reduced-motion override. An unbounded
+// scroll then burned the whole 30s default action timeout and a normal click
+// another 10s before the forced fallback fired (#481). Scrolling through the
+// DOM has no stability wait, and a perpetually animated control is clicked with
+// force once visible, because waiting for it to settle can only time out.
+const CONTROL_SCROLL_TIMEOUT_MS = 2000;
+const UPSELL_CLICK_TIMEOUT_MS = 10000;
+const UPSELL_MUTATION_TIMEOUT_MS = 20000;
+
+// Runs in the page: optionally scrolls the control to the viewport centre
+// (no stability wait), and reports whether the control or an ancestor runs an
+// infinite animation over a property that moves or resizes its box.
+// Paint-only loops (opacity, color, shadow) leave the box stable, so those
+// still take the normal click. Self-contained so Playwright can serialize it.
+function probeControlInPage(element, { scroll }) {
+  if (scroll) element.scrollIntoView({ block: "center", inline: "nearest" });
+  // Properties that move or resize the element's box, or its position
+  // inside an animated ancestor. Paint-only properties are left out.
+  const geometry = /^(transform|translate|scale|rotate|perspective|top|left|right|bottom|inset|width|height|blockSize|inlineSize|min|max|margin|padding|gap|rowGap|columnGap|fontSize|lineHeight|letterSpacing|textIndent|border(Top|Right|Bottom|Left|Block|Inline)?(Start|End)?Width)/;
+  const movesBox = (animation) => {
+    const timing = animation.effect?.getComputedTiming?.();
+    if (animation.playState !== "running" || timing?.iterations !== Infinity) return false;
+    const keyframes = animation.effect?.getKeyframes?.() || [];
+    return keyframes.some((frame) => Object.keys(frame).some((property) => geometry.test(property)));
+  };
+  for (let node = element; node; node = node.parentElement) {
+    if (typeof node.getAnimations === "function" && node.getAnimations().some(movesBox)) return true;
+  }
+  return false;
+}
+
+async function probeControl(locator, { scroll, timeout = CONTROL_SCROLL_TIMEOUT_MS }) {
+  try {
+    return await locator.evaluate(probeControlInPage, { scroll }, { timeout }) === true;
+  } catch {
+    // Best effort, as the scroll always was: the click still scrolls itself,
+    // and an unprobed control takes the normal click.
+    return false;
+  }
+}
+
+// One page round trip per click: scrolls the control into view and returns
+// the `perpetual` flag clickControl takes, so no call site probes twice.
+async function scrollControlIntoView(locator, options = {}) {
+  return probeControl(locator, { ...options, scroll: true });
+}
+
+async function isPerpetuallyAnimated(locator, options = {}) {
+  return probeControl(locator, { ...options, scroll: false });
+}
+
+// `perpetual` is the flag scrollControlIntoView returned, so the click does
+// not probe again; without it the click probes for itself. forceFallback: false keeps a caller's strict click
+// for a control that can settle; a perpetually animated control is always
+// forced, whatever forceFallback says, because a strict click on it can only
+// time out. It must still become visible first, or the visibility error throws.
+async function clickControl(locator, { timeout, forceFallback = true, perpetual } = {}) {
+  const animated = perpetual ?? await isPerpetuallyAnimated(locator);
+  if (animated) {
+    await locator.waitFor({ state: "visible", timeout });
+    await locator.click({ force: true, timeout });
+    return;
+  }
+  try {
+    await locator.click({ timeout });
+  } catch (error) {
+    if (!forceFallback) throw error;
+    await locator.click({ force: true, timeout });
+  }
+}
+
 async function clickUpsellPath(page, path, { trace = null } = {}) {
   const offerUrl = safePageUrl(page);
   const action = path === "accept" ? "add" : "skip";
@@ -4545,27 +4943,36 @@ async function clickUpsellPath(page, path, { trace = null } = {}) {
     return { path, clicked: false, error: `Missing upsell control ${selector}` };
   }
   const expectedItems = path === "accept" ? await selectedUpsellItems(page) : [];
+  const perpetual = await scrollControlIntoView(control);
+  // Armed at the click, not before the scroll, and budgeted to outlast a
+  // normal attempt that times out into its forced fallback: the watch must
+  // still be listening when the click that actually fires posts (#481).
+  //
+  // Only a request started at or after the watch was armed can be this
+  // click's. An earlier step posts to the same order-upsells URL, and when
+  // its own watch expired its response may still arrive during this click
+  // (#505). armedAt and the request's start time are both epoch milliseconds
+  // on the system clock (Date.now() here; Playwright's timing().startTime is
+  // the browser's wall time at request start), and armedAt is read before the
+  // click is sent, so this click's request starts at or after it. A request
+  // with no known start time is not excluded: nothing shows it is stale.
+  const armedAt = Date.now();
   const mutationPromise = path === "accept"
-    ? page.waitForResponse((response) => (
-        response.request().method() === "POST"
-        && isOrderUpsellsUrl(response.url())
-      ), { timeout: 20000 }).catch(() => null)
+    ? page.waitForResponse((response) => {
+        if (response.request().method() !== "POST" || !isOrderUpsellsUrl(response.url())) return false;
+        const startedAt = responseRequestStartedAt(response);
+        return startedAt === null || startedAt >= armedAt;
+      }, { timeout: UPSELL_MUTATION_TIMEOUT_MS + (perpetual ? 0 : UPSELL_CLICK_TIMEOUT_MS) }).catch(() => null)
     : Promise.resolve(null);
-  await control.scrollIntoViewIfNeeded().catch(() => {});
   trace?.markClickAttempted();
-  let clickCompleted = false;
-  try {
-    await control.click({ timeout: 10000 });
-    clickCompleted = true;
-  } catch {
-    await control.click({ force: true });
-    clickCompleted = true;
-  }
-  if (clickCompleted) trace?.markClickCompleted();
+  await clickControl(control, { timeout: UPSELL_CLICK_TIMEOUT_MS, perpetual });
+  trace?.markClickCompleted();
   const mutationResponse = await mutationPromise;
-  const mutationBody = mutationResponse ? await readJsonResponseBody(mutationResponse) : null;
+  const bodyRead = mutationResponse
+    ? await readJsonResponseBodyBounded(mutationResponse, RESPONSE_BODY_READ_TIMEOUT_MS)
+    : null;
   await waitForCheckoutResult(page);
-  return {
+  const record = {
     path,
     clicked: true,
     offer_url: offerUrl,
@@ -4574,8 +4981,21 @@ async function clickUpsellPath(page, path, { trace = null } = {}) {
     api_response_seen: Boolean(mutationResponse),
     api_response_status: mutationResponse?.status() || null,
     api_response_url: mutationResponse?.url() || null,
-    api_response_order_body: mutationBody,
+    api_response_order_body: bodyRead?.body ?? null,
+    // When the mutation's response arrived (epoch ms, the browser's clock as
+    // Date.now()). Only a read-back requested after this reflects the upsell.
+    mutation_responded_at: mutationRespondedAt(mutationResponse),
+    // How the bounded body read ended. A timed-out read means the mutation's
+    // own evidence is missing, not that the upsell failed; the runner then
+    // waits for a later read-back before it judges the step.
+    ...(bodyRead ? { api_response_body_read: { timed_out: bodyRead.timed_out, waited_ms: bodyRead.waited_ms, bound_ms: bodyRead.bound_ms } } : {}),
   };
+  // The request this click made. Another step's upsell mutation posts to the
+  // same order-upsells URL, so a late body is this step's only when it
+  // answers this request.
+  const mutationRequest = mutationResponse ? responseRequest(mutationResponse) : null;
+  if (mutationRequest) record[REQUEST_IDENTITY] = mutationRequest;
+  return record;
 }
 
 function receiptProofEvidence(order) {
@@ -5325,13 +5745,22 @@ async function recoverCreatedOrder({ context, attempt, plan = null, checkoutPage
     }
 
     const cleared = remaining.length === 0;
+    // An unverified accepted upsell is not a failure recovery can clear, nor
+    // one it can re-check: re-reading the order says nothing about which
+    // mutation added what. With everything else cleared, the recovered result
+    // is the same manual-review shape executeTestOrderPath returns (#505).
+    const upsellUnverified = Array.isArray(order.verification?.upsell_unverified) && order.verification.upsell_unverified.length
+      ? order.verification.upsell_unverified
+      : null;
+    if (upsellUnverified) recovered.verification.verified = false;
     return {
       attempts: 1,
       cleared,
       checks,
       result: {
         ...attempt,
-        ok: cleared,
+        ok: cleared && !upsellUnverified,
+        ...(cleared && upsellUnverified ? { upsell_unverified: upsellUnverified } : {}),
         error: cleared ? null : remaining.join("; "),
         order: recovered,
       },
@@ -5469,19 +5898,35 @@ function testOrderAssertion(page, plan, result, firstAttempt = null, creationRec
   // runner deliberately refused to re-run, and the operator needs to know that
   // before they run the path again by hand.
   const stoppedForAmbiguity = creationRecord?.action === "stopped";
+  // The order was created and nothing failed, but an accepted upsell could
+  // not be checked: its mutation body never loaded and no read-back arrived.
+  // Neither proved nor disproved, so a human decides, as for a hosted checkout.
+  // The result is not ok (the path is not proven), but nothing failed either.
+  // A result that says ok while its order still carries unverified reasons is
+  // read the same way: never a pass. No current producer does that (both
+  // executeTestOrderPath and recoverCreatedOrder clear ok when an upsell is
+  // unverified); this arm stops a future ok-producing path, like the recovery
+  // that once promoted an unverified upsell to pass, from doing it silently.
+  const orderUnverified = result.order?.verification?.upsell_unverified;
+  const upsellUnverified = Array.isArray(result.upsell_unverified) && result.upsell_unverified.length
+    ? result.upsell_unverified
+    : result.ok && Array.isArray(orderUnverified) && orderUnverified.length ? orderUnverified : null;
+  const created = result.ok || Boolean(upsellUnverified);
   return assertion({
     id: `browser-test-order:${id}`,
     family: "browser-test-order",
     page,
-    status: result.ok ? STATUS.PASS : STATUS.FAIL,
-    severity: result.ok ? undefined : SEVERITY.BLOCKER,
+    status: created ? (upsellUnverified ? STATUS.MANUAL_REVIEW : STATUS.PASS) : STATUS.FAIL,
+    severity: created ? (upsellUnverified ? SEVERITY.WARN : undefined) : SEVERITY.BLOCKER,
     expected: "test order created through deployed checkout page",
-    actual: result.ok
-      ? result.order.next_order_id || result.order.ref_id
+    actual: created
+      ? upsellUnverified
+        ? `${result.order.next_order_id || result.order.ref_id}; ${upsellUnverified.join("; ")}`
+        : result.order.next_order_id || result.order.ref_id
       : stoppedForAmbiguity
         ? `${failureText} — not re-run: ${creationRecord.classification.reason}. Check for an existing order against this run's QA email before running this path again.`
         : failureText,
-    evidence: result.ok
+    evidence: created
       ? {
           ...planEvidence,
           ...retry,
@@ -5494,6 +5939,7 @@ function testOrderAssertion(page, plan, result, firstAttempt = null, creationRec
           line_count: result.order.receipt_line_items.length,
           ...(receiptProofEvidence(result.order) ? { receipt_proof: receiptProofEvidence(result.order) } : {}),
           ...(path === "accept" ? { accepted_upsell_line_present: result.order.verification?.accepted_upsell_line_present } : {}),
+          ...(upsellUnverified ? { upsell_unverified: upsellUnverified } : {}),
           ...(result.order.upsell ? { upsell_clicked: result.order.upsell.clicked, upsell_final_url: result.order.upsell.final_url } : {}),
           ...(result.order.upsell_steps ? { upsell_steps: result.order.upsell_steps.map(summarizeUpsellStep) } : {}),
           ...(result.order.verification?.accepted_upsell_matches ? { accepted_upsell_matches: result.order.verification.accepted_upsell_matches } : {}),
@@ -5514,6 +5960,43 @@ function testOrderAssertion(page, plan, result, firstAttempt = null, creationRec
   });
 }
 
+// When a response's headers arrived, in epoch milliseconds, or null.
+function mutationRespondedAt(response) {
+  try {
+    const timing = response.request().timing();
+    const at = timing.startTime + timing.responseStart;
+    return Number.isFinite(at) && timing.startTime > 0 && timing.responseStart >= 0 ? at : null;
+  } catch {
+    return null;
+  }
+}
+
+// The Playwright Request a response answers, kept under a symbol key so it
+// never reaches serialized evidence (JSON and the sanitized event log skip
+// it). Playwright hands every listener the same Request object for one
+// request, and a different one for each request, even to the same URL: an
+// upsell step matches its own mutation's late body by this identity (#505).
+const REQUEST_IDENTITY = Symbol("campaigns-os.request-identity");
+
+function responseRequest(response) {
+  try {
+    return response.request() || null;
+  } catch {
+    return null;
+  }
+}
+
+// When the browser started a response's request, in epoch milliseconds (the
+// same clock as Date.now()), or null when Playwright does not report it.
+function responseRequestStartedAt(response) {
+  try {
+    const startTime = response.request().timing().startTime;
+    return Number.isFinite(startTime) && startTime > 0 ? startTime : null;
+  } catch {
+    return null;
+  }
+}
+
 function captureCheckoutEvents(page) {
   const events = { requests: [], responses: [], failed: [], console: [], pageErrors: [], navigations: [] };
   const interesting = /\/api\/v1\/(?:orders|upsells|carts)\/?|\/transactions|spreedly|campaigns\.apps/i;
@@ -5525,13 +6008,24 @@ function captureCheckoutEvents(page) {
       postData: summarizeRequestPostData(request.postData()),
     });
   });
+  // Nothing awaits this listener, so its body read stays unbounded: an entry
+  // lands whenever its body finishes loading, and waitForLateOrderEvidence
+  // polls for it. A bound here would record a slow but successful order body
+  // as null for good, and the order would read as not created.
   page.on("response", async (response) => {
     if (!interesting.test(response.url())) return;
-    events.responses.push({
+    // Taken before the body read: an entry lands in the log when its body
+    // finishes, so its position says nothing about when it was requested.
+    const requestStartedAt = responseRequestStartedAt(response);
+    const request = responseRequest(response);
+    const entry = {
       status: response.status(),
       url: response.url(),
-      body: await readJsonResponseBody(response),
-    });
+      request_started_at: requestStartedAt,
+      body: await readJsonResponseBodyWhenLoaded(response),
+    };
+    if (request) entry[REQUEST_IDENTITY] = request;
+    events.responses.push(entry);
   });
   page.on("requestfailed", (request) => {
     if (!interesting.test(request.url())) return;
@@ -5552,11 +6046,63 @@ function captureCheckoutEvents(page) {
   return events;
 }
 
-async function readJsonResponseBody(response) {
-  const text = await response.text().catch(() => null);
+// Playwright's response.text() waits for the body to finish loading. A page
+// that navigates away as soon as the headers land (an SDK that reads only the
+// status before redirecting) can leave that wait pending forever. Only a
+// caller that blocks the run on the body needs a bound: the upsell mutation
+// read in clickUpsellPath. There the body is evidence, not the proof of the
+// response, so an unread body is reported as null after a short bound instead
+// of hanging the order run. Playwright has no way to cancel a pending body
+// read; the abandoned read is a protocol callback, not a socket this process
+// owns, and it is released when the run closes the browser context.
+const RESPONSE_BODY_READ_TIMEOUT_MS = 3000;
+
+// For callers that nothing awaits (the checkout event listener): a late body
+// still arrives, and a body that never loads just never records an entry.
+async function readJsonResponseBodyWhenLoaded(response) {
+  const text = await Promise.resolve().then(() => response.text()).catch(() => null);
   return parseMaybeJson(redactSensitive(text));
 }
 
+// Callers that block on the read always get the fixed bound; only the test
+// hook picks a shorter one.
+async function readJsonResponseBody(response) {
+  return readJsonResponseBodyWithin(response, RESPONSE_BODY_READ_TIMEOUT_MS);
+}
+
+async function readJsonResponseBodyWithin(response, timeoutMs) {
+  return (await readJsonResponseBodyBounded(response, timeoutMs)).body;
+}
+
+// The bounded read, with a record of how it ended. `timed_out` is true only
+// when the bound fired while the read was still pending, never when the read
+// failed or returned nothing: a caller must be able to tell "the body was not
+// read in time" (the mutation may still have succeeded) from "the body was
+// read". `waited_ms` covers the read alone.
+async function readJsonResponseBodyBounded(response, timeoutMs) {
+  // A missing, zero or unbounded value would reintroduce the hang.
+  if (!(Number.isFinite(timeoutMs) && timeoutMs > 0)) timeoutMs = RESPONSE_BODY_READ_TIMEOUT_MS;
+  const started = Date.now();
+  const TIMED_OUT = Symbol("timed out");
+  let timer = null;
+  const bounded = new Promise((resolve) => { timer = setTimeout(() => resolve(TIMED_OUT), timeoutMs); });
+  const read = Promise.resolve()
+    .then(() => response.text())
+    .catch(() => null);
+  try {
+    const text = await Promise.race([read, bounded]);
+    const timedOut = text === TIMED_OUT;
+    return {
+      body: timedOut ? null : parseMaybeJson(redactSensitive(text)),
+      timed_out: timedOut,
+      waited_ms: Date.now() - started,
+      bound_ms: timeoutMs,
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 function lastJsonResponse(events, pattern) {
   for (let index = events.responses.length - 1; index >= 0; index -= 1) {
     const response = events.responses[index];
@@ -5621,8 +6167,8 @@ async function clickVisibleControlByText(page, pattern, { within = null } = {})
     const control = controls.nth(index);
     const text = trim((await control.innerText().catch(() => "")) || (await control.getAttribute("value").catch(() => "")));
     if (!pattern.test(text)) continue;
-    await control.scrollIntoViewIfNeeded().catch(() => {});
-    await control.click({ timeout: 8000 });
+    const perpetual = await scrollControlIntoView(control);
+    await clickControl(control, { timeout: 8000, forceFallback: false, perpetual });
     return true;
   }
   throw new Error(`No visible control matched ${pattern}`);
@@ -6228,9 +6774,13 @@ async function selectedUpsellItems(page) {
 // order-upsell API added it. The live network observation (apiResponseSeen) is a
 // best-effort signal that can miss the request on fast stepper-accept client nav, so
 // it must not block on its own. Block only when the read-back proof also fails.
+//
+// An unverified proof (the mutation answered 2xx but its body never loaded, and
+// no later read-back arrived) is not a failure: nothing showed the line
+// missing. It is reported for manual review instead (upsell_unverified).
 function upsellAcceptStepFailures(stepIndex, proof, apiResponseSeen) {
   const failures = [];
-  if (!proof.ok) {
+  if (!proof.ok && !proof.unverified) {
     failures.push(`step ${stepIndex + 1}: ${proof.reason}`);
     if (!apiResponseSeen) {
       failures.push(`step ${stepIndex + 1}: upsell accept did not call order upsell API`);
@@ -6252,6 +6802,141 @@ function upsellActionStepFailures(stepIndex, action, upsell, proof) {
   return failures;
 }
 
+// How long an accept whose mutation body timed out waits for other evidence
+// of that mutation, and the slice of the step budget kept for the read-back
+// after it. The whole step stays inside its budget (45s by default).
+const LATE_UPSELL_EVIDENCE_TIMEOUT_MS = 15000;
+const LATE_UPSELL_EVIDENCE_RESERVE_MS = 3000;
+
+function upsellBodyReadTimedOut(upsell) {
+  const status = Number(upsell?.api_response_status);
+  return upsell?.api_response_body_read?.timed_out === true && status >= 200 && status < 300;
+}
+
+// After the bounded read gave up on a 2xx upsell mutation body, the lines the
+// runner already holds are the checkout's, from before the accept. Judging
+// the upsell against them would call a slow success "no new upsell line".
+// Wait, within a bound, for evidence of this mutation captured after the
+// click: its own body landing late in the event log (the unbounded listener
+// keeps reading it), or an order read-back whose lines carry the accepted
+// upsell. Returns the body to judge from, or source "none" when neither came.
+//
+// "Its own body" is the entry answering the very request this step's click
+// made (mutationRequest, Playwright request identity), not any order-upsells
+// URL: every upsell step in a path, on one page or on separate pages, posts
+// to the same /orders/<ref>/upsells/ URL, and an earlier step's slow body can
+// land during this step's wait. Taking it would judge this step by another
+// step's lines. With no request identity no late body counts (#505).
+//
+// A read-back whose request started after the upsell mutation's response
+// arrived (by the browser's request start time, not its position in the log,
+// which reflects when its body finished) that shows the persisted order
+// without the accepted line is a definitive negative, not an absence of
+// evidence. Anchoring on the mutation, not the click attempt, also excludes a
+// read-back started while the click was still waiting to fire. It does not end the wait early (a
+// later read-back may still carry the line), but when the wait ends with no
+// positive evidence the latest such read-back is returned as
+// "order_read_back_missing_line", and the step fails instead of going to
+// manual review. A read-back requested before that, or with no known start
+// time, never counts as a negative.
+async function waitForLateUpsellEvidence(events, { responseIndexBefore, mutationRequest = null, mutationRespondedAt = null, initialLineItems, expectedItems, timeoutMs, intervalMs = 250 }) {
+  const started = Date.now();
+  const deadline = started + Math.max(0, Number(timeoutMs) || 0);
+  const latestMissingLineReadBack = () => {
+    const fresh = events.responses.slice(responseIndexBefore);
+    for (let index = fresh.length - 1; index >= 0; index -= 1) {
+      const response = fresh[index];
+      if (!response.body || typeof response.body !== "object" || Array.isArray(response.body)) continue;
+      if (!(response.status >= 200 && response.status < 300)) continue;
+      if (!ORDER_DETAIL_RESPONSE_PATTERN.test(response.url)) continue;
+      if (!(Number.isFinite(mutationRespondedAt) && Number.isFinite(response.request_started_at) && response.request_started_at >= mutationRespondedAt)) continue;
+      const lines = extractReceiptLines(response.body);
+      if (!Array.isArray(lines) || lines.length === 0) continue;
+      return response.body;
+    }
+    return null;
+  };
+  const find = () => {
+    const fresh = events.responses.slice(responseIndexBefore);
+    for (let index = fresh.length - 1; index >= 0; index -= 1) {
+      const response = fresh[index];
+      if (!response.body || typeof response.body !== "object" || Array.isArray(response.body)) continue;
+      if (!(response.status >= 200 && response.status < 300)) continue;
+      if (!ORDER_UPSELLS_RESPONSE_PATTERN.test(response.url)) continue;
+      if (mutationRequest && response[REQUEST_IDENTITY] === mutationRequest) return { source: "late_upsell_body", body: response.body };
+    }
+    for (let index = fresh.length - 1; index >= 0; index -= 1) {
+      const response = fresh[index];
+      if (!response.body || typeof response.body !== "object" || Array.isArray(response.body)) continue;
+      if (!(response.status >= 200 && response.status < 300)) continue;
+      if (!ORDER_DETAIL_RESPONSE_PATTERN.test(response.url)) continue;
+      const proof = acceptedUpsellProof(extractReceiptLines(response.body), initialLineItems, expectedItems, events);
+      if (proof.ok) return { source: "order_read_back", body: response.body };
+    }
+    return null;
+  };
+  for (;;) {
+    const found = find();
+    if (found) return { ...found, waited_ms: Date.now() - started };
+    if (Date.now() >= deadline) {
+      const missing = latestMissingLineReadBack();
+      if (missing) return { source: "order_read_back_missing_line", body: missing, waited_ms: Date.now() - started };
+      return { source: "none", body: null, waited_ms: Date.now() - started };
+    }
+    await new Promise((resolve) => setTimeout(resolve, Math.min(intervalMs, Math.max(1, deadline - Date.now()))));
+  }
+}
+
+// The order evidence an upsell step is judged against. An accept whose
+// mutation body read timed out first waits for later evidence of that
+// mutation (waitForLateUpsellEvidence), and judges from that body when one
+// arrives: the runner's last order body is the checkout's otherwise.
+async function refreshUpsellStepEvidence({ page, events, path, email, checkoutPage, args, step, upsell, preferredOrderBody = null, initialLineItems, responseIndexBefore, lateWaitMs = LATE_UPSELL_EVIDENCE_TIMEOUT_MS }) {
+  let lateUpsellEvidence = null;
+  let judgedBody = preferredOrderBody;
+  if (step === "accept" && upsellBodyReadTimedOut(upsell)) {
+    lateUpsellEvidence = await waitForLateUpsellEvidence(events, {
+      responseIndexBefore,
+      mutationRequest: upsell[REQUEST_IDENTITY] || null,
+      mutationRespondedAt: upsell.mutation_responded_at,
+      initialLineItems,
+      expectedItems: upsell.expected_items,
+      timeoutMs: lateWaitMs,
+    });
+    upsell.late_evidence = { source: lateUpsellEvidence.source, waited_ms: lateUpsellEvidence.waited_ms };
+    if (lateUpsellEvidence.body) judgedBody = lateUpsellEvidence.body;
+  }
+  const refreshed = await buildOrderEvidence({ page, events, path, email, checkoutPage, args, preferredOrderBody: judgedBody });
+  return { refreshed, lateUpsellEvidence };
+}
+
+// The accepted-upsell proof for one step, given how its evidence arrived. A
+// failed proof stands as a failure unless the mutation answered 2xx, its body
+// read timed out, and no later evidence of it arrived: then the lines judged
+// are stale, and the step is unverified rather than missing its upsell. A
+// post-click read-back without the line ("order_read_back_missing_line") is
+// such evidence, so the failure stands.
+//
+// A passing proof from those stale lines is no more evidence than a failing
+// one: lines on hand before this step's mutation answered cannot carry its
+// upsell, and can carry an earlier step's (whose body may have landed on the
+// same order-upsells URL meanwhile), so it is unverified too (#505).
+function acceptedUpsellStepProof(upsell, lateEvidence, proof) {
+  if (!upsellBodyReadTimedOut(upsell)) return proof;
+  if (lateEvidence && lateEvidence.source !== "none") return proof;
+  const read = upsell.api_response_body_read;
+  return {
+    ...proof,
+    ok: false,
+    unverified: true,
+    reason: `accepted upsell unverified: the order upsell API answered HTTP ${upsell.api_response_status} but its body did not load within ${read.bound_ms}ms, and no later order read-back showed the accepted line within ${lateEvidence?.waited_ms ?? 0}ms`,
+    matched_lines: [],
+    stale_reason: proof.ok
+      ? "the order lines on hand predate this step's upsell mutation, so a match in them is not evidence of it"
+      : proof.reason,
+  };
+}
+
 function acceptedUpsellProof(lines, initialLines, expectedItems, events) {
   if (!Array.isArray(lines) || lines.length === 0) {
     return { ok: false, reason: "final order lines were empty", expected_items: expectedItems || [], matched_lines: [] };
@@ -6352,6 +7037,8 @@ function summarizeUpsellStep(step) {
     expected_items: step.expected_items,
     api_response_seen: step.api_response_seen,
     api_response_status: step.api_response_status,
+    ...(step.api_response_body_read ? { api_response_body_read: step.api_response_body_read } : {}),
+    ...(step.late_evidence ? { late_evidence: step.late_evidence } : {}),
     accepted_upsell_line_present: step.verification?.accepted_upsell_line_present,
   };
 }
@@ -6489,6 +7176,8 @@ export const __qaBrowserTestHooks = Object.freeze({
   COUPON_APPLY_CONTROL_SELECTOR,
   analyticsCorrectnessCaptureAssertions,
   analyticsCorrectnessRunnerFailureAssertion,
+  captureAnalyticsCorrectnessInContext,
+  captureAnalyticsParityInContext,
   analyticsParityCaptureAssertions,
   analyticsParityRunnerFailureAssertion,
   acceptedUpsellProof,
@@ -6500,6 +7189,18 @@ export const __qaBrowserTestHooks = Object.freeze({
   primaryCtaInspectionScript,
   clickCouponApplyControl,
   isOrderUpsellsUrl,
+  clickUpsellPath,
+  isPerpetuallyAnimated,
+  readJsonResponseBody,
+  readJsonResponseBodyWithin,
+  readJsonResponseBodyBounded,
+  RESPONSE_BODY_READ_TIMEOUT_MS,
+  waitForLateUpsellEvidence,
+  refreshUpsellStepEvidence,
+  acceptedUpsellStepProof,
+  REQUEST_IDENTITY,
+  captureCheckoutEvents,
+  buildOrderEvidence,
   testEmail,
   testOrderPaths,
   testOrderPlans,