@nextcommerce/campaigns-os 1.54.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
@@ -189,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
@@ -199,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
@@ -1861,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.
@@ -2136,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>.");
@@ -2211,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();
@@ -2225,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;
@@ -2317,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];
@@ -2706,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),
@@ -2765,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",
@@ -2843,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({
@@ -2880,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,
@@ -2898,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 || {};
@@ -3117,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 {
@@ -3462,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);
@@ -3584,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}` : ""}`);
+    }
   }
 }
 
@@ -3606,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;
 }
 
@@ -3644,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.",
   ];
 }
 
@@ -4023,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
@@ -4061,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) {
@@ -4128,6 +4230,7 @@ function extractApiError(raw) {
 }
 
 export const __qaNodeTestHooks = Object.freeze({
+  output,
   extractTopologies,
   validatedOrderCreationLimit,
   resolveQaInputs,
@@ -4152,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,

package/src/run-record.mjs

@@ -14,6 +14,8 @@ import { randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { ADAPTER_DECISION_STRATEGY_FIELDS } from "./adapter-decision-contract.mjs";
+import { currentBuildFingerprint } from "./polish-gate.mjs";
+import { qaRecordedBuildFingerprint, qaRecordedForCurrentBuild } from "./stage-ledger.mjs";
 
 export const RUN_RECORD_SCHEMA = "campaigns-os-run-record/v0";
 export const RUN_RECORDS_DIR_REL_PATH = ".campaign-runtime/run-records";
@@ -60,6 +62,14 @@ export const RUN_RECORD_REMIT_BASE_KINDS = ["canonical", "loopback", "proxy"];
 // to refuse re-posting a verdict the portal already holds.
 export const RUN_RECORD_QA_VERDICT_PUBLISH_STATES = ["skipped", "ok", "failed"];
 export const RUN_RECORD_QA_VERDICT_PUBLISHERS = ["qa run", "qa publish"];
+export const RUN_RECORD_QA_VERDICT_PUBLISH_REASONS = ["loopback_base_url", "portal_managed_default", "consent_off", "flag_opt_out", "flag_opt_in", "default", "local_spec"];
+export const RUN_RECORD_CLOSERS = ["run_end", "qa_auto_end", "stale_sweep", "manual"];
+const RUN_RECORD_FIELDS = new Set([
+  "schema_version", "run_id", "package_version", "surface_version", "toolkit_commit", "command", "argv_shape", "created_at",
+  "consent_state", "consent_source", "remit_attempted", "remit_ok", "remit_error", "remit_endpoint", "remit_state",
+  "remit_result", "remit_base_kind", "qa_verdict_publish", "closed_by", "identity", "artifacts", "observations",
+  "surfaces", "primary_surface", "surface_confidence", "lifecycle",
+]);
 
 // Required core. Strict here; permissive about optional sub-structures (the
 // validator checks shapes, not nested artifact bodies — those are referenced
@@ -105,6 +115,12 @@ export function validateRunRecord(record) {
   if (record.schema_version != null && record.schema_version !== RUN_RECORD_SCHEMA) {
     add("record.schema_version", `Expected schema_version "${RUN_RECORD_SCHEMA}".`);
   }
+  for (const key of Object.keys(record)) {
+    if (!RUN_RECORD_FIELDS.has(key)) add(`record.${key}`, `unknown Run Record field "${key}".`);
+  }
+  if (record.closed_by !== undefined && !RUN_RECORD_CLOSERS.includes(record.closed_by)) {
+    add("record.closed_by", `closed_by must be one of: ${RUN_RECORD_CLOSERS.join(", ")}.`);
+  }
 
   if (record.argv_shape == null || !isStringArray(record.argv_shape)) {
     add("record.argv_shape", "argv_shape is required and must be an array of strings (flag names, never values).");
@@ -215,25 +231,16 @@ export function validateRunRecord(record) {
         const q = obs.qa;
         if (typeof q !== "object" || Array.isArray(q)) {
           add("record.observations.qa", "qa must be an object.");
-        } else if (q.gap_classes != null && !isStringArray(q.gap_classes)) {
-          add("record.observations.qa.gap_classes", "gap_classes must be an array of strings.");
-        }
-      }
-    }
-  }
-
-  if (record.agent_usage != null) {
-    const usage = record.agent_usage;
-    if (typeof usage !== "object" || Array.isArray(usage)) {
-      add("record.agent_usage", "agent_usage must be an object when present.");
-    } else {
-      for (const field of ["input_tokens", "output_tokens", "tool_output_tokens", "total_tokens", "elapsed_ms"]) {
-        if (usage[field] != null && (!Number.isInteger(usage[field]) || usage[field] < 0)) {
-          add(`record.agent_usage.${field}`, `${field} must be a non-negative integer when present.`);
+        } else {
+          if (q.gap_classes != null && !isStringArray(q.gap_classes)) add("record.observations.qa.gap_classes", "gap_classes must be an array of strings.");
+          if (q.verdict_run_id != null && !isNonEmptyString(q.verdict_run_id)) add("record.observations.qa.verdict_run_id", "verdict_run_id must be a non-empty string or null.");
+          if (q.build_fingerprint != null && !isNonEmptyString(q.build_fingerprint)) add("record.observations.qa.build_fingerprint", "build_fingerprint must be a non-empty string or null.");
+          if (q.stale != null && typeof q.stale !== "boolean") add("record.observations.qa.stale", "stale must be a boolean or null.");
+          for (const key of Object.keys(q)) {
+            if (!["disposition", "gap_classes", "verdict_run_id", "build_fingerprint", "stale"].includes(key)) add(`record.observations.qa.${key}`, `unknown qa observation field "${key}".`);
+          }
         }
       }
-      if (usage.model != null && typeof usage.model !== "string") add("record.agent_usage.model", "model must be a string when present.");
-      if (usage.source != null && typeof usage.source !== "string") add("record.agent_usage.source", "source must be a string when present.");
     }
   }
 
@@ -301,7 +308,10 @@ export function validateQaVerdictPublish(block) {
   if (block.published_at != null && !isNonEmptyString(block.published_at)) {
     add("record.qa_verdict_publish.published_at", "published_at must be a non-empty string or null.");
   }
-  const allowed = new Set(["verdict_run_id", "publisher", "attempted", "ok", "error", "endpoint", "state", "result", "base_kind", "published_at"]);
+  if (block.reason != null && !RUN_RECORD_QA_VERDICT_PUBLISH_REASONS.includes(block.reason)) {
+    add("record.qa_verdict_publish.reason", `reason must be one of: ${RUN_RECORD_QA_VERDICT_PUBLISH_REASONS.join(", ")} (or null).`);
+  }
+  const allowed = new Set(["verdict_run_id", "publisher", "attempted", "ok", "error", "endpoint", "state", "result", "base_kind", "published_at", "reason"]);
   for (const key of Object.keys(block)) {
     if (!allowed.has(key)) add(`record.qa_verdict_publish.${key}`, `unknown qa_verdict_publish field "${key}".`);
   }
@@ -324,6 +334,9 @@ export function validateRunRecordLifecycle(lc) {
   if (lc.duration_ms != null && typeof lc.duration_ms !== "number") add("record.lifecycle.duration_ms", "duration_ms must be a number or null.");
   if (lc.wall_clock_duration_ms != null && typeof lc.wall_clock_duration_ms !== "number") add("record.lifecycle.wall_clock_duration_ms", "wall_clock_duration_ms must be a number or null.");
   if (lc.repair_loop_count != null && !Number.isInteger(lc.repair_loop_count)) add("record.lifecycle.repair_loop_count", "repair_loop_count must be an integer or null.");
+  for (const field of ["needs_input_count", "failure_count"]) {
+    if (lc[field] !== undefined && (!Number.isInteger(lc[field]) || lc[field] < 0)) add(`record.lifecycle.${field}`, `${field} must be a non-negative integer.`);
+  }
   if (lc.stages != null) {
     if (!Array.isArray(lc.stages)) {
       add("record.lifecycle.stages", "stages must be an array when present.");
@@ -334,6 +347,8 @@ export function validateRunRecordLifecycle(lc) {
         } else {
           if (stage.duration_ms != null && typeof stage.duration_ms !== "number") add(`record.lifecycle.stages[${index}].duration_ms`, "stage duration_ms must be a number or null.");
           if (stage.exit_status != null && !Number.isInteger(stage.exit_status)) add(`record.lifecycle.stages[${index}].exit_status`, "stage exit_status must be an integer or null.");
+          if (stage.wait_ms != null && (!Number.isInteger(stage.wait_ms) || stage.wait_ms < 0)) add(`record.lifecycle.stages[${index}].wait_ms`, "stage wait_ms must be a non-negative integer or null.");
+          if (stage.finding_codes !== undefined && (!isStringArray(stage.finding_codes) || stage.finding_codes.length > 5 || new Set(stage.finding_codes).size !== stage.finding_codes.length || !Number.isInteger(stage.exit_status) || stage.exit_status === 0)) add(`record.lifecycle.stages[${index}].finding_codes`, "finding_codes must have at most five distinct strings and require a non-zero exit_status.");
         }
       });
     }
@@ -395,8 +410,14 @@ function extractSpecValidationRuleIds(doctor) {
   return [...new Set(ids)];
 }
 
-function extractQaObservations(verdict) {
+function extractQaObservations(verdict, report) {
   if (!verdict || typeof verdict !== "object") return null;
+  const verdictRunId = isNonEmptyString(verdict.run_id) ? verdict.run_id : null;
+  // The verdict owns the disposition. The report owns QA's build stamp, so
+  // only bind the two when its QA stage names this exact verdict.
+  const sameVerdict = verdictRunId !== null && report?.stages?.qa?.verdict_run_id === verdictRunId;
+  const recorded = sameVerdict ? qaRecordedBuildFingerprint(report) : null;
+  const current = currentBuildFingerprint(report);
   const families = new Set();
   for (const exception of Array.isArray(verdict.exceptions) ? verdict.exceptions : []) {
     if (typeof exception?.family === "string") families.add(exception.family);
@@ -404,6 +425,9 @@ function extractQaObservations(verdict) {
   return {
     disposition: typeof verdict.disposition === "string" ? verdict.disposition : null,
     gap_classes: [...families],
+    verdict_run_id: verdictRunId,
+    build_fingerprint: recorded,
+    stale: recorded && current ? !qaRecordedForCurrentBuild(report, current) : null,
   };
 }
 
@@ -465,17 +489,6 @@ function normalizeRemitState(remit) {
   return "skipped";
 }
 
-function normalizeAgentUsage(usage) {
-  if (!usage || typeof usage !== "object" || Array.isArray(usage)) return null;
-  const out = {};
-  for (const field of ["input_tokens", "output_tokens", "tool_output_tokens", "total_tokens", "elapsed_ms"]) {
-    if (Number.isInteger(usage[field]) && usage[field] >= 0) out[field] = usage[field];
-  }
-  if (isNonEmptyString(usage.model)) out.model = usage.model.trim();
-  if (isNonEmptyString(usage.source)) out.source = usage.source.trim();
-  return Object.keys(out).length ? out : null;
-}
-
 const PRIMARY_SURFACE_PRIORITY = ["platform", "template", "design-source", "spec-rule", "cli", "skill", "docs"];
 
 const ADAPTER_DECISION_SURFACE_BY_FIELD = {
@@ -667,7 +680,7 @@ export function assembleRunRecord({
   primarySurface = null,
   surfaceConfidence = null,
   lifecycle = null,
-  agentUsage = null,
+  closedBy = null,
   qaVerdictPublish = null,
   now = new Date(),
 } = {}) {
@@ -679,7 +692,7 @@ export function assembleRunRecord({
   }
   const adapter = extractAdapterDecisions(selectAdapterDecisions({ packet, report, context }));
   if (adapter) observations.adapter_decisions = adapter;
-  const qaObs = extractQaObservations(qaVerdict);
+  const qaObs = extractQaObservations(qaVerdict, report);
   if (qaObs) observations.qa = qaObs;
   observations.finding_ids = selectRunFindingIds(journal, runId);
   const malformedJournalLines = Array.isArray(journal?.malformed)
@@ -732,8 +745,7 @@ export function assembleRunRecord({
   }
   if (surfaceConfidence) record.surface_confidence = surfaceConfidence;
   if (lifecycle && typeof lifecycle === "object" && !Array.isArray(lifecycle)) record.lifecycle = lifecycle;
-  const normalizedUsage = normalizeAgentUsage(agentUsage);
-  if (normalizedUsage) record.agent_usage = normalizedUsage;
+  if (RUN_RECORD_CLOSERS.includes(closedBy)) record.closed_by = closedBy;
   // Present only when a publish outcome is known: an absent block reads as
   // "nothing recorded", which is what every record before this field says.
   if (qaVerdictPublish && typeof qaVerdictPublish === "object" && !Array.isArray(qaVerdictPublish)) record.qa_verdict_publish = qaVerdictPublish;