@nextcommerce/campaigns-os 1.43.1 → 1.46.0

package/src/qa-node.mjs

@@ -1,6 +1,7 @@
 import { campaignSpecIdentity, resolveCampaignIdentity, campaignIdentitiesMatch } from "./spec-source-identity.mjs";
-import { expectedBinding, createBindingScriptLoader, observeBinding, bindingAssertion } from './qa-binding-evidence.mjs';
+import { expectedBinding, createBindingScriptLoader, observeBinding, bindingAssertion, scriptParseAssertion } from './qa-binding-evidence.mjs';
 import { shellToken } from "./shell-token.mjs";
+import { applyQaBuildScope, specForQaScope } from "./qa-build-scope.mjs";
 import { requiredActionText } from "./gate-actions.mjs";
 import { parseOrderPathDepthFlag } from "./proof-policy.mjs";
 import {
@@ -29,13 +30,22 @@ const PACKAGE_ROOT = installModeResolve(installModeDirname(installModeFileUrl(im
 function cmd(verb, rest = "") {
   return `${invocationPrefixFor(PACKAGE_ROOT)} ${verb}${rest ? ` ${rest}` : ""}`;
 }
-import { runAnalyticsCorrectnessChecks, runAnalyticsParityChecks, runBrowserChecks, runBrowserTestOrders, testEmail, validatedOrderCreationLimit } from "./qa-browser.mjs";
+import { isSameAnalyticsCapturePage, runAnalyticsCorrectnessChecks, runAnalyticsParityChecks, runBrowserChecks, runBrowserTestOrders, testEmail, upsellActionCoverageWithoutOrders, validatedOrderCreationLimit } from "./qa-browser.mjs";
 import { assessReceiptPurchase } from "./qa-analytics-correctness.mjs";
 import { createVerdict, isFindingAssertion, QA_ASSERTION_FAMILY_VOCABULARY, SESSION_ENDING_DISPOSITIONS, SEVERITY, STATUS, validateVerdict } from "./qa-verdict.mjs";
 import { normalizeSdkMetaName, lookupSdkIgnoredMetaTag } from "./sdk-meta-tags.mjs";
 import { annotateQaAssertionCauses, formatCauseReportLines, formatCauseTag } from "./finding-cause.mjs";
 import { promoteQaVerdict, writeQaSidecar } from "./qa-sidecar.mjs";
 import { publishQaVerdict, qaPortalUrl, qaVerdictPublishBlock, QA_VERDICT_PUBLISHERS, skippedQaVerdictPublish } from "./qa-verdict-publish.mjs";
+import {
+  isLocalServePacket,
+  LOCAL_PROOF_BUILD_ENVIRONMENT,
+  LOCAL_PROOF_BUILD_ENVIRONMENT_FIELD,
+  LOCAL_PROOF_PARITY_FIELD,
+  recordedBuildEnvironment,
+  recordedProductionParity,
+} from "./local-proof.mjs";
+import { isLoopbackHostname } from "./remit.mjs";
 import { publishStoredVerdict, qaPublishTextLines, QA_PUBLISH_EXIT_CODES } from "./qa-publish.mjs";
 // Shared outgoing-edge resolver, so QA expectations and build-time wiring
 // cannot drift on which declared routing field wins.
@@ -88,6 +98,18 @@ import {
   unavailableCommercialCapture,
   unavailableCommercialReport,
 } from "./qa-commercial-parity.mjs";
+import {
+  LIVE_REF_CODES,
+  campaignDriftMessage,
+  disabledLiveRead,
+  evaluateLiveCampaignRefs,
+  extractRenderedRefs,
+  liveRefsDisabled,
+  liveRefFindingMessage,
+  liveRefsNotRunMessage,
+  readLiveCampaignForPacket,
+} from "./live-campaign-refs.mjs";
+import { specPackageRefs, specShippingRefs } from "./doctor/checks.mjs";
 
 // The producing runtime identity on every verdict. Read from package.json so
 // a verdict names the release that made it; a literal here outlived three
@@ -100,7 +122,7 @@ const HELP = `campaigns-os qa — Node/npm spec-aware QA
 Usage:
   campaigns-os qa parity --fixture <parity-fixture.json> --scenario <scenario-id> [--base-url <override>] [--baseline <url>] [--parity-order-json <file>] [--no-post-verdict]
   campaigns-os qa resolve --packet <campaign-runtime.build.json> [--base-url <url>] [--no-probe] [--probe-timeout-ms <ms>] [--json]
-  campaigns-os qa run --packet <campaign-runtime.build.json> [--base-url <url>] [--output-dir <dir>] [--no-remit] [--json]
+  campaigns-os qa run --packet <campaign-runtime.build.json> [--base-url <url>] [--output-dir <dir>] [--no-remit] [--no-live-refs] [--json]
   campaigns-os qa policy set --packet <campaign-runtime.build.json> [--allowed-domains-confirmed true|false] [--deploy-target <target>] [--preview-url <url>] [--production-url <url>] [--order-path-depth <off|common|full>] [--json]
   campaigns-os qa waive --packet <campaign-runtime.build.json> --assertion analytics-correctness:purchase-fires --reason "<why>" [--waived-by <who>] [--report <assembly-report.json>] [--json]
   campaigns-os qa promote --packet <campaign-runtime.build.json> --verdict <full-verdict.json> [--json]   # project one explicit qa-output verdict to the committed .campaign-runtime/qa-verdict.json sidecar
@@ -120,7 +142,7 @@ Options:
                                   Requires --base-url and --family. No Map ID / CampaignSpec needed.
   --spec <path>                   Local exported CampaignSpec JSON for the non-packet Map ID flow.
                                   Packet QA always uses packet.spec.local_path and rejects this override.
-  --proxy-base <url>              Campaign Map proxy base for /api/spec, /api/price-preview, and verdict publishing.
+  --proxy-base <url>              Campaign Map proxy base for /api/spec, /api/price-preview, /api/campaign, and verdict publishing.
   --base-url <url>                Deployed campaign root. Packet deploy URL is used when omitted.
                                   Commercial pages are checked automatically against /api/price-preview;
                                   no commercial sidecar or extra catalog flag is required.
@@ -156,6 +178,9 @@ Options:
                                   Record is not stamped; a refusal still exits 2, a clean dry run exits 0
                                   (--json: dry_run, would_publish, would_post).
   --no-remit                     When an ambient run session is active, write the local Run Record but skip Run Telemetry remit.
+  --no-live-refs                  qa run: skip the one read-only GET of <proxy-base>/api/campaign that checks each
+                                  served page's shipping and package refs against the live campaign; the verdict
+                                  records the check not_run with reason disabled, never a pass.
   --auth-cookie <cookie>          Cookie header for protected previews.
   --browser                       Run Playwright-rendered browser checks after static Node checks.
                                   Requires one-time setup: campaigns-os qa install-browser
@@ -168,8 +193,11 @@ Options:
                                   Create Playwright typed-card test orders through the tested checkout page.
                                   Test cards bypass the gateway and create no transactions, so no permission
                                   flags or packet policy are needed — just pick a mode. Default mode (bare
-                                  --test-order, or "common") runs checkout, first-offer accept/decline, and a
-                                  deduplicated shortest real receipt path when needed (at most 4 orders). "full" walks
+                                  --test-order, or "common") runs every actual terminal path when they fit under
+                                  the cap (--max-test-orders, default 6). Above the cap it runs checkout,
+                                  first-offer accept/decline, and a deduplicated shortest real receipt path, then
+                                  adds one decline path per offer/downsell page not yet declined, up to the cap,
+                                  and names any page left out. "full" walks
                                   every actual terminal path; cycles, missing routes, and reachable nonterminals
                                   block before browser launch. The default cap is 6; overflow names the exact raise.
                                   "tiers" is spec-driven: one strict-selection order per selector tier the
@@ -455,12 +483,22 @@ async function resolveQaInputs(args, {
     hiddenEagerMediaGate,
   });
   const qaWaivers = resolveQaWaivers({ packetPath, report: checkpointPreflight?.runtimeReport });
+  const qaScope = applyQaBuildScope(topologies, {
+    packet, report: checkpointPreflight?.runtimeReport,
+    targetRepo: checkpointPreflight?.targetRepo, publicRouteSlug,
+  });
   const brandContract = loadBrandContract(templateFamily);
+  const localServeAnalytics = resolveLocalServeAnalytics({
+    packet,
+    report: checkpointPreflight?.runtimeReport,
+    captureUrl: analyticsCaptureTarget.url || baseUrl,
+  });
   return {
     themeGate,
     polishGate,
     qaWaivers,
     analyticsCaptureTarget,
+    localServeAnalytics,
     brandContract: brandContract.contract,
     brandContractStatus: brandContract.status,
     packetPath,
@@ -481,7 +519,8 @@ async function resolveQaInputs(args, {
     specHash,
     templateFamily,
     commerceStructureContract,
-    topologies,
+    topologies: qaScope.topologies,
+    excludedPages: qaScope.excludedPages,
     checkpointGates: checkpointPreflight?.checkpointGates || nonPacketCheckpointGates(),
     // The report the checkpoint gates were evaluated on, and the target repo
     // whose default it may or may not be: what the printed remediation names.
@@ -2130,6 +2169,13 @@ async function runQa(args, options = {}) {
   // Fail-fast before anything resolves or launches. The authoritative check
   // lives on the creation budget itself, which every browser path builds.
   refuseBadOrderCreationLimit(args);
+  // Match dispatch: an active browser mode takes precedence over legacy API
+  // diagnostics. Only the selected legacy path requires a cart and API mode.
+  const browserMode = String(args["test-order"] || "off").toLowerCase();
+  const legacyMode = String(args["legacy-api-test-order"] || "off").toLowerCase();
+  if (browserMode === "off" && legacyMode !== "off") {
+    refusing(() => legacyTestOrderInputs({ ...args, "test-order": legacyMode }));
+  }
   const resolved = await resolveQaInputs(args);
   return runResolvedQa(args, resolved, options);
 }
@@ -2137,7 +2183,7 @@ async function runQa(args, options = {}) {
 // `runSessionActive` is threaded in from the CLI's single ambient-session read
 // rather than re-discovered here, so the closeout command this run prints and
 // the run_id the session will close under come from the same observation.
-async function runResolvedQa(args, resolved, { runSessionActive = false } = {}) {
+async function runResolvedQa(args, resolved, { runSessionActive = false, liveCampaign = undefined, liveCampaignFetch = globalThis.fetch } = {}) {
   const startedAt = new Date().toISOString();
   const runId = generateRunId();
   const gate = resolved.themeGate;
@@ -2207,12 +2253,19 @@ async function runResolvedQa(args, resolved, { runSessionActive = false } = {})
 
   const assertions = [
     ...checkpointAssertions,
+    ...(resolved.excludedPages || []).map(page => assertion({
+      id: `build-scope:${page.page_id}`, family: "funnel-flow", page,
+      status: STATUS.SKIPPED,
+      expected: "Only built routes are preview-QA targets",
+      actual: "out_of_build_scope",
+      evidence: { reason: "out_of_build_scope" },
+    })),
     ...(polishGate?.owned_checkpoint_only ? [] : [polishGateAssertion(polishGate)]),
     themeGateAssertion(gate),
   ];
   const contractAssertion = templateBrandContractAssertion(resolved);
   if (contractAssertion) assertions.push(contractAssertion);
-  const commercialPlanning = planCommercialParity(resolved.rawSpec || resolved.spec);
+  const commercialPlanning = planCommercialParity(specForQaScope(resolved.rawSpec || resolved.spec, resolved.excludedPages));
   const sourceLoader = createPageSourceLoader({ authCookie: args["auth-cookie"] });
   const commercialIds = new Set(commercialPlanning.pages
     .filter((page) => page?.id !== undefined && page?.id !== null)
@@ -2223,13 +2276,33 @@ async function runResolvedQa(args, resolved, { runSessionActive = false } = {})
   const pages = resolved.topologies.flatMap(topology => topology.pages);
   const pageResults = await mapConcurrent(pages, COMMERCIAL_QA_LIMITS.concurrency, page =>
     runPageChecks(page, args, { sourceLoader, bindingExpected, bindingScriptLoader, captureCommercial: commercialIds.has(String(page.page_id)) }));
+  const livePages = new Map();
   for (const [index, page] of pages.entries()) {
     const pageResult = pageResults[index];
     assertions.push(...pageResult.assertions);
+    if (pageResult.renderedRefs && !livePages.has(String(page.page_id))) {
+      livePages.set(String(page.page_id), { ...page, page_id: String(page.page_id), ...pageResult.renderedRefs });
+    }
     if (commercialIds.has(String(page.page_id)) && pageResult.commercialCapture && !capturesByPageId.has(String(page.page_id))) {
       capturesByPageId.set(String(page.page_id), pageResult.commercialCapture);
     }
   }
+  // The live campaign read (#533): one GET of {proxy-base}/api/campaign under
+  // the public campaign key, made only when a served page was read to compare;
+  // --no-live-refs sends nothing and records the check not_run (`disabled`).
+  const liveSpec = resolved.rawSpec || resolved.spec;
+  const liveRead = liveRefsDisabled(args)
+    ? disabledLiveRead()
+    : liveCampaign !== undefined || livePages.size === 0
+    ? liveCampaign
+    : await readLiveCampaignForPacket({
+      packet: resolved.packet,
+      packetPath: resolved.packetPath || null,
+      spec: liveSpec,
+      fetchImpl: liveCampaignFetch,
+      proxyBase: resolved.proxyBase,
+    });
+  assertions.push(...liveCampaignRefAssertions({ pages: [...livePages.values()], spec: liveSpec, liveCampaign: liveRead }));
   if (args.browser === true) {
     assertions.push(...await runBrowserChecks(resolved.topologies, args, {
       brandContract: resolved.brandContract,
@@ -2297,13 +2370,17 @@ async function runAnalyticsOrderSequence({ args, resolved, runId, assertions },
   } else if (analyticsLeg === "run") {
     assertions.push(...await operations.runInventory(args, analyticsContract || {}, {
       target: resolved.analyticsCaptureTarget,
+      ...analyticsCaptureScope(resolved),
     }));
   }
 
-  // Analytics parity is unchanged and remains opt-in between root inventory
-  // and typed-card receipt capture.
+  // Analytics parity remains opt-in between root inventory and typed-card
+  // receipt capture. #503: it gets the same partial-scope capture options.
   if (stringArg(args["analytics-baseline"])) {
-    assertions.push(...await operations.runParity(args, { target: resolved.analyticsCaptureTarget }));
+    assertions.push(...await operations.runParity(args, {
+      target: resolved.analyticsCaptureTarget,
+      ...analyticsCaptureScope(resolved),
+    }));
   }
 
   const result = await operations.runOrders({
@@ -2316,9 +2393,130 @@ async function runAnalyticsOrderSequence({ args, resolved, runId, assertions },
   if (analyticsLeg === "run") {
     assertions.push(operations.assessReceipt(result.receiptAnalytics, { waivers: resolved.qaWaivers }));
   }
+  applyLocalServeAnalyticsReview(assertions, resolved.localServeAnalytics);
   return result.orders;
 }
 
+// #483: local proof mode (deploy.target local-serve) renders the DEVELOPMENT
+// environment on purpose, and the starter templates gate every vendor loader
+// on it. A pixel that did not fire on that render is the render's design, not
+// the campaign's defect, so fire-dependent analytics checks become manual
+// review there instead of blockers. Only a run whose capture is actually
+// served from loopback qualifies: the same packet QA'd against the PR preview
+// (--base-url <preview>) is a production render and keeps its blockers, which
+// is the follow-up every downgraded assertion names.
+// The render itself must be on record, too: the exception applies only when
+// stages.assembly.evidence.build_environment says "development". A production
+// build served on localhost, or a build whose environment was never recorded,
+// keeps its blockers; the build-environment preflight only warns about those
+// states, so this gate cannot lean on it.
+// data-layer-purchase is deliberately not downgraded: it counts the SDK's own
+// dl_purchase, which the development render still pushes, so a miss on
+// localhost can be a real defect and keeps blocking.
+// A failure that is a capture or runner error, not "did not fire", is never
+// downgraded either: the environment gate explains a silent pixel, not an
+// unmeasured one. tag:* and oob:* are only emitted from a completed capture (a
+// failed capture is analytics-correctness:runner, which is outside this set);
+// purchase-fires names its unmeasured receipts in capture_error_plan_ids.
+const LOCAL_SERVE_ANALYTICS_REASON = "local_serve_development_render";
+const FIRE_DEPENDENT_ANALYTICS_ID = /^analytics-correctness:(?:tag:|oob:|purchase-fires(?::|$))/;
+
+function isCaptureErrorFailure(item) {
+  const evidence = item?.evidence;
+  if (evidence && typeof evidence === "object" && evidence.error_code) return true;
+  if (/^analytics-correctness:purchase-fires(?::|$)/.test(String(item?.id || ""))) {
+    // Downgrade only a Purchase reading that positively records no capture
+    // error; a missing list is an unknown, not a clean measurement.
+    const errors = evidence?.capture_error_plan_ids;
+    return !Array.isArray(errors) || errors.length > 0;
+  }
+  return false;
+}
+
+function isLoopbackUrl(value) {
+  if (typeof value !== "string" || !value.trim()) return false;
+  let hostname = null;
+  try { hostname = new URL(value).hostname; } catch { hostname = null; }
+  return !!hostname && isLoopbackHostname(hostname);
+}
+
+// #500: run-level eligibility is computed from the campaign-root URL, but the
+// page a failing check measured is not always that root. The #493 inventory
+// fallback can capture a built entry whose page.url is a remote production
+// preview, and a localhost root can redirect to a production host. So each
+// failing check is downgraded only when the page it measured is on record as
+// loopback:
+// - tag:* / oob:* — the check's own url and the inventory capture's
+//   capture_page.url (both the URL requested) AND the capture's final_url
+//   (page.url() after redirects and settling) must all be loopback;
+// - purchase-fires — every judged receipt's receipt_url (the order's final
+//   page URL, recorded before analytics settle) AND its receipt_document_url
+//   (page.url() read after the receipt analytics settled and were collected)
+//   must be loopback, and there must be one. A receipt that redirects to a
+//   hosted page during the settle window measured that host, not loopback.
+// A measured location that is missing or unparseable keeps the blocker.
+function localServeMeasuredOnLoopback(item, assertions) {
+  const id = String(item?.id || "");
+  if (/^analytics-correctness:purchase-fires(?::|$)/.test(id)) {
+    const receipts = item?.evidence?.receipts;
+    return Array.isArray(receipts) && receipts.length > 0
+      && receipts.every((receipt) => isLoopbackUrl(receipt?.receipt_url)
+        && isLoopbackUrl(receipt?.receipt_document_url));
+  }
+  const ownUrl = item?.evidence?.url ?? item?.url;
+  if (!isLoopbackUrl(ownUrl)) return false;
+  const capture = assertions.find((entry) => entry?.id === "analytics-correctness:capture" && entry.status === STATUS.PASS);
+  const capturePage = capture?.evidence?.capture_page;
+  return isLoopbackUrl(capturePage?.url) && isLoopbackUrl(capture?.evidence?.final_url);
+}
+
+function resolveLocalServeAnalytics({ packet, report, captureUrl }) {
+  if (!isLocalServePacket(packet)) return null;
+  if (!isLoopbackUrl(String(captureUrl ?? ""))) return null;
+  if (recordedBuildEnvironment(report) !== LOCAL_PROOF_BUILD_ENVIRONMENT) return null;
+  const parity = recordedProductionParity(report);
+  return {
+    deploy_target: "local-serve",
+    build_environment: { field: LOCAL_PROOF_BUILD_ENVIRONMENT_FIELD, value: LOCAL_PROOF_BUILD_ENVIRONMENT },
+    production_parity: parity
+      ? {
+          field: LOCAL_PROOF_PARITY_FIELD,
+          status: typeof parity.status === "string" ? parity.status : null,
+          checked_at: typeof parity.checked_at === "string" ? parity.checked_at : null,
+          page_count: Number.isFinite(parity.page_count) ? parity.page_count : null,
+          gated_hosts: [...new Set((Array.isArray(parity.pages) ? parity.pages : [])
+            .flatMap((page) => (Array.isArray(page?.gated_hosts) ? page.gated_hosts : []))
+            .filter((host) => typeof host === "string"))].sort(),
+        }
+      : { field: LOCAL_PROOF_PARITY_FIELD, status: "not_recorded" },
+  };
+}
+
+function applyLocalServeAnalyticsReview(assertions, localServe) {
+  if (!localServe) return;
+  const parityPassed = localServe.production_parity?.status === "pass";
+  for (const [index, item] of assertions.entries()) {
+    if (item?.status !== STATUS.FAIL || !FIRE_DEPENDENT_ANALYTICS_ID.test(String(item.id || ""))) continue;
+    if (isCaptureErrorFailure(item)) continue;
+    if (!localServeMeasuredOnLoopback(item, assertions)) continue;
+    assertions[index] = {
+      ...item,
+      status: STATUS.MANUAL_REVIEW,
+      severity: SEVERITY.WARN,
+      actual: `${item.actual ?? "did not fire"}; local-serve development render gates vendor loaders out, so re-run against the PR preview with --base-url <preview-url>`,
+      evidence: {
+        ...(item.evidence || {}),
+        reason: LOCAL_SERVE_ANALYTICS_REASON,
+        local_serve_status: STATUS.FAIL,
+        build_environment: localServe.build_environment,
+        follow_up: "Re-run qa run against the PR preview (a production render) with --base-url <preview-url>; that run gates these checks.",
+        production_parity: localServe.production_parity,
+        ...(parityPassed ? {} : { production_parity_note: "No passing page-kit parity is recorded, so nothing yet shows the production render carries these loaders." }),
+      },
+    };
+  }
+}
+
 async function finalizeQaRun({ args, resolved, runId, startedAt, assertions, testOrders, commercial = null, runSessionActive = false, browser = null }) {
   const entryUrls = deriveEntryUrls(resolved.topologies);
   const pageUrls = derivePageUrls(resolved.topologies);
@@ -2447,6 +2645,38 @@ async function finalizeQaRun({ args, resolved, runId, startedAt, assertions, tes
   };
 }
 
+// #493: a full build captures the campaign root. A partial build captures it
+// only when a built, in-scope page is served there; otherwise the root is
+// whatever the host answers (a directory index, a generic fallback) and must
+// not be measured. Either way the built entry pages (the same first in-scope
+// entry #482 selects) are the fallback when the root cannot be captured.
+// #503: "served there" is the page identity the capture leg deduplicates by
+// (isSameAnalyticsCapturePage): a query-routed page on the root's path
+// (`/campaign/?step=checkout`) is not the root, so it cannot put the root in
+// scope.
+function analyticsCaptureScope(resolved) {
+  const rootUrl = rootCaptureUrl(resolved?.analyticsCaptureTarget?.url);
+  const topologies = topologyList(resolved?.topologies);
+  const partial = topologies.some((topology) => topology?.partial_build_scope)
+    || (Array.isArray(resolved?.excludedPages) && resolved.excludedPages.length > 0);
+  const rootInScope = !rootUrl || !partial || topologies.some((topology) =>
+    (Array.isArray(topology?.pages) ? topology.pages : []).some((page) =>
+      typeof page?.url === "string" && isSameAnalyticsCapturePage(page.url, rootUrl)));
+  return {
+    rootInScope,
+    fallbackTargets: deriveEntryUrls(resolved?.topologies),
+  };
+}
+
+function rootCaptureUrl(value) {
+  if (typeof value !== "string" || !value.trim()) return null;
+  try {
+    return new URL(value).toString();
+  } catch {
+    return null;
+  }
+}
+
 const ENTRY_PAGE_TYPES = new Set([
   "entry",
   "presell",
@@ -2464,7 +2694,9 @@ function deriveEntryUrls(topologies) {
   for (const topology of topologyList(topologies)) {
     const pages = Array.isArray(topology?.pages) ? topology.pages.filter((page) => page?.url) : [];
     if (!pages.length) continue;
-    const page = pages.find(isEntryLikePage) || pages[0];
+    // #482: a partial build enters at its first in-scope page, which can be
+    // an opted-in select or checkout rather than a later landing/presell.
+    const page = topology.partial_build_scope ? pages[0] : pages.find(isEntryLikePage) || pages[0];
     entries.push({
       funnel_id: topology.funnel_id || "default",
       funnel_name: topology.funnel_name || topology.funnel_id || "default",
@@ -2558,7 +2790,10 @@ async function runPageChecks(page, args, {
   }
 
   const source = await sourceLoader(page);
-  assertions.push(bindingAssertion(page, await observeBinding({ source, page, expected: bindingExpected, scriptLoader: bindingScriptLoader })));
+  const scriptParseFailures = [];
+  assertions.push(bindingAssertion(page, await observeBinding({ source, page, expected: bindingExpected, scriptLoader: bindingScriptLoader, parseFailures: scriptParseFailures })));
+  const scriptParse = scriptParseAssertion(page, scriptParseFailures);
+  if (scriptParse) assertions.push(assertion({ ...scriptParse, page }));
   if (!source.ok) {
     const isHttpStatus = source.error_code === "http_status";
     assertions.push(assertion({
@@ -2687,7 +2922,77 @@ async function runPageChecks(page, args, {
     }));
   }
 
-  return { assertions, commercialCapture };
+  const rendered = extractRenderedRefs(html);
+  return {
+    assertions,
+    commercialCapture,
+    renderedRefs: { package_refs: [...rendered.package_refs], shipping_refs: [...rendered.shipping_refs] },
+  };
+}
+
+// The live campaign ref check (#533) as QA assertions: the comparison doctor
+// runs over built pages, run here over the served pages this attempt read,
+// under the same codes. `liveCampaign` is a readLiveCampaign result the
+// caller made; absent or failed, the check is not_run with its reason.
+function liveCampaignRefAssertions({ pages, spec, liveCampaign }) {
+  const campaignAssertion = (fields) => assertion({ family: "api-metadata", page: { page_id: "campaign" }, ...fields });
+  if (!pages.length && liveCampaign?.reason_code !== "disabled") {
+    return [campaignAssertion({
+      id: "live-campaign-refs",
+      status: STATUS.SKIPPED,
+      expected: "every served page's shipping and package refs are served by the live campaign",
+      actual: "not_run",
+      evidence: { code: LIVE_REF_CODES.notRun, reason_code: "no_pages", reason: "No served page source was read to compare against the live campaign." },
+    })];
+  }
+  const result = evaluateLiveCampaignRefs({
+    pages,
+    map: { package_refs: specPackageRefs(spec), shipping_refs: specShippingRefs(spec) },
+    live: liveCampaign,
+  });
+  const keySource = liveCampaign?.key_source ? { key_source: liveCampaign.key_source } : {};
+  if (result.status === "not_run") {
+    // --no-live-refs: the verdict says how many served pages went unchecked.
+    const eligible = result.reason_code === "disabled" ? { pages_eligible: result.checked_pages } : {};
+    return [campaignAssertion({
+      id: result.attempted ? LIVE_REF_CODES.notRun : "live-campaign-refs",
+      status: result.attempted ? STATUS.WARN : STATUS.SKIPPED,
+      ...(result.attempted ? { severity: SEVERITY.WARN } : {}),
+      expected: "every served page's shipping and package refs are served by the live campaign",
+      actual: "not_run",
+      evidence: { code: LIVE_REF_CODES.notRun, reason_code: result.reason_code, reason: result.attempted ? liveRefsNotRunMessage(result) : result.reason, ...eligible, ...keySource },
+    })];
+  }
+  const out = result.page_findings.map((finding) => assertion({
+    id: `${finding.code}:${finding.page_id}`,
+    family: "api-metadata",
+    page: pages.find((page) => String(page.page_id) === finding.page_id) || { page_id: finding.page_id },
+    status: STATUS.FAIL,
+    severity: SEVERITY.BLOCKER,
+    expected: `every rendered ${finding.kind} ref is served by the live campaign`,
+    actual: finding.refs.join(", "),
+    evidence: { code: finding.code, refs: finding.refs, message: liveRefFindingMessage(finding) },
+  }));
+  if (result.drift) {
+    out.push(campaignAssertion({
+      id: LIVE_REF_CODES.drift,
+      status: STATUS.WARN,
+      severity: SEVERITY.WARN,
+      expected: "the CampaignSpec lists the refs the live campaign serves",
+      actual: "drift",
+      evidence: { code: LIVE_REF_CODES.drift, drift: result.drift, message: campaignDriftMessage(result.drift) },
+    }));
+  }
+  if (result.status === "pass") {
+    out.push(campaignAssertion({
+      id: "live-campaign-refs",
+      status: STATUS.PASS,
+      expected: "every served page's shipping and package refs are served by the live campaign",
+      actual: `${result.checked_pages} page(s) checked`,
+      evidence: { ...keySource },
+    }));
+  }
+  return out;
 }
 
 async function maybeRunTestOrders(
@@ -2702,6 +3007,12 @@ async function maybeRunTestOrders(
   const mode = String(args["test-order"] || "off").toLowerCase();
   const legacyMode = String(args["legacy-api-test-order"] || "off").toLowerCase();
   const emptyReceiptAnalytics = () => ({ plannedPlanIds: [], attempts: [] });
+  if (!mode || mode === "off") {
+    // No browser order clicks an upsell control, legacy API orders included,
+    // so the coverage row says so instead of going missing (#530).
+    const coverage = upsellActionCoverageWithoutOrders(resolved.topologies);
+    if (coverage) assertions.push(coverage);
+  }
   if ((!mode || mode === "off") && (!legacyMode || legacyMode === "off")) {
     return { orders: [], receiptAnalytics: emptyReceiptAnalytics() };
   }
@@ -2728,15 +3039,12 @@ async function maybeRunLegacyApiTestOrders({ args, resolved, runId, assertions }
   const apiKey = stringArg(args["api-key"]) || process.env.QA_CAMPAIGNS_API_KEY;
   const apiBase = stringArg(args["campaigns-api-base"]) || process.env.CAMPAIGNS_API_BASE;
   if (!apiKey || !apiBase) throw new Error("Legacy direct API test orders require --api-key/QA_CAMPAIGNS_API_KEY and --campaigns-api-base/CAMPAIGNS_API_BASE.");
-  const cart = parseCart(args.cart);
-  if (!cart.length) throw new Error("--test-order requires --cart package_id:quantity pairs.");
+  const { cart, paths } = legacyTestOrderInputs(args);
   const checkout = findPage(resolved.topologies, "checkout");
   if (!checkout?.url) throw new Error("--test-order requires a checkout page URL.");
   const upsell = findPage(resolved.topologies, "upsell");
-  const paths = mode === "both" ? ["accept", "decline"] : [mode];
   const orders = [];
   for (const path of paths) {
-    if (!["accept", "decline"].includes(path)) throw new Error(`Unknown --test-order mode: ${mode}`);
     const create = await createTestOrder({ apiBase, apiKey, cart, runId, successUrl: checkout.expected_next_url || upsell?.url || checkout.url, spec: resolved.spec, args });
     const verification = { expected_line_count: cart.length, actual_line_count: 0, diff: [], verified: false };
     if (!create.ok) {
@@ -3604,6 +3912,14 @@ function decodeHtml(value) {
     .replace(/&gt;/g, ">");
 }
 
+function legacyTestOrderInputs(args) {
+  const cart = typeof args.cart === "string" ? parseCart(args.cart) : [];
+  if (!cart.length) throw new Error("--test-order requires --cart package_id:quantity pairs.");
+  const mode = String(args["test-order"] || "off").toLowerCase();
+  if (!["accept", "decline", "both"].includes(mode)) throw new Error(`Unknown --test-order mode: ${mode}`);
+  return { cart, paths: mode === "both" ? ["accept", "decline"] : [mode] };
+}
+
 function parseCart(value) {
   if (!value) return [];
   return String(value).split(",").map((part) => {
@@ -3649,6 +3965,9 @@ export const __qaNodeTestHooks = Object.freeze({
   resolveQaInputs,
   runResolvedQa,
   runPageChecks,
+  analyticsCaptureScope,
+  resolveLocalServeAnalytics,
+  applyLocalServeAnalyticsReview,
   analyticsCorrectnessLegDecision,
   analyticsCorrectnessDisabledAssertion,
   runAnalyticsOrderSequence,
@@ -3683,6 +4002,7 @@ export const __qaNodeTestHooks = Object.freeze({
   isRoutingMetaTag,
   unsupportedSdkMetaHint,
   reportCommercialRunnerError,
+  liveCampaignRefAssertions,
   browserSkippedByGate,
   reportBrowserSkippedByGate,
   gateClearingHint,