@nextcommerce/campaigns-os 1.54.0 → 1.57.0

package/src/qa-node.mjs

@@ -1,5 +1,5 @@
 import { campaignSpecIdentity, resolveCampaignIdentity, campaignIdentitiesMatch } from "./spec-source-identity.mjs";
-import { applyLocalPreviewToCheckpoint, applyLocalPreviewToPolishGate, carriedForwardMessage, CARRIED_FORWARD, starterResidueIsExpected } from "./local-preview-policy.mjs";
+import { applyLocalPreviewToCheckpoint, applyLocalPreviewToPolishGate, carriedForwardMessage, CARRIED_FORWARD, ensureUrlTrailingSlash, normalizeQaBaseUrl, starterResidueIsExpected } from "./local-preview-policy.mjs";
 import { expectedBinding, createBindingScriptLoader, observeBinding, bindingAssertion, scriptParseAssertion } from './qa-binding-evidence.mjs';
 import { shellToken } from "./shell-token.mjs";
 import { currentBriefMaterial } from "./input-currency.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";
@@ -61,8 +61,10 @@ import {
   declineRouteTarget,
   forwardRouteTarget,
   inapplicableForwardFields,
+  upgradeCampaignSpec,
 } from "../campaign-spec/dist/index.js";
 import { evaluateThemeGate } from "./theme-gate.mjs";
+import { findPaymentPage } from "./qa-test-order-topology.mjs";
 import { probeRouteUrls, ROUTE_PROBE_DEFAULT_TIMEOUT_MS } from "./qa-route-probe.mjs";
 import { resolveCommerceCatalog, resolvePacketCommerceCatalogPath, resolveTemplateBrandContract } from "./private-template-source.mjs";
 import { computeBuildFingerprint, resolveBuiltSiteScope, topologiesFromBuiltSiteScope } from "./built-site-scope.mjs";
