@nextcommerce/campaigns-os 1.43.2 → 1.47.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
@@ -35,6 +41,11 @@
 //                              are single-brace and conditions are no-brace;
 //                              a double brace renders literally.
 //
+//   Not a finding: data-next-is-upsell="true" on a checkout order bump. The
+//   selected bump is a line item on the checkout order, tagged as an upsell so
+//   order reports show it apart from core items. That is the intended default;
+//   a bump include opts out with is_upsell: false.
+//
 //   Info (advisory, one note per campaign, no code)
 //   unknown_attributes[]       a data-next-* name the pinned SDK's attribute
 //                              index does not list. Catches an invented
@@ -43,10 +54,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.
 
@@ -65,6 +77,7 @@ 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" },
   // Unknown data-next-* names are not a finding and carry no code: they are
@@ -181,6 +194,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 });

package/src/sdk-storage-compatibility.mjs

@@ -57,8 +57,9 @@ export function readStorageManifest(path) {
   version(value.sdkVersion);
   version(value.supportedSdkVersions?.min);
   version(value.supportedSdkVersions?.max);
-  if (compare(value.sdkVersion, value.supportedSdkVersions.max) !== 0)
-    throw new Error('Manifest source SDK version must equal supported maximum.');
+  // A release manifest may describe a supported range ending below its own release; it cannot vouch past itself.
+  if (compare(value.sdkVersion, value.supportedSdkVersions.max) < 0)
+    throw new Error('Manifest source SDK version is below its supported maximum.');
   const unique = new Set();
   if (compare(value.supportedSdkVersions.min, value.supportedSdkVersions.max) > 0)
     throw new Error('Invalid manifest version range.');