@nextcommerce/campaigns-os 1.52.0 → 1.54.0

package/src/progress-node.mjs

@@ -5,6 +5,7 @@ import {mkdirSync,readFileSync,writeFileSync,renameSync,rmSync,readdirSync} from
 import {join,resolve,dirname} from 'node:path';
 import {PROGRESS_SCHEMA_VERSION,PROGRESS_STAGES,PROGRESS_STAGE_STATUSES,PROGRESS_CONTINUATIONS,PROGRESS_ACTION_IDS,PROGRESS_GATE_IDS,canonicalProgressJson,progressSnapshotId,verifyProgressSnapshot} from './progress.mjs';
 import {specMaterialHash} from './spec-identity.mjs';
+import {effectiveStageStatus} from './input-currency.mjs';
 import {sameFile} from './fs-identity.mjs';
 import {withDirectoryLock} from './directory-lock.mjs';
 import {resolveConsent,CANONICAL_REMIT_SCOPE,normalizeConsentScope,announceDefaultOnTelemetry} from './consent.mjs';
@@ -17,7 +18,7 @@ const accepted = (value,values,fallback='unknown')=>values.includes(value)?value
 // A next action that is a variant of a fixed action projects onto it: the
 // order-bump QA run is a QA run. Without this, the closed v0 vocabulary would
 // read it as unknown and mark a ready QA continuation blocked.
-const PROGRESS_ACTION_ALIASES = new Map([['qa_run_bump','qa_run']]);
+const PROGRESS_ACTION_ALIASES = new Map([['qa_run_bump','qa_run'],['refresh_inputs','recheck']]);
 const hash = value=>typeof value==='string'&&/^(?:sha256:)?[0-9a-f]{64}$/i.test(value)?`sha256:${value.replace(/^sha256:/i,'').toLowerCase()}`:null;
 const id = value=>typeof value==='string'&&/^[A-Za-z0-9_-]{1,64}$/.test(value)?value:null;
 const digest = value=>`sha256:${createHash('sha256').update(value).digest('hex')}`;