@@ -85,6 +87,7 @@ import { campaignSidecarPaths, explicitReportPath, resolveCampaignWorkspace, tar
 import { loadParityFixture } from "./qa-parity-fixture.mjs";
 import { assessParityCapture, resolveParityScenario, runParityCapture } from "./qa-parity-capture.mjs";
 import { loadPageKitCampaignEntry, PAGE_KIT_CAMPAIGNS_REL_PATH } from "./page-kit-campaign-config.mjs";
+import { publicRouteForPage } from "./source-html-intake.mjs";
 import {
   evaluatePageKitStoreProfile,
   PAGE_KIT_STORE_PROFILE_FIELDS,
@@ -115,7 +118,7 @@ import {
   liveRefsNotRunMessage,
   readLiveCampaignForPacket,
 } from "./live-campaign-refs.mjs";
-import { specPackageRefs, specShippingRefs } from "./doctor/checks.mjs";
+import { entryPageKitServingRoute, isRootRoutedEntryPage, 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
@@ -128,7 +131,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
@@ -189,6 +192,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
@@ -199,8 +206,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
@@ -459,7 +467,6 @@ async function resolveQaInputs(args, {
   }
   const normalized = normalizeSpec(rawSpec);
   const publicRouteSlug = resolvePublicRouteSlug({ packet, spec: normalized, rawSpec });
-  const baseUrl = normalizeQaBaseUrl(inputBaseUrl, publicRouteSlug);
   // Packet 01: the analytics legs capture ONE URL derived from resolved
   // identity (public_route_slug + route_root), composed here where the raw
   // operator/deploy base is still in hand.
@@ -470,6 +477,7 @@ async function resolveQaInputs(args, {
     routeRoot: resolveCampaignRouteRoot({ packet, spec: normalized, rawSpec, publicRouteSlug, notes: routeRootNotes }),
     routeRootNote: routeRootNotes[0] || null,
   });
+  const baseUrl = normalizeQaBaseUrl(inputBaseUrl, publicRouteSlug);
   const specHash = computeSpecHash(rawSpec);
   // The brief material this run is judged against, bound at run start beside
   // the spec hash: the QA stage write stamps it, not the material at write time.
@@ -479,7 +487,16 @@ async function resolveQaInputs(args, {
     || stringArg(normalized?.campaign?.preferred_template_family)
     || null;
   const commerceStructureContract = loadCommerceStructureContract({ packet, packetPath, templateFamily });
-  const topologies = extractTopologies(normalized, { baseUrl, publicRouteSlug, templateFamily, commerceStructureContract });
+  const targetRepo = checkpointPreflight?.targetRepo || (packetPath && packet ? targetRepoFor(packetPath, packet) : null);
+  const targetOutputDir = targetRepo && packet?.assembly?.output_dir ? resolve(targetRepo, packet.assembly.output_dir) : null;
+  const mappingById = new Map((packet?.source_html?.pages || []).map((page) => [page.page_id, page]));
+  const topologies = extractTopologies(normalized, {
+    baseUrl, publicRouteSlug, templateFamily, commerceStructureContract,
+    entryServingRoute: (page) => entryPageKitServingRoute(targetRepo, publicRouteSlug, page, {
+      targetOutputDir,
+      mapping: mappingById.get(page.id),
+    }),
+  });
   const themeGate = resolveThemeGate({
     packetPath,
     topologies,
@@ -966,7 +983,9 @@ function resolvePolishGate({
   return gate;
 }
 
-const THEME_GATE_COMMERCE_TYPES = new Set(["checkout", "upsell", "downsell", "receipt", "thankyou"]);
+// select and checkout_step pages render the family's checkout surface without
+// taking payment (campaigns-os#641); the brand theme applies to them as well.
+const THEME_GATE_COMMERCE_TYPES = new Set(["select", "checkout_step", "checkout", "upsell", "downsell", "receipt", "thankyou"]);
 
 function themeGateScopeFromTopologies(topologies = []) {
   const built_pages = [];
@@ -1861,7 +1880,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.
@@ -2136,11 +2155,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>.");
@@ -2211,6 +2253,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();
@@ -2225,7 +2268,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;
@@ -2317,7 +2368,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];
@@ -2706,7 +2764,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),
@@ -2765,14 +2823,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",
@@ -2843,8 +2937,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({
@@ -2880,7 +2983,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,
@@ -2898,6 +3001,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 || {};
@@ -3117,9 +3221,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 {
@@ -3144,7 +3248,10 @@ async function maybeRunLegacyApiTestOrders({ args, resolved, runId, assertions }
   const apiBase = stringArg(args["campaigns-api-base"]) || process.env.CAMPAIGNS_API_BASE;
   if (!apiKey || !apiBase) throw new Error("Legacy direct API test orders require --api-key/QA_CAMPAIGNS_API_KEY and --campaigns-api-base/CAMPAIGNS_API_BASE.");
   const { cart, paths } = legacyTestOrderInputs(args);
-  const checkout = findPage(resolved.topologies, "checkout");
+  // The Checkout on the tested path, never the first page typed checkout: on a
+  // split checkout that was the first step, whose forward link is the next
+  // step, so the order's success URL pointed back into checkout (#641).
+  const checkout = findPaymentPage(resolved.topologies);
   if (!checkout?.url) throw new Error("--test-order requires a checkout page URL.");
   const upsell = findPage(resolved.topologies, "upsell");
   const orders = [];
@@ -3228,22 +3335,25 @@ async function createTestOrder({ apiBase, apiKey, cart, runId, successUrl, spec,
   }
 }
 
+// QA reads the v5 page vocabulary: a v4 spec's `checkout → checkout` chain is
+// retyped `checkout_step` on read (campaigns-os#641). The raw spec is untouched,
+// so the spec hash still covers the bytes as written.
 function normalizeSpec(raw) {
-  if (Array.isArray(raw?.funnels)) return raw;
+  if (Array.isArray(raw?.funnels)) return upgradeCampaignSpec(raw);
   if (Array.isArray(raw?.funnel_pages)) {
     return { ...raw, funnels: [{ id: "default", name: "Default", weight: 100, pages: raw.funnel_pages }] };
   }
   return { ...raw, funnels: [] };
 }
 
-function extractTopologies(spec, { baseUrl = null, publicRouteSlug = null, templateFamily = null, commerceStructureContract = null } = {}) {
+function extractTopologies(spec, { baseUrl = null, publicRouteSlug = null, templateFamily = null, commerceStructureContract = null, entryServingRoute = null } = {}) {
   const pageById = new Map();
   for (const funnel of spec.funnels || []) {
     for (const page of funnel.pages || []) pageById.set(page.id, page);
   }
   const urlById = new Map();
   for (const [id, page] of pageById) {
-    urlById.set(id, resolvePageUrl(page, baseUrl, publicRouteSlug));
+    urlById.set(id, resolvePageUrl(page, baseUrl, publicRouteSlug, entryServingRoute?.(page)));
   }
   return (spec.funnels || []).map((funnel) => ({
     funnel_id: funnel.id || "default",
@@ -3298,13 +3408,13 @@ function extractTopologies(spec, { baseUrl = null, publicRouteSlug = null, templ
   }));
 }
 
-function resolvePageUrl(page, baseUrl, publicRouteSlug = null) {
+function resolvePageUrl(page, baseUrl, publicRouteSlug = null, entryServingRoute = null) {
   if (typeof page.url === "string" && page.url.trim()) return page.url.trim();
   if (!baseUrl) return null;
-  const route = typeof page.page_url === "string" && page.page_url.trim()
-    ? runtimeRelativeRouteForSpecValue(page.page_url, publicRouteSlug)
-    : page.is_entry
-      ? ""
+  const route = isRootRoutedEntryPage(page, publicRouteSlug)
+    ? entryServingRoute?.route || ""
+    : typeof page.page_url === "string" && page.page_url.trim()
+      ? runtimeRelativeRouteForSpecValue(page.page_url, publicRouteSlug)
       : defaultRouteForType(page.type);
   if (isAbsoluteHttpUrl(route)) return route;
   try {
@@ -3316,6 +3426,7 @@ function resolvePageUrl(page, baseUrl, publicRouteSlug = null) {
 
 function defaultRouteForType(type) {
   if (type === "thankyou") return "receipt/";
+  if (type === "checkout_step") return "checkout-step/";
   if (["presell", "landing", "checkout", "upsell", "downsell"].includes(type)) return `${type}/`;
   return `${type || "page"}/`;
 }
@@ -3462,6 +3573,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);
@@ -3584,14 +3698,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}` : ""}`);
+    }
   }
 }
 
@@ -3606,7 +3727,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;
 }
 
@@ -3644,8 +3765,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.",
   ];
 }
 
@@ -3829,21 +3950,6 @@ function normalizeBaseUrl(value) {
   return typeof value === "string" && value.trim() ? value.trim() : null;
 }
 
-function normalizeQaBaseUrl(value, publicRouteSlug) {
-  const baseUrl = normalizeBaseUrl(value);
-  if (!baseUrl) return null;
-  const slug = normalizePublicRouteSlug(publicRouteSlug);
-  if (!slug) return ensureUrlTrailingSlash(baseUrl);
-  try {
-    const url = new URL(ensureUrlTrailingSlash(baseUrl));
-    const segments = url.pathname.split("/").filter(Boolean);
-    if (segments.at(-1) === slug) return ensureUrlTrailingSlash(url.toString());
-    return new URL(`${slug}/`, url).toString();
-  } catch {
-    return ensureUrlTrailingSlash(baseUrl);
-  }
-}
-
 // The campaign's served route root — "/", "/<slug>/", or null — read by the
 // one rule every stage shares (route-identity.mjs): the packet under its exact
 // canonical form, the spec under prepare-build's intake form. A declaration
@@ -3951,10 +4057,6 @@ function resolvePublicRouteSlug({ packet, spec, rawSpec }) {
     || null;
 }
 
-function ensureUrlTrailingSlash(value) {
-  return value.endsWith("/") ? value : `${value}/`;
-}
-
 function stripOrigin(value) {
   try {
     const url = new URL(value);
@@ -4023,16 +4125,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
@@ -4061,14 +4170,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) {
@@ -4128,6 +4232,7 @@ function extractApiError(raw) {
 }
 
 export const __qaNodeTestHooks = Object.freeze({
+  output,
   extractTopologies,
   validatedOrderCreationLimit,
   resolveQaInputs,
@@ -4152,6 +4257,8 @@ export const __qaNodeTestHooks = Object.freeze({
   themeGateSummary,
   templateBrandContractAssertion,
   deriveEntryUrls,
+  qaRunCurrency,
+  withEntryCurrency,
   derivePageUrls,
   deriveTestedUrlsFromAssertions,
   resolvePayload,