@nextcommerce/campaigns-os 1.53.0 → 1.55.0

package/src/qa-cart-entry.mjs

@@ -70,12 +70,21 @@ export const CART_ENTRY_ROUTE_ATTRIBUTE = "data-next-url";
 // preventDefault() unconditionally, so its href never navigates, and it
 // resolves the attribute against the origin (campaign-cart url-utils), not the
 // document base. Without the attribute such a control adds to the cart and
-// stays put — no route. Anywhere else the SDK attribute has no navigation
+// stays put — no route. A control matching one of `declaredRoutes` (each
+// `{ selector, url }`, a route the page declares rather than one the control
+// carries: the SDK checkout form's submit button and an upsell's accept /
+// decline actions) goes to that url and nothing else, because the SDK
+// handles the submission or the click itself, so an href="#" or the form's
+// action never navigates. Anywhere else the SDK attribute has no navigation
 // semantics: an HTML anchor's own resolved href (native, so a <base href> is
 // honoured), then an href attribute, then `data-href`, then a wrapping form's
-// action. Only spellings with real navigation semantics count — an attribute
-// the SDK does not declare is not a route.
-export function cartEntryHrefFor(element, { cartEntrySelector, cartEntryRouteAttribute, origin, baseHref }) {
+// action — for that form's submit button only, and never inside a form
+// matching `checkoutFormSelector`: the SDK checkout form, which the SDK
+// submits itself, or, on a checkout or upsell / downsell page, every form,
+// since there the only form-borne route is the one in `declaredRoutes`. Only
+// spellings with real navigation semantics count — an attribute the SDK does
+// not declare is not a route.
+export function cartEntryHrefFor(element, { cartEntrySelector, cartEntryRouteAttribute, declaredRoutes = [], checkoutFormSelector = null, origin, baseHref }) {
   if (!element || typeof element.getAttribute !== "function") return null;
   if (typeof element.matches === "function" && element.matches(cartEntrySelector)) {
     const sdkRoute = String(element.getAttribute(cartEntryRouteAttribute) || "").trim();
@@ -88,12 +97,26 @@ export function cartEntryHrefFor(element, { cartEntrySelector, cartEntryRouteAtt
       return null;
     }
   }
+  const declared = typeof element.matches === "function"
+    ? (declaredRoutes || []).find((route) => route?.selector && element.matches(route.selector))
+    : null;
+  if (declared) {
+    try {
+      return new URL(declared.url, baseHref).href;
+    } catch {
+      return null;
+    }
+  }
   // An HTML anchor resolves its own href (an SVG <a> exposes an object, not a
   // string, and falls through to the attribute reading).
-  if (String(element.tagName || "").toUpperCase() === "A" && typeof element.href === "string" && element.href) return element.href;
+  const tag = String(element.tagName || "").toUpperCase();
+  if (tag === "A" && typeof element.href === "string" && element.href) return element.href;
+  // The reflected type, so a <button> with no type attribute submits too.
+  const submits = (tag === "BUTTON" || tag === "INPUT") && String(element.type || "").toLowerCase() === "submit";
+  const insideRoutelessForm = Boolean(checkoutFormSelector) && typeof element.closest === "function" && Boolean(element.closest(checkoutFormSelector));
   const attr = element.getAttribute("href")
     || element.getAttribute("data-href")
-    || (typeof element.closest === "function" ? element.closest("form")?.getAttribute("action") : null);
+    || (submits && !insideRoutelessForm && typeof element.closest === "function" ? element.closest("form")?.getAttribute("action") : null);
   if (!attr) return null;
   try {
     return new URL(attr, baseHref).href;

package/src/qa-node.mjs

@@ -32,7 +32,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, upsellActionCoverageWithoutOrders, validatedOrderCreationLimit } from "./qa-browser.mjs";
+import { QA_RUN_CURRENCY, isSameAnalyticsCapturePage, runAnalyticsCorrectnessChecks, runAnalyticsParityChecks, runBrowserChecks, runBrowserTestOrders, testEmail, UPSELL_ACTION_SPELLINGS, upsellActionCoverageWithoutOrders, validatedOrderCreationLimit } from "./qa-browser.mjs";
 import { assessReceiptPurchase } from "./qa-analytics-correctness.mjs";
 import { trackingQaAssertion, trackingRunScopeRows } from "./qa-tracking-params.mjs";
 import { contentParamNotRequestedRows, contentParamQaAssertion } from "./qa-content-params.mjs";
@@ -128,7 +128,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] [--no-live-refs] [--json]
+  campaigns-os qa run --packet <campaign-runtime.build.json> [--base-url <url>] [--currency <code>] [--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
@@ -168,7 +168,9 @@ Options:
                                   qa publish reads the same directory when looking up the sidecar's run.
   --post-verdict                  (default) Publish the verdict to the QA portal at
                                   <proxy-base>/api/qa/verdicts and print the QA portal link.
-                                  Publishing is automatic; this flag is retained for clarity.
+                                  Publishing is automatic, except for a run whose base URL is a local
+                                  address (localhost, *.localhost, 127.x.x.x, 0.0.0.0, [::1], an IPv4-mapped loopback): that verdict stays local unless
+                                  this flag is passed.
   --no-post-verdict, --local-only Skip publishing; write only the local verdict copy (offline / dev / CI).
                                   Publish it later, without a re-run, with qa publish.
   --verdict <path>                qa promote / qa publish: the full verdict file under qa-output/. qa publish
@@ -187,6 +189,10 @@ Options:
   --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.
+  --currency <code>               qa run: enter each funnel's entry page with ?currency=<CODE> (three letters, e.g. GBP),
+                                  keeping its existing query. The flag takes one code per run (given twice, the
+                                  last one is used); the verdict records it as evidence.currency on the entry
+                                  page's http:<page> row. Not supported by qa parity or --legacy-api-test-order.
   --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
@@ -197,8 +203,9 @@ Options:
   --browser-timeout <ms>          Browser navigation timeout. Default: 30000.
   --test-order <off|common|checkout|accept|decline|both|full|tiers[:checkout|common|full]|accept-decline[-accept...]>
                                   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 cards bypass the gateway and create no transactions, but each creates a real
+                                  store order record. Unless the operator has already said test orders are fine for this campaign, ask once, up front, before placing orders.
+                                  No permission flag or packet policy is needed. Default mode (bare
                                   --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
@@ -1859,7 +1866,7 @@ function updateQaPolicy(args) {
   // the packet and before the packet write: refusals, so they journal nothing.
   const removedFlags = REMOVED_QA_POLICY_FLAGS.filter((flag) => flag in args);
   if (removedFlags.length) {
-    throw refused(`qa policy set: ${removedFlags.map((flag) => `--${flag}`).join(" and ")} ${removedFlags.length > 1 ? "were" : "was"} removed in supported surface 1.28.0 (test orders run from --test-order <mode> alone; there is no permission flag). Drop the flag${removedFlags.length > 1 ? "s" : ""}. Accepted: --allowed-domains-confirmed, --deploy-target, --preview-url, --production-url, --order-path-depth.`);
+    throw refused(`qa policy set: ${removedFlags.map((flag) => `--${flag}`).join(" and ")} ${removedFlags.length > 1 ? "were" : "was"} removed in supported surface 1.28.0 (test orders use --test-order <mode>, with no permission flag; unless the operator has already said test orders are fine for this campaign, ask once, up front, before placing these real store order records). Drop the flag${removedFlags.length > 1 ? "s" : ""}. Accepted: --allowed-domains-confirmed, --deploy-target, --preview-url, --production-url, --order-path-depth.`);
   }
   // Validated with the other argv checks, before anything is written: a
   // refusal at this call site, like the removed-flag check above.
@@ -2134,11 +2141,34 @@ function parityReplayEvidence(bundle) {
 // validator's own.
 const refuseBadOrderCreationLimit = (args) => refusing(() => validatedOrderCreationLimit(args));
 
+// `qa run --currency <code>`: one run proves one currency. The code is three
+// ASCII letters, upper-cased; anything else (no value, a list, a symbol) is
+// refused here, before anything is resolved, fetched or launched. So is a run
+// whose orders are legacy direct API orders: that request carries no
+// currency, so the order would be placed in the default one.
+function qaRunCurrency(args) {
+  if (!Object.hasOwn(args, "currency")) return null;
+  const value = args.currency;
+  if (typeof value !== "string" || !/^[A-Za-z]{3}$/.test(value)) {
+    const got = typeof value === "string" && value !== "" ? JSON.stringify(value) : "no value";
+    throw refused(`--currency takes one three-letter currency code, such as GBP or EUR (got ${got}). Run qa run once per currency.`);
+  }
+  const browserMode = String(args["test-order"] || "off").toLowerCase();
+  const legacyMode = String(args["legacy-api-test-order"] || "off").toLowerCase();
+  if (browserMode === "off" && legacyMode !== "off") {
+    throw refused("--currency is not supported with --legacy-api-test-order: the direct API order carries no currency and would be placed in the default one. Use --test-order <mode> for orders in that currency, or drop --currency.");
+  }
+  return value.toUpperCase();
+}
+
 async function runParityQa(args) {
   // Checked here as well as on the budget itself: the budget is built after a
   // browser has launched, and a flag the operator typed wrong should cost them
   // nothing. The budget stays the authority — this is fail-fast, not the gate.
   refuseBadOrderCreationLimit(args);
+  if (Object.hasOwn(args, "currency")) {
+    throw refused("qa parity does not support --currency: the scenario's fixture sets the currency it checks. Use qa run --currency <code> to prove a currency.");
+  }
   const fixturePath = stringArg(args.fixture);
   const scenarioId = stringArg(args.scenario) || stringArg(args._[2]);
   if (!fixturePath) throw refused("QA parity requires --fixture <parity-fixture.json>.");
@@ -2209,6 +2239,7 @@ 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);
+  qaRunCurrency(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();
@@ -2223,7 +2254,15 @@ 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, liveCampaign = undefined, liveCampaignFetch = globalThis.fetch } = {}) {
+async function runResolvedQa(args, resolvedInputs, { runSessionActive = false, liveCampaign = undefined, liveCampaignFetch = globalThis.fetch } = {}) {
+  // --currency: every leg below (HTTP rows, browser loads, test orders) reads
+  // the entry page's URL from these topologies, so it is tagged once here;
+  // the validated code rides on args, under QA_RUN_CURRENCY, for the order
+  // runner's own first load of each path.
+  const currency = qaRunCurrency(args);
+  if (currency) args = { ...args, [QA_RUN_CURRENCY]: currency };
+  const entryCurrency = withEntryCurrency(resolvedInputs.topologies, currency);
+  const resolved = currency ? { ...resolvedInputs, topologies: entryCurrency.topologies } : resolvedInputs;
   const startedAt = new Date().toISOString();
   const runId = generateRunId();
   const gate = resolved.themeGate;
@@ -2315,7 +2354,14 @@ async function runResolvedQa(args, resolved, { runSessionActive = false, liveCam
   const bindingScriptLoader = createBindingScriptLoader();
   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)) }));
+    runPageChecks(page, args, {
+      sourceLoader,
+      bindingExpected,
+      bindingScriptLoader,
+      captureCommercial: commercialIds.has(String(page.page_id)),
+      currency: entryCurrency.entryPages.has(page) ? currency : null,
+      currencyNotApplied: entryCurrency.notApplied.get(page) || null,
+    }));
   const livePages = new Map();
   for (const [index, page] of pages.entries()) {
     const pageResult = pageResults[index];
@@ -2668,7 +2714,7 @@ async function finalizeQaRun({ args, resolved, runId, startedAt, assertions, tes
   const consent = resolveConsent({ proxyBase: resolved.proxyBase });
   const publishDecision = resolved.localSpecId
     ? { publish: false, reason: "local_spec", flag_invalid: false }
-    : decidePublishVerdict({ args, portalManaged: resolved.portalManaged === true, consent });
+    : decidePublishVerdict({ args, portalManaged: resolved.portalManaged === true, consent, baseUrl: resolved.baseUrl });
   if (publishDecision.flag_invalid) {
     process.stderr.write(`[campaigns-os] --post-verdict "${args["post-verdict"]}" is not a recognized value (use true|1|yes|y|on or false|0|no|n|off); the flag was ignored and the default publish decision applied.\n`);
   }
@@ -2704,7 +2750,7 @@ async function finalizeQaRun({ args, resolved, runId, startedAt, assertions, tes
     // The classified outcome (attempted, ok, error, endpoint, result,
     // http_status, base_kind) and the Run Record block derived from it.
     publish: { ...publishOutcome, response: undefined },
-    qa_verdict_publish: qaVerdictPublishBlock(publishOutcome, { verdictRunId: verdict.run_id, publisher: QA_VERDICT_PUBLISHERS.run, publishedAt: new Date().toISOString() }),
+    qa_verdict_publish: qaVerdictPublishBlock(publishOutcome, { verdictRunId: verdict.run_id, publisher: QA_VERDICT_PUBLISHERS.run, publishedAt: new Date().toISOString(), reason: publishDecision.reason }),
     publish_decision: { ...publishDecision, destination: publishDestination, consent_state: consent?.state ?? null },
     counts: countAssertions(verdict.assertions),
     theme_gate: themeGateSummary(resolved.themeGate),
@@ -2763,14 +2809,50 @@ const ENTRY_PAGE_TYPES = new Set([
   "review",
 ]);
 
+function entryPageOf(topology) {
+  const pages = Array.isArray(topology?.pages) ? topology.pages.filter((page) => page?.url) : [];
+  if (!pages.length) return null;
+  // #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.
+  return topology.partial_build_scope ? pages[0] : pages.find(isEntryLikePage) || pages[0];
+}
+
+// Each funnel's entry page gets ?currency=<CODE> through the URL API, so the
+// query string and tracking params it already carries are kept. Returns the
+// topologies unchanged without a currency; `entryPages` holds the tagged pages
+// and `notApplied` the entry pages whose URL did not parse, with the reason
+// their http row records.
+function withEntryCurrency(topologies, currency) {
+  const entryPages = new Set();
+  const notApplied = new Map();
+  if (!currency) return { topologies, entryPages, notApplied };
+  const tagged = topologyList(topologies).map((topology) => {
+    const entry = entryPageOf(topology);
+    // No URL at all: the page gets the route-url row, not an http row.
+    if (!entry?.url) return topology;
+    let url = null;
+    try {
+      url = new URL(entry.url);
+    } catch {
+      url = null;
+    }
+    if (!url) {
+      notApplied.set(entry, { currency, reason: "entry URL does not parse as an absolute URL" });
+      return topology;
+    }
+    url.searchParams.set("currency", currency);
+    const page = { ...entry, url: url.toString() };
+    entryPages.add(page);
+    return { ...topology, pages: topology.pages.map((item) => (item === entry ? page : item)) };
+  });
+  return { topologies: tagged, entryPages, notApplied };
+}
+
 function deriveEntryUrls(topologies) {
   const entries = [];
   for (const topology of topologyList(topologies)) {
-    const pages = Array.isArray(topology?.pages) ? topology.pages.filter((page) => page?.url) : [];
-    if (!pages.length) continue;
-    // #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];
+    const page = entryPageOf(topology);
+    if (!page) continue;
     entries.push({
       funnel_id: topology.funnel_id || "default",
       funnel_name: topology.funnel_name || topology.funnel_id || "default",
@@ -2841,8 +2923,17 @@ async function runPageChecks(page, args, {
   captureCommercial = false,
   bindingExpected = { value: null },
   bindingScriptLoader = createBindingScriptLoader(),
+  currency = null,
+  currencyNotApplied = null,
 } = {}) {
   const assertions = [];
+  // --currency is recorded on the entry page's HTTP row: the persisted
+  // verdict drops every URL query, so the fetched URL cannot carry it. An
+  // entry URL the currency could not be added to says so on the same row.
+  const currencyEvidence = {
+    ...(currency ? { currency } : {}),
+    ...(currencyNotApplied ? { currency_not_applied: currencyNotApplied } : {}),
+  };
   if (!page.url) {
     assertions.push(bindingAssertion(page, await observeBinding({ source: null, page, expected: bindingExpected, scriptLoader: bindingScriptLoader })));
     assertions.push(assertion({
@@ -2878,7 +2969,7 @@ async function runPageChecks(page, args, {
       severity: SEVERITY.BLOCKER,
       expected: isHttpStatus ? "2xx HTTP response" : "fetchable bounded deployed page",
       actual: isHttpStatus ? `${source.status} ${source.status_text}`.trim() : null,
-      evidence: { transport_error: { code: source.error_code, message: source.error } },
+      evidence: { transport_error: { code: source.error_code, message: source.error }, ...currencyEvidence },
     }));
     return {
       assertions,
@@ -2896,6 +2987,7 @@ async function runPageChecks(page, args, {
     status: STATUS.PASS,
     expected: "2xx HTTP response",
     actual: `${source.status} ${source.status_text}`.trim(),
+    evidence: Object.keys(currencyEvidence).length ? currencyEvidence : undefined,
   }));
 
   const expectedMeta = page.expected_meta_tags || {};
@@ -3115,9 +3207,9 @@ async function maybeRunTestOrders(
     return { orders: [], receiptAnalytics: emptyReceiptAnalytics(), qc_results: notRequestedRows() };
   }
   if (mode && mode !== "off") {
-    // Test Orders use global test cards: they bypass the payment gateway, create
-    // no transactions, and need no merchant setup or approval. `--test-order
-    // <mode>` is sufficient intent — no permission flags or packet policy gate.
+    // Test Orders use global test cards: they bypass the payment gateway and create
+    // no transactions, but each leaves a real store order record. Ask the operator
+    // once in the first turn; `--test-order <mode>` has no permission flag or packet policy gate.
     const result = await operations.runBrowser(resolved.topologies, args, runId, { captureAnalytics, spec: resolved.spec });
     assertions.push(...result.assertions);
     return {
@@ -3460,6 +3552,9 @@ function output(value, args) {
     printEntryUrlLines(value.entry_urls);
     console.log(`Run ID: ${value.run_id}`);
     console.log(`Disposition: ${value.verdict.disposition}`);
+    if (value.verdict.disposition === "ready_with_exceptions") {
+      console.log("This is a passing proof with exceptions. Report these exceptions to the operator; do not clear or waive them, or change markup just to make them pass.");
+    }
     console.log(`Counts: ${Object.entries(value.counts).map(([status, count]) => `${count} ${status}`).join(", ")}`);
     printCauseLines(value.verdict);
     printThemeGateLines(value.theme_gate, value.packet_path, value.report_path);
@@ -3472,6 +3567,9 @@ function output(value, args) {
     } else if (value.publish_skipped && value.publish_decision?.reason === "consent_off") {
       console.log(`QA portal: publish skipped — telemetry consent is off, so this non-portal-managed verdict stays local.`);
       console.log(`  Destination would be ${value.publish_decision.destination}. Opt in for this run with --post-verdict, or enable with \`${cmd("telemetry")} on\`.`);
+    } else if (value.publish_skipped && value.publish_decision?.reason === "loopback_base_url") {
+      console.log(`QA portal: publish skipped — the base URL is a local address, so this verdict stays local.`);
+      console.log(`  Destination would be ${value.publish_decision.destination}. Publish this run with \`${cmd("qa")} publish\`, or pass --post-verdict on the next run.`);
     } else if (value.publish_skipped) {
       console.log(`QA portal: publish skipped (--no-post-verdict); local verdict only.`);
     } else {
@@ -3579,14 +3677,21 @@ function printCauseLines(verdict) {
   // One formatter, shared with the doctor report: a prior record that exists
   // but has no usable QA verdict is not the same state as no prior record, and
   // the two commands must not describe it differently.
-  for (const line of formatCauseReportLines(verdict?.cause_summary)) console.log(line);
+  if (verdict?.disposition !== "ready_with_exceptions") {
+    for (const line of formatCauseReportLines(verdict?.cause_summary)) console.log(line);
+  }
   const exceptions = Array.isArray(verdict.exceptions) ? verdict.exceptions : [];
   if (!exceptions.length) return;
   console.log("Findings:");
   for (const exception of exceptions) {
-    const identity = [exception.id, exception.page].filter(Boolean).join(" @ ") || "(unidentified finding)";
     const tag = formatCauseTag(exception);
-    console.log(`- ${identity} (${exception.status || "unknown"})${tag ? ` ${tag}` : ""}`);
+    if (verdict.disposition === "ready_with_exceptions") {
+      const severity = exception.severity ? `; severity: ${exception.severity}` : "";
+      console.log(`- id: ${exception.id || "(none)"}; page: ${exception.page || "(none)"} (${exception.status || "unknown"}${severity})${tag ? ` ${tag}` : ""}`);
+    } else {
+      const identity = [exception.id, exception.page].filter(Boolean).join(" @ ") || "(unidentified finding)";
+      console.log(`- ${identity} (${exception.status || "unknown"})${tag ? ` ${tag}` : ""}`);
+    }
   }
 }
 
@@ -3601,7 +3706,7 @@ export function themeGateLines(themeGate, packetPath = null, reportPath = null)
   for (const action of themeGate.required_actions || []) {
     lines.push(`  - ${requiredActionText(action, { packetPath, reportPath })}`);
   }
-  lines.push("Or rerun with --theme-waive \"<reason>\" to record an ephemeral waiver for this run.");
+  lines.push('Or rerun once with --theme-waive "<reason>"; this waiver applies only to that run. A recorded theme waive requires --waived-by "<named human>".');
   return lines;
 }
 
@@ -3639,8 +3744,8 @@ export function qaResolveNextProofLines(value) {
     `Next expected proof: ${qaRunCommandFromResolve(value)}`,
     `Entry URL(s) resolved: ${formatEntryUrlsForProof(value.entry_urls)}`,
     value.local_spec_id
-      ? "Typed-card test orders use global test cards (no transactions/no permission gate); local-spec QA stays in the repository."
-      : "Typed-card test orders use global test cards (no transactions/no permission gate); QA publishes to the portal by default.",
+      ? "Typed-card test cards create no transactions but leave real store order records. Unless the operator has already said test orders are fine for this campaign, ask once, up front, before placing them; there is no permission flag. Local-spec QA stays in the repository."
+      : "Typed-card test cards create no transactions but leave real store order records. Unless the operator has already said test orders are fine for this campaign, ask once, up front, before placing them; there is no permission flag. QA publishes to the portal by default.",
   ];
 }
 
@@ -3757,8 +3862,13 @@ export function forcedAnalyticsCorrectness(args) {
 // else (client projects, fixtures, local shakeouts on a local spec), consent
 // off (CAMPAIGNS_OS_TELEMETRY=off / `campaigns-os telemetry off`) means the
 // verdict stays local, with the destination and the opt-in flag named in the
-// run output. Publishing for the portal path is never weakened.
-export function decidePublishVerdict({ args = {}, portalManaged = false, consent = null } = {}) {
+// run output. Publishing for the portal path is never weakened by consent.
+// #486: a run against a local-address base URL (localhost or any *.localhost
+// name, any 127.x.x.x, 0.0.0.0, [::1] or an IPv4-mapped loopback; see
+// isLocalAddressUrl below) is a local check, so by default its verdict stays
+// local whatever the spec source; the output names --post-verdict and qa
+// publish. An explicit --post-verdict still publishes.
+export function decidePublishVerdict({ args = {}, portalManaged = false, consent = null, baseUrl = null } = {}) {
   if (args["no-post-verdict"] === true || args["local-only"] === true) {
     return { publish: false, reason: "flag_opt_out" };
   }
@@ -3775,11 +3885,30 @@ export function decidePublishVerdict({ args = {}, portalManaged = false, consent
     flagInvalid = true;
   }
   const decorate = (decision) => (flagInvalid ? { ...decision, flag_invalid: true } : decision);
+  if (isLocalAddressUrl(baseUrl)) return decorate({ publish: false, reason: "loopback_base_url" });
   if (portalManaged) return decorate({ publish: true, reason: "portal_managed_default" });
   if (consent?.state === "off") return decorate({ publish: false, reason: "consent_off" });
   return decorate({ publish: true, reason: "default" });
 }
 
+// The publish default (#486) reads "local" more widely than the shared
+// LOOPBACK_HOSTNAMES list, which also decides where plain http is allowed and
+// so stays narrow: any 127.0.0.0/8 address, 0.0.0.0, [::1], an IPv4-mapped
+// loopback, and localhost or any *.localhost name (with or without a trailing
+// dot). Keeping such a run local is the safe direction: --post-verdict and
+// qa publish still send it.
+function isLocalAddressUrl(value) {
+  if (typeof value !== "string" || !value.trim()) return false;
+  let hostname;
+  try { hostname = new URL(value.trim()).hostname.toLowerCase(); } catch { return false; }
+  const name = hostname.replace(/\.$/, "");
+  if (name === "localhost" || name.endsWith(".localhost")) return true;
+  if (/^127(?:\.\d{1,3}){3}$/.test(name) || name === "0.0.0.0") return true;
+  if (name === "[::1]" || name === "[::]") return true;
+  // WHATWG URL serializes ::ffff:127.x.y.z as [::ffff:7fxx:xxxx].
+  return /^\[::ffff:7f[0-9a-f]{2}:[0-9a-f]{1,4}\]$/.test(name);
+}
+
 function policySnapshot(packet) {
   return {
     campaign: {
@@ -3994,16 +4123,23 @@ function htmlIncludesRouteReference(html, expectedUrl) {
   return html.includes(expectedUrl) || html.includes(path);
 }
 
-// A data-upsell-proxy button forwards its click to the SDK action inside the
-// offer. With no such action, the route's URL can still sit in the page's meta
-// tags, so the reference match would pass a control that does nothing.
+// A data-upsell-proxy button forwards its click to the SDK action of its own
+// spelling inside the offer. With no such action, the route's URL can still sit
+// in the page's meta tags, so the reference match would pass a control that
+// does nothing.
 function findDeadUpsellProxy(html, kind, page) {
   if (page.page_type !== "upsell" || kind === "next") return null;
-  const action = kind === "accept" ? "add" : "skip";
-  if (!new RegExp(`\\bdata-upsell-proxy\\s*=\\s*["']${action}["']`, "i").test(html)) return null;
-  const target = new RegExp(`\\bdata-next-upsell-action\\s*=\\s*["']${action}["']`, "i");
-  if (upsellOfferElements(html).some((offer) => target.test(offer))) return null;
-  return `data-upsell-proxy="${action}" with no data-next-upsell-action="${action}" inside the offer to forward to`;
+  for (const action of UPSELL_ACTION_SPELLINGS[kind]) {
+    if (!new RegExp(`\\bdata-upsell-proxy\\s*=\\s*["']${action}["']`, "i").test(html)) continue;
+    const target = upsellActionPattern(action);
+    if (upsellOfferElements(html).some((offer) => target.test(offer))) continue;
+    return `data-upsell-proxy="${action}" with no data-next-upsell-action="${action}" inside the offer to forward to`;
+  }
+  return null;
+}
+
+function upsellActionPattern(action) {
+  return new RegExp(`\\bdata-next-upsell-action\\s*=\\s*["']${action}["']`, "i");
 }
 
 // The markup of each [data-next-upsell="offer"] element, read to its closing
@@ -4032,14 +4168,9 @@ function upsellOfferElements(html) {
 }
 
 function findSdkRouteAction(html, kind, page) {
-  if (page.page_type !== "upsell") return null;
-  if (kind === "accept" && /\bdata-next-upsell-action\s*=\s*["']add["']/i.test(html)) {
-    return 'SDK upsell accept control: data-next-upsell-action="add"';
-  }
-  if (kind === "decline" && /\bdata-next-upsell-action\s*=\s*["']skip["']/i.test(html)) {
-    return 'SDK upsell decline control: data-next-upsell-action="skip"';
-  }
-  return null;
+  if (page.page_type !== "upsell" || kind === "next") return null;
+  const action = UPSELL_ACTION_SPELLINGS[kind].find((spelling) => upsellActionPattern(spelling).test(html));
+  return action ? `SDK upsell ${kind} control: data-next-upsell-action="${action}"` : null;
 }
 
 function decodeHtml(value) {
@@ -4099,6 +4230,7 @@ function extractApiError(raw) {
 }
 
 export const __qaNodeTestHooks = Object.freeze({
+  output,
   extractTopologies,
   validatedOrderCreationLimit,
   resolveQaInputs,
@@ -4123,6 +4255,8 @@ export const __qaNodeTestHooks = Object.freeze({
   themeGateSummary,
   templateBrandContractAssertion,
   deriveEntryUrls,
+  qaRunCurrency,
+  withEntryCurrency,
   derivePageUrls,
   deriveTestedUrlsFromAssertions,
   resolvePayload,

package/src/qa-verdict-publish.mjs

@@ -83,7 +83,7 @@ export function skippedQaVerdictPublish() {
  * remit (`ok` when the receiver's answer counts as stored, `failed` when it
  * refused or never answered, `skipped` when nothing was sent).
  */
-export function qaVerdictPublishBlock(outcome, { verdictRunId, publisher, publishedAt = null }) {
+export function qaVerdictPublishBlock(outcome, { verdictRunId, publisher, publishedAt = null, reason = null }) {
   const attempted = Boolean(outcome?.attempted);
   const ok = attempted ? outcome.ok === true : null;
   return {
@@ -94,6 +94,7 @@ export function qaVerdictPublishBlock(outcome, { verdictRunId, publisher, publis
     error: attempted && typeof outcome.error === "string" ? outcome.error : null,
     endpoint: attempted ? outcome.endpoint ?? QA_VERDICT_PUBLISH_ENDPOINT : null,
     state: attempted ? (ok ? "ok" : "failed") : "skipped",
+    reason: reason ?? outcome?.reason ?? null,
     result: attempted ? outcome.result ?? null : null,
     base_kind: attempted ? outcome.base_kind ?? null : null,
     published_at: attempted && ok ? publishedAt : null,