@@ -54,7 +55,15 @@ export function projectProgressObservation({workspace,context,report,doctor,cont
   const aligned=contextBound&&mapId&&localMapId===mapId&&baseline?.map_id===mapId&&baseline?.algorithm==='map-store-v1'&&hash(baseline.hash)&&localHash&&localHash===hash(baseline.local_spec_material_hash);
   const build=hash(doctor?.derived?.build_output_fingerprint?.value);
   const recordedBuild=hash(report?.stages?.assembly?.build_fingerprint);
-  const reportBound=doctor?.derived?.prepare_build_gate?.binding_failure!==true&&contextBound&&campaignIdentitiesMatch(packet?.spec,campaignSpecIdentity(spec))&&campaignIdentitiesMatch(packet?.spec,report?.identity)&&localHash&&localHash===hash(report?.identity?.spec_material_hash);
+  // The report belongs to this packet and spec: its stages can be read. A
+  // spec edit since the report was bound does not unbind it; the edit makes
+  // the stamped stages owed, which their effective status reports. The
+  // doctor read must have assessed the same spec material this read sees.
+  const inputCurrency=doctor?.derived?.input_currency;
+  const stagesBound=doctor?.derived?.prepare_build_gate?.binding_failure!==true&&contextBound&&campaignIdentitiesMatch(packet?.spec,campaignSpecIdentity(spec))&&campaignIdentitiesMatch(packet?.spec,report?.identity)&&localHash&&(!inputCurrency||hash(inputCurrency.spec?.current)===localHash);
+  // The report is also bound to the spec material on disk now, so output and
+  // verdict evidence recorded against it can match.
+  const reportBound=stagesBound&&localHash===hash(report?.identity?.spec_material_hash);
   const qaSource=hash(report?.stages?.qa?.evidence?.source_build_fingerprint);
   const verdict=qaResult?.verdict;
   const qa=verdict?{
@@ -73,8 +82,11 @@ export function projectProgressObservation({workspace,context,report,doctor,cont
   return {
     schema_version:PROGRESS_SCHEMA_VERSION,package_version:packageVersion,producer:qaResult?'qa':'next',
     identity:{map_id:mapId,...localSpecIdentityFields(packet?.spec),map_revision_hash:mapId?(contextBound&&baseline?.map_id===mapId?hash(baseline?.hash):(localMapId===mapId?hash(spec?.spec_identity?.spec_hash||spec?.spec_hash):null)):null,map_revision_algorithm:'map-store-v1',saved_revision_alignment:aligned?'aligned':'unconfirmed',local_spec_material_hash:localHash,local_spec_material_algorithm:'campaign-spec-material-v1',build_fingerprint:build,build_fingerprint_algorithm:'sha256-manifest/v1'},
+    // Each stage's effective status: a stage owed again by a brief or
+    // CampaignSpec change reads required, one whose inputs cannot be
+    // confirmed reads unknown (src/input-currency.mjs).
     stages:PROGRESS_STAGES.map(stage=>{
-      const status=reportBound?accepted(report?.stages?.[stage]?.status,PROGRESS_STAGE_STATUSES):'unknown';
+      const status=stagesBound?accepted(effectiveStageStatus(stage,report?.stages?.[stage],inputCurrency),PROGRESS_STAGE_STATUSES):'unknown';
       const source=stage==='assembly'?recordedBuild:stage==='qa'?qaSource:null;
       return {stage,status,source_build_fingerprint:source,build_binding:reportBound&&build&&source===build&&doctor?.derived?.build_output_fingerprint?.status==='pass'?'matching':'unconfirmed'};
     }),
@@ -84,7 +96,7 @@ export function projectProgressObservation({workspace,context,report,doctor,cont
 }
 function lock(dir,fn,{budgetMs=1500}={}) {
   const lockPath=join(dir,'.allocation-lock');
-  return withDirectoryLock(lockPath,fn,{budgetMs,unavailable:()=>Object.assign(new Error('progress.lock_unavailable'),{lockPath})});
+  return withDirectoryLock(lockPath,fn,{budgetMs,unavailable:(error)=>Object.assign(new Error('progress.lock_unavailable'),{lockPath,code:error?.code,obstruction:error?.obstruction})});
 }
 export async function persistProgressObservation(observation,{dir,now=()=>new Date(),historyLimit=32}={}) {
   mkdirSync(dir,{recursive:true,mode:0o700});
@@ -152,7 +164,8 @@ export async function observeProgress(args,continuation,{qaResult=null,packageVe
     if(remit.state==='failed')warn('[campaigns-os] Progress delivery pending; the local observation is retained. Lifecycle result is unchanged.');
     return {...remit,snapshot_id:snapshot.snapshot_id,reused};
   } catch(error) {
-    if(error?.message==='progress.lock_unavailable')warn(`[campaigns-os] Progress allocation lock occupied${error.lockPath?` at ${error.lockPath}`:''}; wait for the current writer. If it stays occupied (an abandoned, ownerless or interrupted lock), stop all campaigns-os writers for this target, then remove that lock directory (docs/progress-snapshots.md). Lifecycle result is unchanged.`);
+    if(error?.message==='progress.lock_unavailable'&&error.obstruction)warn(`[campaigns-os] Progress allocation lock path ${error.lockPath} is occupied by ${error.obstruction}; it is never removed automatically. Move it out of the way. Lifecycle result is unchanged.`);
+    else if(error?.message==='progress.lock_unavailable')warn(`[campaigns-os] Progress allocation lock occupied${error.lockPath?` at ${error.lockPath}`:''}; wait for the current writer. If it stays occupied (an abandoned, ownerless or interrupted lock), stop all campaigns-os writers for this target, then remove that lock directory (docs/progress-snapshots.md). Lifecycle result is unchanged.`);
     else warn('[campaigns-os] Progress observation unavailable; lifecycle result is unchanged.');
     return {state:'failed',reason:'capture_unavailable'};
   }

package/src/qa-browser.mjs

@@ -6,6 +6,8 @@ const PACKAGE_ROOT = installModeResolve(installModeDirname(installModeFileUrl(im
 import { createHash } from "node:crypto";
 import { runWithDeadline } from "./deadline.mjs";
 import { PLACEHOLDER_TEXT_ASSERTION_SUFFIX, SEVERITY, STATUS } from "./qa-verdict.mjs";
+import { contrastToolkit } from "./contrast.mjs";
+import { generatedTextRenders } from "./polish-readability.mjs";
 import {
   analyticsCaptureError,
   projectAnalyticsCaptureError,
@@ -75,6 +77,22 @@ const DEFAULT_TEST_CARD = "6011111111111117";
 const DEFAULT_TEST_CVV = "123";
 const DEFAULT_TEST_EXP_MONTH = "12";
 const DEFAULT_TEST_EXP_YEAR = "2030";
+// The card number and CVV iframes, matched by id prefix because each id ends
+// in a per-load suffix. SDK 0.4.40 and earlier mount Spreedly's iFrame v1
+// (spreedly-number-frame-1234); 0.4.41 mounts the Spreedly Checkout SDK fields
+// that NEXT's payments.29next.com/js/v1/payment.js loads
+// (spreedly-hosted-number-oujmii2uzjk). A page carries one generation or the
+// other, and each frame holds a single text input. fillPaymentFields refuses
+// by name unless exactly one number frame and one CVV frame match, so a page
+// mounting both generations, or two forms, fails at the card step instead of
+// on whichever frame happens to come first.
+const CARD_NUMBER_FRAME = 'iframe[id^="spreedly-number-frame"], iframe[id^="spreedly-hosted-number"]';
+const CARD_CVV_FRAME = 'iframe[id^="spreedly-cvv-frame"], iframe[id^="spreedly-hosted-cvv"]';
+// Typing the card is read back and retried this many times in all before the
+// card step fails by name.
+const CARD_TYPE_ATTEMPTS = 3;
+// How long the card step waits for the SDK to report the card fields ready.
+const CARD_READY_TIMEOUT_MS = 15000;
 const DEFAULT_MAX_TEST_ORDERS = 6;
 // Planned-path ids listed in a refused --max-test-orders message before the
 // remainder is counted rather than printed.
@@ -1300,9 +1318,7 @@ async function primaryCtaVisualAssertions(browserPage, page) {
 }
 
 function primaryCtaCheckEligible(page) {
-  if (!page?.expected_next_url) return false;
-  const pageType = String(page.page_type || "").toLowerCase();
-  return !["checkout", "upsell", "downsell", "thankyou", "receipt"].includes(pageType);
+  return Boolean(page?.expected_next_url);
 }
 
 // Candidate CTAs: anything clickable, plus every SDK action control and the
@@ -1314,10 +1330,12 @@ const PRIMARY_CTA_SELECTOR = ["a[href]", "button", "[role='button']", "[data-nex
 
 // The in-page half of the primary-CTA inspection, as the source text the
 // page evaluates. The route rule it needs (cartEntryHrefFor, unit-tested in
-// qa-cart-entry) is handed in as a function value rather than closed over, so
-// both function bodies must stay free of module-scope references: the text is
-// run in a fresh context by a test (primary-CTA inspection script is
-// self-contained) that would surface a leaked identifier as a ReferenceError.
+// qa-cart-entry), the shared contrast helper (contrastToolkit) and the
+// generated-text rule Polish reads (generatedTextRenders) are handed in as
+// function values rather than closed over, so every function body must
+// stay free of module-scope references: the text is run in a fresh context by
+// a test (primary-CTA inspection script is self-contained) that would surface
+// a leaked identifier as a ReferenceError.
 function primaryCtaInspectionScript(expectedUrl) {
   const args = {
     routeUrl: expectedUrl,
@@ -1326,7 +1344,7 @@ function primaryCtaInspectionScript(expectedUrl) {
     cartEntryRouteAttribute: CART_ENTRY_ROUTE_ATTRIBUTE,
     ignoredRouteAttributes: [...UNDECLARED_ROUTE_ATTRIBUTES],
   };
-  return `(${inspectPrimaryCtaScript.toString()})(${JSON.stringify(args)}, ${cartEntryHrefFor.toString()})`;
+  return `(${inspectPrimaryCtaScript.toString()})(${JSON.stringify(args)}, ${cartEntryHrefFor.toString()}, ${contrastToolkit.toString()}, ${generatedTextRenders.toString()})`;
 }
 
 async function inspectPrimaryCta(browserPage, expectedUrl) {
@@ -1340,8 +1358,9 @@ async function inspectPrimaryCta(browserPage, expectedUrl) {
   }));
 }
 
-function inspectPrimaryCtaScript({ routeUrl, ctaSelector, cartEntrySelector, cartEntryRouteAttribute, ignoredRouteAttributes }, hrefForImpl) {
+function inspectPrimaryCtaScript({ routeUrl, ctaSelector, cartEntrySelector, cartEntryRouteAttribute, ignoredRouteAttributes }, hrefForImpl, contrastToolkitImpl, generatedTextImpl) {
   const CTA_SELECTOR = ctaSelector;
+  const toolkit = contrastToolkitImpl();
 
   const trim = (value) => String(value || "").replace(/\s+/g, " ").trim();
   const compactPath = (value) => String(value || "").replace(/\/+$/, "") || "/";
@@ -1352,42 +1371,6 @@ function inspectPrimaryCtaScript({ routeUrl, ctaSelector, cartEntrySelector, car
       return null;
     }
   })();
-  const parseColor = (value) => {
-    const raw = String(value || "").trim().toLowerCase();
-    if (!raw || raw === "transparent") return null;
-    const rgb = raw.match(/^rgba?\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})(?:\s*,\s*(\d?(?:\.\d+)?|1(?:\.0+)?))?\s*\)$/);
-    if (!rgb) return null;
-    const parts = rgb.slice(1, 4).map((part) => Number(part));
-    if (parts.some((part) => !Number.isFinite(part) || part < 0 || part > 255)) return null;
-    const alpha = rgb[4] === undefined ? 1 : Number(rgb[4]);
-    return { r: parts[0], g: parts[1], b: parts[2], a: Number.isFinite(alpha) ? alpha : 1 };
-  };
-  const hex = (color) => color ? `#${[color.r, color.g, color.b].map((part) => Math.round(part).toString(16).padStart(2, "0")).join("")}` : null;
-  const luminance = (color) => {
-    const channel = (value) => {
-      const normalized = value / 255;
-      return normalized <= 0.03928 ? normalized / 12.92 : ((normalized + 0.055) / 1.055) ** 2.4;
-    };
-    return 0.2126 * channel(color.r) + 0.7152 * channel(color.g) + 0.0722 * channel(color.b);
-  };
-  const contrast = (a, b) => {
-    if (!a || !b) return null;
-    const light = Math.max(luminance(a), luminance(b));
-    const dark = Math.min(luminance(a), luminance(b));
-    return Math.round(((light + 0.05) / (dark + 0.05)) * 100) / 100;
-  };
-  const effectiveBackground = (element) => {
-    let current = element;
-    while (current && current.nodeType === Node.ELEMENT_NODE) {
-      const style = getComputedStyle(current);
-      const color = parseColor(style.backgroundColor);
-      if (color && color.a > 0.05) {
-        return { color, source: current === element ? "element" : current.tagName.toLowerCase() };
-      }
-      current = current.parentElement;
-    }
-    return { color: { r: 255, g: 255, b: 255, a: 1 }, source: "assumed_canvas" };
-  };
   const isVisible = (element) => {
     const rect = element.getBoundingClientRect();
     const style = getComputedStyle(element);
@@ -1440,56 +1423,124 @@ function inspectPrimaryCtaScript({ routeUrl, ctaSelector, cartEntrySelector, car
   // per-element detail for the listed candidates only.
   const ignoredAttributes = Array.from(new Set(visibleElements.flatMap(ignoredAttributesOn))).sort();
 
-  const candidates = visibleElements
+  // A route candidate's text, read through the shared contrast helper: each
+  // text-bearing element inside it is compared, unrounded, with the
+  // requirement for its own size. An element with a review trigger (or with
+  // no ratio to compare) is a review member and is not compared; an element
+  // whose control is disabled or loading has no colours read. Text whose
+  // control is disabled is inactive: it is not rendered text the check can
+  // read, so it never counts toward text_rendered or toward a pass. A
+  // disabled candidate is not measured at all, whatever text it generates,
+  // and never counts toward a pass. In an enabled candidate, text an element
+  // inside it generates through ::before or ::after (generatedTextImpl) is
+  // never measured, so the candidate is reviewed, never passed on its other
+  // text.
+  const measureCandidate = (element) => {
+    if (element.matches(":disabled, [aria-disabled=\"true\"]")) {
+      return { disabled: true, text_rendered: null, control_loading: null, contrast_ratio: null, elements: [], below: false, review: false, measured: false, inactive: false };
+    }
+    // Every element the page renders inside the candidate: its own subtree,
+    // open shadow roots included.
+    const subtree = toolkit.flatSubtree(element);
+    const reads = subtree
+      .filter((node) => toolkit.isTextBearing(node, window))
+      .map((node) => toolkit.measureTextElement(node, window));
+    const compared = [];
+    let review = subtree.some((node) => generatedTextImpl(node, window));
+    for (const read of reads) {
+      if (read.disabled || read.control_loading) continue;
+      if (read.review_reason !== null || typeof read.ratio !== "number") review = true;
+      else compared.push(read);
+    }
+    const ratios = compared.map((read) => read.ratio);
+    return {
+      disabled: false,
+      text_rendered: reads.some((read) => !read.disabled),
+      control_loading: reads.some((read) => read.control_loading),
+      contrast_ratio: ratios.length ? toolkit.displayRatio(Math.min(...ratios)) : null,
+      elements: reads.map((read) => ({
+        selector_path: read.selector_path,
+        contrast_ratio_exact: read.ratio,
+        required_ratio: read.required,
+        size_class: read.size_class,
+        review_reason: read.review_reason,
+      })),
+      below: compared.some((read) => !toolkit.meetsRequirement(read.ratio, read.required)),
+      review,
+      measured: compared.length > 0,
+      inactive: reads.some((read) => read.disabled),
+    };
+  };
+
+  // Route candidates carry their measurement; other rows are listed for the
+  // route-recognition view only and are not measured.
+  const verdicts = new Map();
+  const rows = visibleElements
     .map((element) => {
       const rect = element.getBoundingClientRect();
-      const style = getComputedStyle(element);
-      const fg = parseColor(style.color);
-      const bg = effectiveBackground(element);
-      const ratio = contrast(fg, bg.color);
       const href = hrefFor(element);
       const label = trim(element.innerText || element.textContent || element.getAttribute("aria-label"));
       return {
-        selector: selectorFor(element),
-        text: label.slice(0, 120),
-        href,
-        route_matches: routeMatches(href),
-        ignored_attributes: ignoredAttributesOn(element),
-        width: Math.round(rect.width),
-        height: Math.round(rect.height),
-        foreground: hex(fg),
-        background: hex(bg.color),
-        background_source: bg.source,
-        contrast_ratio: ratio,
-        readable: typeof ratio === "number" && ratio >= 4.5,
-        size_ok: rect.width >= 40 && rect.height >= 20,
+        element,
+        row: {
+          selector: selectorFor(element),
+          text: label.slice(0, 120),
+          href,
+          route_matches: routeMatches(href),
+          ignored_attributes: ignoredAttributesOn(element),
+          width: Math.round(rect.width),
+          height: Math.round(rect.height),
+          size_ok: rect.width >= 40 && rect.height >= 20,
+        },
       };
     })
-    .filter((candidate) => candidate.text || candidate.href);
-
-  const routeCandidates = candidates
-    .filter((candidate) => candidate.route_matches)
-    .sort((a, b) => {
-      if (a.readable !== b.readable) return a.readable ? -1 : 1;
-      if (a.size_ok !== b.size_ok) return a.size_ok ? -1 : 1;
-      return (b.contrast_ratio || 0) - (a.contrast_ratio || 0);
+    .filter(({ row }) => row.text || row.href)
+    .map(({ element, row }) => {
+      if (!row.route_matches) return { ...row, disabled: null, text_rendered: null, control_loading: null, contrast_ratio: null, elements: null };
+      const { below, review, measured, inactive, ...read } = measureCandidate(element);
+      const candidate = { ...row, ...read };
+      verdicts.set(candidate, { below, review, measured, inactive });
+      return candidate;
     });
-  const primary = routeCandidates[0] || null;
-  const ok = Boolean(primary?.readable && primary?.size_ok);
-  const reason = ok
-    ? "ok"
-    : !routeCandidates.length
-      ? "missing_route_cta"
-      : primary?.size_ok === false
-        ? "cta_too_small"
-        : "low_contrast";
+
+  // Every route candidate counts, in document order; none is preferred.
+  // The page outcome is the first that applies. An enabled candidate whose
+  // only text is inactive (its control is disabled) has no rendered text;
+  // cta_disabled is only for every candidate disabled. The page passes only
+  // when every enabled candidate had at least one element compared, so text
+  // that was skipped never stands in for a measurement.
+  const routeCandidates = rows.filter((candidate) => candidate.route_matches);
+  const enabled = routeCandidates.filter((candidate) => !candidate.disabled);
+  const measurability = routeCandidates.length ? toolkit.documentMeasurability(document) : { measurable: true };
+  const reason = !routeCandidates.length
+    ? "missing_route_cta"
+    : !measurability.measurable
+      ? measurability.reason
+      : enabled.some((candidate) => verdicts.get(candidate).below)
+        ? "low_contrast"
+        : !routeCandidates.some((candidate) => candidate.size_ok)
+          ? "cta_too_small"
+          : enabled.some((candidate) => !candidate.text_rendered)
+            ? "text_not_rendered"
+            : enabled.some((candidate) => candidate.control_loading)
+              ? "control_loading"
+              : enabled.some((candidate) => verdicts.get(candidate).review)
+                ? "contrast_review"
+                : !enabled.length || enabled.some((candidate) => !verdicts.get(candidate).measured)
+                  ? "cta_disabled"
+                  : "ok";
+
+  // Rows are capped at eight, except that every route candidate is listed.
+  const listed = [];
+  for (const row of rows) if (row.route_matches || listed.length < 8) listed.push(row);
 
   return {
-    ok,
+    ok: reason === "ok",
     reason,
     expected_url: routeUrl,
-    primary,
-    candidates: candidates.slice(0, 8),
+    // The first route candidate in document order, for display only.
+    primary: routeCandidates[0] || null,
+    candidates: listed,
     // Every route-shaped attribute seen on a visible CTA-shaped element and
     // not consulted (see above), so a missing-route verdict on a page spelled
     // that way reads as a vocabulary gap, not as a removed CTA.
@@ -1497,8 +1548,20 @@ function inspectPrimaryCtaScript({ routeUrl, ctaSelector, cartEntrySelector, car
   };
 }
 
+// The outcomes the page itself earns as a failure. Every other outcome that
+// is not a pass could not be observed completely (the page was not
+// measurable, text or a control was not ready, a review trigger, every CTA
+// disabled, or an inspection the page rejected): manual review, never a pass
+// and never a contrast failure.
+const PRIMARY_CTA_FAIL_REASONS = Object.freeze([
+  "missing_route_cta",
+  "low_contrast",
+  "cta_too_small",
+]);
+
 function primaryCtaAssertionFromEvidence(page, evidence) {
   const ok = evidence?.ok === true;
+  const review = !ok && !PRIMARY_CTA_FAIL_REASONS.includes(evidence?.reason);
   const ignored = Array.isArray(evidence?.ignored_attributes) ? evidence.ignored_attributes.filter(Boolean) : [];
   // Named on every verdict the page earns, passing or not: a passing page
   // spelled with an undeclared route attribute is still one an operator
@@ -1509,7 +1572,7 @@ function primaryCtaAssertionFromEvidence(page, evidence) {
     id: `browser-primary-cta:${page.page_id}`,
     family: "browser-runtime",
     page,
-    status: ok ? STATUS.PASS : STATUS.FAIL,
+    status: ok ? STATUS.PASS : review ? STATUS.MANUAL_REVIEW : STATUS.FAIL,
     severity: ok ? undefined : SEVERITY.WARN,
     expected: "visible readable primary CTA linked to the expected next route",
     actual: ok
@@ -3821,7 +3884,7 @@ async function executeTestOrderPath({ page, events, email, ladder, checkoutPage,
     }, { timeoutMs: budget() });
     await ladder.run("card_fields_filled", async () => {
       ensurePageFillable(page, checkoutPage.url);
-      await fillPaymentFields(page, args);
+      return fillPaymentFields(page, args);
     }, { timeoutMs: budget() });
     await ladder.run("cart_created", async () => {
       const cart = cartCreationEvidence(events);
@@ -5036,14 +5099,69 @@ async function fillPaymentFields(page, args) {
 
   const card = normalizeCard(stringArg(args["test-card"]) || DEFAULT_TEST_CARD);
   const cvv = stringArg(args["test-cvv"]) || DEFAULT_TEST_CVV;
-  const numberInput = page.frameLocator('iframe[id^="spreedly-number-frame"]').locator("input").first();
-  const cvvInput = page.frameLocator('iframe[id^="spreedly-cvv-frame"]').locator("input").first();
-  await numberInput.click();
-  await numberInput.pressSequentially(card, { delay: 20 });
-  await cvvInput.click();
-  await cvvInput.pressSequentially(cvv, { delay: 20 });
-  await page.locator("body").click({ position: { x: 20, y: 20 } }).catch(() => {});
-  await page.waitForTimeout(500);
+  const frames = await cardFrames(page);
+  const readyWaitMs = await waitForCardFieldsReady(page);
+  const numberInput = page.frameLocator(CARD_NUMBER_FRAME).locator("input").first();
+  const cvvInput = page.frameLocator(CARD_CVV_FRAME).locator("input").first();
+  const typed = async (input) => normalizeCard(await input.inputValue());
+  let attempts = 0;
+  let held = null;
+  while (attempts < CARD_TYPE_ATTEMPTS) {
+    attempts++;
+    if (attempts > 1) {
+      await numberInput.fill("");
+      await cvvInput.fill("");
+    }
+    await numberInput.click();
+    await numberInput.pressSequentially(card, { delay: 20 });
+    await cvvInput.click();
+    await cvvInput.pressSequentially(cvv, { delay: 20 });
+    await page.locator("body").click({ position: { x: 20, y: 20 } }).catch(() => {});
+    await page.waitForTimeout(500);
+    held = { number: await typed(numberInput), cvv: await typed(cvvInput) };
+    if (held.number === card && held.cvv === normalizeCard(cvv)) {
+      return { evidence: { ...frames, ready_wait_ms: readyWaitMs, attempts } };
+    }
+  }
+  throw new Error(`card fields did not keep the typed card after ${attempts} attempts: number field holds ${held.number.length} digit(s) ending ${held.number.slice(-4) || "(empty)"} (typed ${card.length} ending ${card.slice(-4)}), CVV field holds ${held.cvv.length} digit(s)`);
+}
+
+// Typing into the card fields before the SDK reports them ready can lose
+// keystrokes: on SDK 0.4.41 the Spreedly-hosted number input exists before
+// its script has loaded, and digits typed in that window are dropped (seen
+// as a number missing its leading digits, which the SDK then refuses without
+// tokenizing, so the order never posts). The checkout form carries
+// next-loading-spreedly from before the card iframes mount until the fields
+// are ready, in 0.4.38 through 0.4.41, so wait for it to clear. A page whose
+// SDK never set it is ready at once. The SDK also clears it when the card
+// script fails to load, so a class still set after the wait means the card
+// script never answered; the step refuses by name rather than type into
+// fields that may drop the number.
+async function waitForCardFieldsReady(page) {
+  const started = Date.now();
+  await page.waitForFunction(() => !document.querySelector(".next-loading-spreedly"), null, { timeout: CARD_READY_TIMEOUT_MS }).catch((error) => {
+    if (error?.name !== "TimeoutError") throw error;
+    throw new Error(`card fields did not report ready within ${CARD_READY_TIMEOUT_MS / 1000}s: the checkout form still carries next-loading-spreedly, so the card script never finished loading`);
+  });
+  return Date.now() - started;
+}
+
+// The card iframes the step is about to type into, once the SDK has mounted
+// them. Exactly one of each, of one generation, or the step fails by name.
+async function cardFrames(page) {
+  await page.locator(CARD_NUMBER_FRAME).first().waitFor({ state: "attached" });
+  await page.locator(CARD_CVV_FRAME).first().waitFor({ state: "attached" });
+  const ids = async (selector) => page.locator(selector).evaluateAll((nodes) => nodes.map((node) => node.id));
+  const number = await ids(CARD_NUMBER_FRAME);
+  const cvv = await ids(CARD_CVV_FRAME);
+  const all = [...number, ...cvv];
+  const generation = all.every((id) => id.startsWith("spreedly-hosted-"))
+    ? "spreedly-hosted"
+    : all.every((id) => /^spreedly-(number|cvv)-frame/.test(id)) ? "spreedly-iframe-v1" : "mixed";
+  if (number.length !== 1 || cvv.length !== 1 || generation === "mixed") {
+    throw new Error(`expected one card number iframe and one CVV iframe of one generation; found number=[${number.join(", ")}] cvv=[${cvv.join(", ")}]`);
+  }
+  return { generation, number_frame_id: number[0], cvv_frame_id: cvv[0] };
 }
 
 async function clickCreditPaymentMethod(page) {

package/src/qa-node.mjs

@@ -2,6 +2,7 @@ import { campaignSpecIdentity, resolveCampaignIdentity, campaignIdentitiesMatch
 import { applyLocalPreviewToCheckpoint, applyLocalPreviewToPolishGate, carriedForwardMessage, CARRIED_FORWARD, 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";
 import { applyQaBuildScope, specForQaScope } from "./qa-build-scope.mjs";
 import { requiredActionText } from "./gate-actions.mjs";
 import { parseOrderPathDepthFlag } from "./proof-policy.mjs";
@@ -167,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
@@ -468,6 +471,9 @@ async function resolveQaInputs(args, {
     routeRootNote: routeRootNotes[0] || null,
   });
   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.
+  const sourceBriefMaterial = packet ? currentBriefMaterial({ packet, packetPath }) : null;
   const templateFamily = stringArg(packet?.assembly?.template_family)
     || stringArg(normalized?.spec_identity?.preferred_template_family)
     || stringArg(normalized?.campaign?.preferred_template_family)
@@ -524,6 +530,7 @@ async function resolveQaInputs(args, {
     spec: normalized,
     specVersion: String(rawSpec.schema_version || rawSpec.schemaVersion || "unknown"),
     specHash,
+    sourceBriefMaterial,
     templateFamily,
     commerceStructureContract,
     topologies: qaScope.topologies,
@@ -583,7 +590,7 @@ function resolvePacketCheckpointPreflight(args, {
   }
   if (packet?.spec?.local_spec_id != null && (!reportMatchesPacketIdentity(report, packet)
     || (specStatus === "ok" && !specHashesMatch(report.identity?.spec_material_hash, computeSpecHash(rawSpec))))) {
-    throw new Error("Local-spec QA requires the matching Assembly Report and current spec material hash. Re-run prepare-build after a material revision; do not reuse foreign or stale proof.");
+    throw new Error("Local-spec QA requires the matching Assembly Report and current spec material hash. Run `record spec` after a material revision (it keeps stage history); do not reuse foreign or stale proof.");
   }
   const checkpointGates = [
     evaluatePageKitStoreProfile({
@@ -1585,6 +1592,12 @@ function reportPathField(resolved) {
   return reportPath ? { report_path: reportPath } : {};
 }
 
+// The verdict with the brief material qa run bound at run start, when the
+// run had a packet to bind it from.
+function withSourceBriefMaterial(verdict, sourceBriefMaterial) {
+  return sourceBriefMaterial ? { ...verdict, source_brief_material: sourceBriefMaterial } : verdict;
+}
+
 function resolvePayload(resolved, { routeProbe = null } = {}) {
   const entryUrls = deriveEntryUrls(resolved.topologies);
   const pageUrls = derivePageUrls(resolved.topologies);
@@ -2598,7 +2611,7 @@ async function finalizeQaRun({ args, resolved, runId, startedAt, assertions, tes
   // The verdict as it is persisted: the local file, the committed sidecar and
   // the published copy all read this one projection (no URL query in any
   // string or key), whichever runner, return path or field produced a value.
-  const verdict = redactPersisted(createVerdict({
+  const verdict = redactPersisted(withSourceBriefMaterial(createVerdict({
     runId,
     mapId: resolved.mapId,
     localSpecId: resolved.localSpecId,
@@ -2619,7 +2632,7 @@ async function finalizeQaRun({ args, resolved, runId, startedAt, assertions, tes
     commercial,
     causeSummary,
     browser,
-  }));
+  }), resolved.sourceBriefMaterial));
 
   const validationErrors = validateVerdict(verdict);
   if (validationErrors.length) throw new Error(`QA verdict failed local validation:\n- ${validationErrors.join("\n- ")}`);
@@ -2657,7 +2670,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`);
   }
@@ -3461,6 +3474,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 {
@@ -3746,8 +3762,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" };
   }
@@ -3764,11 +3785,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: {