@nextcommerce/campaigns-os 1.43.2 → 1.46.0

package/src/qa-commercial-parity.mjs

@@ -11,7 +11,10 @@ import {
   CommercialParityLimitError,
   createCommercialParityReport,
   extractCommercialClaims,
+  recurringClaimAbsences,
+  recurringClaimAbsentAssertions,
 } from "./commercial-parity.mjs";
+import { extractRenderedPackageRefs } from "./live-campaign-refs.mjs";
 
 export const COMMERCIAL_QA_LIMITS = Object.freeze({
   max_html_bytes: 2 * 1024 * 1024,
@@ -171,10 +174,15 @@ function captureFailure(page, code, error) {
 
 export function captureCommercialClaims(page, html) {
   try {
-    return extractCommercialClaims(html, {
-      pageId: present(page?.page_id) ? String(page.page_id) : null,
-      url: page?.url,
-    });
+    return {
+      ...extractCommercialClaims(html, {
+        pageId: present(page?.page_id) ? String(page.page_id) : null,
+        url: page?.url,
+      }),
+      // Every package the page renders, by the refs doctor reads, so a
+      // subscription whose rebill copy yielded no claim is still seen (#533).
+      rendered_package_refs: [...extractRenderedPackageRefs(html)],
+    };
   } catch (error) {
     const code = error instanceof CommercialParityLimitError
       ? error.code
@@ -398,6 +406,29 @@ export function planCommercialParity(spec, { maxScenarios = COMMERCIAL_QA_LIMITS
   };
 }
 
+// A package recurs when the spec says so, or carries a recurring price and a
+// cadence. Page rows override the campaign catalog per ref, as the journey does.
+function isSubscriptionPackage(pkg) {
+  return pkg?.is_recurring === true
+    || (present(pkg?.price_recurring) && (present(pkg?.interval_count) || present(pkg?.interval)));
+}
+
+export function subscriptionPackageRefsByPage(spec, pages) {
+  const packageRef = (pkg) => (present(pkg?.ref_id) ? String(pkg.ref_id) : present(pkg?.package_id) ? String(pkg.package_id) : null);
+  const catalog = new Map(array(spec?.packages).map((pkg) => [packageRef(pkg), pkg]).filter(([ref]) => ref));
+  const byPage = new Map();
+  array(pages).forEach((page) => {
+    if (!present(page?.id)) return;
+    const refs = new Set();
+    array(page.packages).forEach((pkg) => {
+      const ref = packageRef(pkg);
+      if (ref && isSubscriptionPackage({ ...(catalog.get(ref) || {}), ...pkg })) refs.add(ref);
+    });
+    if (refs.size) byPage.set(String(page.id), refs);
+  });
+  return byPage;
+}
+
 function countBy(values, keyFor) {
   const counts = {};
   values.forEach((value) => {
@@ -473,6 +504,7 @@ function compactReport(report, journey, plan, executed, issues, observedClaims,
     unresolved_voucher_claims: report.unresolved_voucher_claims,
     serialized_assertion_count: report.serialized_assertion_count,
     omitted_assertion_count: report.omitted_assertion_count,
+    recurring_claim_absences: array(report.recurring_claim_absences),
     observed_claims: observedClaims,
     claim_limit: claimLimit,
     finding_count: report.findings.length,
@@ -539,6 +571,7 @@ export function unavailableCommercialReport(code, { status = "not_run" } = {}) {
     unresolved_voucher_claims: 0,
     serialized_assertion_count: 0,
     omitted_assertion_count: 0,
+    recurring_claim_absences: [],
     observed_claims: 0,
     claim_limit: COMMERCIAL_QA_LIMITS.max_aggregate_claims,
     finding_count: 0,
@@ -625,8 +658,18 @@ export async function runCommercialParity({
     maxAssertions,
     countsOnly: aggregateClaimOverflow,
   });
+  // Subscription packages a page renders with no recurring claim read for
+  // them: incomplete evidence (an issue), and a warning naming the package.
+  const absences = aggregateClaimOverflow
+    ? []
+    : recurringClaimAbsences(captures, subscriptionPackageRefsByPage(planningSpec, commercialPlanning.pages));
+  absences.forEach(() => issues.push({ code: "recurring_claim_absent" }));
+  const absentAssertions = recurringClaimAbsentAssertions(absences, {
+    maxAssertions: Math.max(0, maxAssertions - parity.assertions.length),
+  });
+  parity.recurring_claim_absences = absences;
   return {
-    assertions: parity.assertions,
+    assertions: [...parity.assertions, ...absentAssertions],
     commercial: compactReport(
       parity,
       parityJourney,

package/src/qa-node.mjs

@@ -30,7 +30,7 @@ const PACKAGE_ROOT = installModeResolve(installModeDirname(installModeFileUrl(im
 function cmd(verb, rest = "") {
   return `${invocationPrefixFor(PACKAGE_ROOT)} ${verb}${rest ? ` ${rest}` : ""}`;
 }
-import { isSameAnalyticsCapturePage, 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";
@@ -98,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
@@ -110,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
@@ -130,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.
@@ -166,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
@@ -178,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
@@ -2165,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;
@@ -2258,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,
@@ -2884,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(
@@ -2899,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() };
   }
@@ -3888,6 +4002,7 @@ export const __qaNodeTestHooks = Object.freeze({
   isRoutingMetaTag,
   unsupportedSdkMetaHint,
   reportCommercialRunnerError,
+  liveCampaignRefAssertions,
   browserSkippedByGate,
   reportBrowserSkippedByGate,
   gateClearingHint,

package/src/qa-test-order-topology.mjs

@@ -30,6 +30,19 @@ export function resolveTestOrderTopology(topology = {}, checkoutPage = null) {
     ...(entry?.kind === "terminal" ? [entry.terminal] : []),
     ...terminalPaths.map((candidate) => candidate.terminal),
   ]);
+  // Every declared offer page with the offer page each action leads to, so a
+  // planned path that stops short of a terminal can still be walked to the
+  // controls it clicks.
+  const offerEdges = [];
+  for (const [key, page] of pagesByUrl) {
+    if (!OFFER_PAGE_TYPES.has(pageType(page))) continue;
+    const edge = { key, page_id: page.page_id || null, page_type: page.page_type || null, url: page.url };
+    for (const [action, field] of ACTIONS) {
+      const target = targetNode(page?.[field], pagesByUrl, topologyOrigin);
+      edge[`${action}_key`] = target?.kind === "offer" ? canonicalHttpUrl(target.page.url) : null;
+    }
+    offerEdges.push(edge);
+  }
 
   return {
     topology_id: topology?.funnel_id || "default",
@@ -48,6 +61,8 @@ export function resolveTestOrderTopology(topology = {}, checkoutPage = null) {
     terminal_paths: terminalPaths,
     invalid_paths: invalidPaths,
     recognized_terminals: recognizedTerminals,
+    entry_offer_key: entry?.kind === "offer" ? canonicalHttpUrl(entry.page.url) : null,
+    offer_edges: offerEdges,
   };
 }
 
@@ -95,6 +110,139 @@ export function commonTestOrderPaths(resolvedTopology) {
   return paths;
 }
 
+// The default `common` depth (#530). The sample above never reached a
+// downsell's decline, so a broken decline link passed QA. When every actual
+// terminal path fits under the cap, `common` runs them all. Above the cap it
+// keeps the sample and adds, for each offer page whose decline no planned path
+// clicks yet, the shortest path that clicks it, until the cap is reached. A
+// page counts as covered only when its decline is clicked: arriving at it, or
+// clicking its accept, does not. Pages still uncovered are returned, not
+// dropped. The sample is never trimmed, so a cap below it is still refused by
+// the flood guard exactly as before.
+export function commonTestOrderPlan(resolvedTopology, { cap } = {}) {
+  const baseline = commonTestOrderPaths(resolvedTopology);
+  let full = null;
+  try {
+    full = fullTestOrderPaths(resolvedTopology);
+  } catch {
+    full = null;
+  }
+  const plan = {
+    requested_depth: "common",
+    cap,
+    full_path_count: full ? full.length : null,
+    baseline_paths: baseline,
+  };
+  if (full && full.length <= cap) {
+    // Same set as `full`; the sample's paths keep their place at the front.
+    const paths = [...baseline.filter((path) => full.includes(path)), ...full.filter((path) => !baseline.includes(path))];
+    return { ...plan, effective_depth: "full", reason: "under_cap", paths, coverage_paths: [], uncovered_pages: [] };
+  }
+
+  const paths = baseline.slice();
+  const coveragePaths = [];
+  const offers = offerPagesByReach(resolvedTopology);
+  for (const offer of offers) {
+    if (paths.length >= cap) break;
+    const declined = declinedOfferKeys(resolvedTopology, paths);
+    if (declined.has(offer.key) || !offer.reach) continue;
+    const candidate = shortestDeclinePath(resolvedTopology, offer, declined);
+    if (!candidate || paths.includes(candidate)) continue;
+    paths.push(candidate);
+    coveragePaths.push(candidate);
+  }
+  const declined = declinedOfferKeys(resolvedTopology, paths);
+  const uncovered = offers
+    .filter((offer) => !declined.has(offer.key))
+    .map((offer) => ({
+      page_id: offer.page_id,
+      page_type: offer.page_type,
+      reason: offer.reach ? "cap" : "unreachable",
+    }));
+  return {
+    ...plan,
+    effective_depth: "common",
+    reason: full ? "over_cap" : "full_not_enumerable",
+    paths,
+    coverage_paths: coveragePaths,
+    uncovered_pages: uncovered,
+  };
+}
+
+// The offer pages a planned path clicks, in click order: `checkout` clicks
+// none, `decline-accept` clicks the entry offer's decline and then the accept
+// on whichever offer that decline leads to. A walk stops where the topology
+// leaves the offer graph, as the runner does.
+export function testOrderPathClicks(resolvedTopology, path) {
+  const normalized = String(path || "").toLowerCase();
+  const steps = !normalized || normalized === "checkout" ? [] : normalized.split("-");
+  const edges = new Map((resolvedTopology?.offer_edges || []).map((edge) => [edge.key, edge]));
+  const clicks = [];
+  let current = edges.get(resolvedTopology?.entry_offer_key) || null;
+  for (const step of steps) {
+    if (!current) break;
+    clicks.push({ key: current.key, page_id: current.page_id, action: step });
+    current = edges.get(current[`${step}_key`]) || null;
+  }
+  return clicks;
+}
+
+function declinedOfferKeys(resolvedTopology, paths) {
+  const keys = new Set();
+  for (const path of paths) {
+    for (const click of testOrderPathClicks(resolvedTopology, path)) {
+      if (click.action === "decline") keys.add(click.key);
+    }
+  }
+  return keys;
+}
+
+// Declared offer pages, shallowest first, each with the shortest action
+// sequence that reaches it (accept before decline on a tie) or null when no
+// path from the checkout reaches it.
+function offerPagesByReach(resolvedTopology) {
+  const edges = resolvedTopology?.offer_edges || [];
+  const byKey = new Map(edges.map((edge) => [edge.key, edge]));
+  const reach = new Map();
+  const entry = resolvedTopology?.entry_offer_key;
+  if (entry && byKey.has(entry)) {
+    reach.set(entry, []);
+    const queue = [entry];
+    while (queue.length) {
+      const key = queue.shift();
+      for (const action of ["accept", "decline"]) {
+        const next = byKey.get(key)?.[`${action}_key`];
+        if (!next || reach.has(next) || !byKey.has(next)) continue;
+        reach.set(next, [...reach.get(key), action]);
+        queue.push(next);
+      }
+    }
+  }
+  const reached = [...reach.keys()].map((key) => ({ ...byKey.get(key), reach: reach.get(key) }));
+  const unreached = edges.filter((edge) => !reach.has(edge.key)).map((edge) => ({ ...edge, reach: null }));
+  return [...reached, ...unreached];
+}
+
+// The shortest actual terminal path that clicks this offer's decline. Among
+// equally short paths, the one that also clicks the most still-undeclined
+// offers wins, then accept before decline. Where no terminal path clicks it
+// (the graph beyond is not enumerable), the path that reaches the offer and
+// declines it.
+function shortestDeclinePath(resolvedTopology, offer, declined) {
+  const newlyDeclined = (path) => new Set(testOrderPathClicks(resolvedTopology, path)
+    .filter((click) => click.action === "decline" && !declined.has(click.key))
+    .map((click) => click.key)).size;
+  const candidates = (resolvedTopology?.terminal_paths || [])
+    .filter((candidate) => testOrderPathClicks(resolvedTopology, candidate.path)
+      .some((click) => click.key === offer.key && click.action === "decline"))
+    .map((candidate) => ({ ...candidate, gain: newlyDeclined(candidate.path) }))
+    .sort((left, right) => (left.steps.length - right.steps.length)
+      || (right.gain - left.gain)
+      || compareActionSteps(left.steps, right.steps));
+  if (candidates.length) return candidates[0].path;
+  return [...offer.reach, "decline"].join("-");
+}
+
 function compareCommonReceiptPaths(left, right) {
   const lengthDelta = (left?.steps?.length || 0) - (right?.steps?.length || 0);
   if (lengthDelta) return lengthDelta;

package/src/sdk-markup.mjs

@@ -2,12 +2,12 @@
 //
 // `built_output.upsell_selector_scope` catches one shape of built markup that
 // the Campaign Cart SDK binds without complaint and that then does the wrong
-// thing to a shopper. This module is the rest of that family: six more
+// thing to a shopper. This module is the rest of that family: seven more
 // shapes, each a static read of built HTML, each producing either a silent
 // no-op (the shopper fills a field that never reaches the order; a button
 // that never enables) or a double cart write. A partner agency's Campaign
-// Cart skill kit listed them as stable lint codes; the codes are kept so the
-// two vocabularies line up.
+// Cart skill kit listed the first six as stable lint codes; the codes are
+// kept so the two vocabularies line up. ORPHANED_UPSELL_ACTION is ours.
 //
 //   Blockers (not waivable — the markup provably does not do what it says)
 //   SWAP_WITH_ADD_TO_CART      a bundle selector in swap mode (explicit, or
@@ -26,6 +26,12 @@
 //   MISSING_SELECTOR_ID_MATCH  an add-to-cart button whose data-next-selector-id
 //                              names no selector on the page. The button waits
 //                              for a selection that can never arrive.
+//   ORPHANED_UPSELL_ACTION     data-next-upsell-action with no ancestor carrying
+//                              data-next-upsell (#529). The upsell enhancer
+//                              binds only the actions inside its container; an
+//                              action outside it is a plain link, so a "No
+//                              thanks" goes nowhere and the shopper is stuck.
+//                              Every page type, not only upsell pages.
 //
 //   Warnings (advisory)
 //   DOUBLE_SELECTED            more than one data-next-selected="true" card in
@@ -34,6 +40,12 @@
 //   TEMPLATE_DOUBLE_BRACE      `{{` inside an SDK-owned <template>. SDK tokens
 //                              are single-brace and conditions are no-brace;
 //                              a double brace renders literally.
+//   CHECKOUT_BUMP_IS_UPSELL    data-next-is-upsell="true" on a checkout page
+//                              (#535). A checkout bump is a pre-purchase
+//                              add-on; the flag puts it on the initial order
+//                              as an upsell line. The page type is a live,
+//                              unambiguous next-page-type meta, since it is
+//                              what the SDK reads; otherwise the route type.
 //
 //   Info (advisory, one note per campaign, no code)
 //   unknown_attributes[]       a data-next-* name the pinned SDK's attribute
@@ -43,10 +55,11 @@
 //                              own data-next-* hooks, which is why it informs
 //                              rather than warns.
 //
-// Parsed with parse5 rather than regex because four of the six turn on
-// containment (a card inside a selector, a field inside a form, a template's
-// content), and HTML nesting is not a regular language. Template content is
-// walked too: the SDK clones it into the live DOM.
+// Parsed with parse5 rather than regex because five of the seven turn on
+// containment (a card inside a selector, a field inside a form, an action
+// inside its upsell container, a template's content), and HTML nesting is not
+// a regular language. Template content is walked too: the SDK clones it into
+// the live DOM.
 //
 // Pure: callers hand in built HTML. Both doctor entry points drive it.
 
@@ -57,6 +70,9 @@ import {
   isIndexedSdkAttribute,
   isKnownCheckoutFieldName,
 } from "./sdk-attribute-index.mjs";
+import { builtPageTypeMeta } from "./upsell-selector-scope.mjs";
+
+const normalizedPageTypeValue = (type) => (type == null ? null : String(type).trim().toLowerCase());
 
 export const SDK_MARKUP = "built_output.sdk_markup";
 
@@ -65,8 +81,10 @@ export const SDK_MARKUP_CODES = Object.freeze({
   CHECKOUT_NOT_FORM: { code: `${SDK_MARKUP}.checkout_not_form`, severity: "error" },
   WRONG_FIELD_NAME: { code: `${SDK_MARKUP}.wrong_field_name`, severity: "error" },
   MISSING_SELECTOR_ID_MATCH: { code: `${SDK_MARKUP}.missing_selector_id_match`, severity: "error" },
+  ORPHANED_UPSELL_ACTION: { code: `${SDK_MARKUP}.orphaned_upsell_action`, severity: "error" },
   DOUBLE_SELECTED: { code: `${SDK_MARKUP}.double_selected`, severity: "warning" },
   TEMPLATE_DOUBLE_BRACE: { code: `${SDK_MARKUP}.template_double_brace`, severity: "warning" },
+  CHECKOUT_BUMP_IS_UPSELL: { code: `${SDK_MARKUP}.checkout_bump_is_upsell`, severity: "warning" },
   // Unknown data-next-* names are not a finding and carry no code: they are
   // information on the gate (unknown_attributes[]) and one advisory ready line.
 });
@@ -142,11 +160,22 @@ function describe(entry) {
   return `${bits.join("")}>`;
 }
 
+function describeBump(entry) {
+  const id = entry.attrs.get("id");
+  const packageId = entry.attrs.get("data-next-package-id");
+  const bits = [`<${entry.tag}`];
+  if (id) bits.push(` id="${id}"`);
+  if (packageId) bits.push(` data-next-package-id="${packageId}"`);
+  return `${bits.join("")}>`;
+}
+
 /**
  * Scan one built page. Returns findings with { code_name, code, severity,
  * page_id, file, message, detail } and the set of unknown data-next-* names.
+ * `page_type` is the route-inferred type, used only when the page declares no
+ * live, unambiguous next-page-type meta (builtPageTypeMeta).
  */
-export function scanPageMarkup({ page_id, file = null, content = "" }) {
+export function scanPageMarkup({ page_id, file = null, content = "", page_type = null }) {
   const document = parse(String(content || ""));
   const where = file || page_id;
   const findings = [];
@@ -157,10 +186,13 @@ export function scanPageMarkup({ page_id, file = null, content = "" }) {
   const selectorIds = new Set(); // ids of elements that are themselves a selector
   const templates = []; // { entry, sdkOwned }
   const referencedTemplateIds = new Set();
+  const upsellFlagged = []; // entries carrying data-next-is-upsell="true"
 
   walkElements(document, (entry) => {
     const { tag, attrs: a, ancestors } = entry;
 
+    if ((a.get("data-next-is-upsell") || "").trim().toLowerCase() === "true") upsellFlagged.push(entry);
+
     for (const [name] of a) {
       if (name.startsWith("data-next-") && !isIndexedSdkAttribute(name)) unknown.add(name);
       if (TEMPLATE_ID_ATTRIBUTES.test(name) && a.get(name)) referencedTemplateIds.add(a.get(name).trim());
@@ -181,6 +213,18 @@ export function scanPageMarkup({ page_id, file = null, content = "" }) {
       }
     }
 
+    // An ancestor, not the element itself: the enhancer looks for actions
+    // inside the container it binds.
+    if (a.has("data-next-upsell-action") && !ancestors.some((anc) => anc.attrs.has("data-next-upsell"))) {
+      const value = a.get("data-next-upsell-action") ?? "";
+      // The SDK reads add/accept as accepting the offer and skip/decline as
+      // declining it; any other value does nothing even inside a container.
+      const verb = { add: "accept", accept: "accept", skip: "decline", decline: "decline" }[value.trim().toLowerCase()] || "act on";
+      findings.push(finding("ORPHANED_UPSELL_ACTION", page_id, where,
+        `${describe(entry)} data-next-upsell-action="${value}" on ${where} has no ancestor carrying data-next-upsell. The SDK binds upsell actions only inside that container, so this one never fires and the shopper cannot ${verb} the offer. Move it inside the data-next-upsell container it belongs to.`,
+        { tag, action: value }));
+    }
+
     const action = (a.get("data-next-action") || "").trim().toLowerCase();
     if (action === "add-to-cart") {
       addToCartButtons.push({ entry, selectorId: (a.get("data-next-selector-id") || "").trim() || null });
@@ -263,6 +307,26 @@ export function scanPageMarkup({ page_id, file = null, content = "" }) {
       { template_id: id || null, snippet }));
   }
 
+  // One finding per page, naming every flagged element: the repair is the
+  // same for each (drop the flag from the bump include's markup; several
+  // starter includes write it unconditionally, so an is_upsell=false argument
+  // does not always clear it).
+  // The page type is read only when a flag is present, so a page without one
+  // is not parsed a second time.
+  const pageTypeMeta = upsellFlagged.length ? builtPageTypeMeta(content) : null;
+  // The live, unambiguous meta wins because it is what the SDK reads; the
+  // upsell gate's narrower oto-route rule (builtPageTypeOverRouteGuess) does
+  // not apply to a checkout bump.
+  const effectivePageType = upsellFlagged.length
+    ? normalizedPageTypeValue(pageTypeMeta ?? page_type)
+    : null;
+  if (effectivePageType === "checkout") {
+    const elements = upsellFlagged.map(describeBump);
+    findings.push(finding("CHECKOUT_BUMP_IS_UPSELL", page_id, where,
+      `${elements.length > 1 ? `${elements.length} order bumps` : "An order bump"} on checkout page ${where} (${elements.join(", ")}) ${elements.length > 1 ? "carry" : "carries"} data-next-is-upsell="true". A checkout bump is a pre-purchase add-on; the flag puts it on the initial order as an upsell line. The flag comes from the bump include's markup, and several starter bump includes write it unconditionally, so remove data-next-is-upsell="true" from the include in this campaign unless the line really should be billed as an upsell.`,
+      { page_type: effectivePageType, page_type_source: pageTypeMeta !== null ? "next-page-type" : "route", elements }));
+  }
+
   return { page_id, file, findings, unknown_attributes: [...unknown].sort() };
 }