@nextcommerce/campaigns-os 1.54.0 → 1.57.0

package/src/qa-test-order-topology.mjs

@@ -5,9 +5,126 @@ const ACTIONS = Object.freeze([
   ["accept", "expected_accept_url"],
 ]);
 
+// The page types of a checkout path, as pageType() spells them (lowercase, `_`
+// and `-` dropped). `checkout` is the page that takes payment; `select` and
+// `checkout_step` lead into it without placing an order (campaigns-os#641).
+const PAYMENT_PAGE_TYPE = "checkout";
+const PRE_PAYMENT_PAGE_TYPES = new Set(["select", "checkoutstep"]);
+
+export function isPaymentTopologyPage(page) {
+  return pageType(page) === PAYMENT_PAGE_TYPE;
+}
+
+export function isCheckoutStepTopologyPage(page) {
+  return pageType(page) === "checkoutstep";
+}
+
+// Follow forward links (expected_next_url) from `start` to the page that takes
+// payment. Null when the walk leaves the topology, loops, or reaches any page
+// that is neither a pre-payment page nor the Checkout.
+export function paymentPageFrom(topology, start) {
+  const pages = Array.isArray(topology?.pages) ? topology.pages : [];
+  const seen = new Set();
+  let page = start || null;
+  while (page && !seen.has(page)) {
+    seen.add(page);
+    if (isPaymentTopologyPage(page)) return page;
+    const key = canonicalHttpUrl(page.expected_next_url);
+    const next = key ? pages.find((candidate) => canonicalHttpUrl(candidate?.url) === key) : null;
+    if (!next) return null;
+    if (!isPaymentTopologyPage(next) && !PRE_PAYMENT_PAGE_TYPES.has(pageType(next))) return null;
+    page = next;
+  }
+  return null;
+}
+
+// The topology's entry pages: flagged is_entry, else those no page links to
+// (offer and receipt pages excluded: an orphaned upsell is not where a shopper
+// starts), else the first page. Never decided by page names.
+function topologyEntryPages(pages) {
+  const flagged = pages.filter((page) => page?.is_entry === true);
+  if (flagged.length) return flagged;
+  const targeted = new Set();
+  for (const page of pages) {
+    for (const field of ["expected_next_url", "expected_accept_url", "expected_decline_url"]) {
+      const key = canonicalHttpUrl(page?.[field]);
+      if (key && key !== canonicalHttpUrl(page?.url)) targeted.add(key);
+    }
+  }
+  const roots = pages.filter((page) => {
+    const key = canonicalHttpUrl(page?.url);
+    const type = pageType(page);
+    return !(key && targeted.has(key)) && !OFFER_PAGE_TYPES.has(type) && !RECEIPT_PAGE_TYPES.has(type);
+  });
+  return roots.length ? roots : pages.slice(0, 1);
+}
+
+// Every Checkout the topology's entry paths reach, in entry order, then any
+// Checkout no entry path reaches (a landing CTA into checkout declares no
+// forward field). "The first page typed checkout" is never the answer on its
+// own: on a multi-step path it is a step, and with split-test paths there are
+// several (campaigns-os#641).
+export function paymentPagesForTopology(topology) {
+  const pages = Array.isArray(topology?.pages) ? topology.pages : [];
+  const out = [];
+  for (const entry of topologyEntryPages(pages)) {
+    const checkout = paymentPageFrom(topology, entry);
+    if (checkout && !out.includes(checkout)) out.push(checkout);
+  }
+  for (const page of pages) if (isPaymentTopologyPage(page) && !out.includes(page)) out.push(page);
+  return out;
+}
+
+// The Checkout of the first entry path of the first topology that has one.
+export function findPaymentPage(topologies = []) {
+  for (const topology of Array.isArray(topologies) ? topologies : []) {
+    const page = paymentPagesForTopology(topology)[0];
+    if (page) return page;
+  }
+  return null;
+}
+
+// The pages a shopper passes through to reach `checkoutPage`, in order and
+// ending with it: an optional select page, then each checkout_step, then the
+// Checkout. Walks backwards over forward links, so it holds whichever path the
+// Checkout sits on; where two pages lead into the same page a checkout_step is
+// preferred over a select page, which can only start the chain.
+export function checkoutPathPages(topology, checkoutPage) {
+  const pages = Array.isArray(topology?.pages) ? topology.pages : [];
+  if (!checkoutPage) return [];
+  const chain = [checkoutPage];
+  const seen = new Set(chain);
+  let current = checkoutPage;
+  for (;;) {
+    const key = canonicalHttpUrl(current?.url);
+    if (!key) break;
+    const leading = pages.filter((page) => !seen.has(page)
+      && PRE_PAYMENT_PAGE_TYPES.has(pageType(page))
+      && canonicalHttpUrl(page?.expected_next_url) === key);
+    const previous = leading.find(isCheckoutStepTopologyPage) || leading[0] || null;
+    if (!previous) break;
+    chain.unshift(previous);
+    seen.add(previous);
+    if (!isCheckoutStepTopologyPage(previous)) break;
+    current = previous;
+  }
+  return chain;
+}
+
+// Only the checkout_step pages of that path, in order.
+export function checkoutStepPages(topology, checkoutPage) {
+  return checkoutPathPages(topology, checkoutPage).filter(isCheckoutStepTopologyPage);
+}
+
 export function resolveTestOrderTopology(topology = {}, checkoutPage = null) {
   const pages = Array.isArray(topology?.pages) ? topology.pages : [];
-  const checkout = checkoutPage || pages.find((page) => pageType(page) === "checkout") || null;
+  // A caller may hand in a select or checkout_step page; the path's Checkout is
+  // the page whose forward link leads to the offers. Starting from a step made
+  // its next step a `nonterminal_target` and hid every offer path.
+  const given = checkoutPage && !isPaymentTopologyPage(checkoutPage) && PRE_PAYMENT_PAGE_TYPES.has(pageType(checkoutPage))
+    ? paymentPageFrom(topology, checkoutPage) || checkoutPage
+    : checkoutPage;
+  const checkout = given || paymentPagesForTopology(topology)[0] || null;
   const pagesByUrl = new Map();
   for (const page of pages) {
     const key = canonicalHttpUrl(page?.url);

package/src/qa-verdict-discovery.mjs

@@ -13,7 +13,7 @@ import { resolveCampaignIdentity, localQaIdentifier } from "./spec-source-identi
 
 import { createHash } from "node:crypto";
 import { readdirSync, readFileSync, statSync } from "node:fs";
-import { dirname, join, relative, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { QA_OUTPUT_REL_PATH } from "./campaign-workspace.mjs";
 import { absentOrMalformed } from "./fs-identity.mjs";
 import { isPlainObject as isObject, normalizeString as optionalString } from "./repo-scan.mjs";
@@ -53,7 +53,8 @@ export function qaVerdictDir(root, identifier) {
 
 // The verdict paths the Assembly Report's qa stage records (any `*.json`
 // string under a path/file/verdict/output-named key, or inside outputs[] /
-// artifacts[] / qa), relative to the report unless absolute.
+// artifacts[] / qa), relative to the target root unless absolute. Older
+// report-relative hints remain readable.
 export function qaVerdictPathHints(report) {
   const paths = [];
   const visit = (value) => {
@@ -90,7 +91,8 @@ function sha256File(path) {
 }
 
 // Every verdict candidate for a campaign: the files the report records
-// (source "assembly_report", resolved against the report) and every `*.json`
+// (source "assembly_report", resolved against the report first, then the target)
+// and every `*.json`
 // under `qa-output/<identifier>/` beneath each root (source "qa_output").
 //   { path, repoRelPath, source, verdict, sha256, mtimeMs, identityMatch, trusted }
 // `verdict` is null for a recorded path that exists but is not a JSON object
@@ -141,8 +143,14 @@ export function* iterateQaVerdicts({ packet = null, report = null, reportPath =
   };
 
   const reportBase = reportPath ? dirname(resolve(reportPath)) : null;
+  const targetRoot = uniqueTargetRoot(roots, reportBase);
   for (const hint of qaVerdictPathHints(report)) {
-    const found = candidate(reportBase ? resolve(reportBase, hint) : hint, "assembly_report", null);
+    const reportRelative = (isAbsolute(hint) || reportBase)
+      ? candidate(isAbsolute(hint) ? hint : resolve(reportBase, hint), "assembly_report", null)
+      : null;
+    const found = reportRelative || (!isAbsolute(hint) && targetRoot
+      ? candidate(resolve(targetRoot, hint), "assembly_report", null)
+      : null);
     if (found) yield found;
   }
 
@@ -172,6 +180,15 @@ export function* iterateQaVerdicts({ packet = null, report = null, reportPath =
   }
 }
 
+function uniqueTargetRoot(roots, reportBase) {
+  for (let directory = reportBase; directory; directory = dirname(directory)) {
+    if (basename(directory) === ".campaign-runtime") return dirname(directory);
+    if (dirname(directory) === directory) break;
+  }
+  const candidates = [...new Set(roots.filter((root) => typeof root === "string" && root).map((root) => resolve(root)))];
+  return candidates.length === 1 ? candidates[0] : null;
+}
+
 export function discoverQaVerdicts(options = {}) {
   return [...iterateQaVerdicts(options)];
 }

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;

package/src/runtime-state-ignore.mjs

@@ -29,6 +29,7 @@ export const RUNTIME_STATE_IGNORED_PATHS = [
   ".campaign-runtime/workflow-findings.jsonl",
   ".campaign-runtime/run-records/",
   ".campaign-runtime/fetched-specs/",
+  ".campaign-runtime/progress/",
   ".campaign-runtime/polish-evidence/",
   ".campaign-runtime/evidence/",
   // Full QA verdicts carry live storefront URLs and order references; the
@@ -41,11 +42,12 @@ export const RUNTIME_STATE_IGNORED_PATHS = [
 
 // Entries the toolkit adds to an existing managed block when they are
 // missing from the file. The block is otherwise the operator's to edit, but
-// these name directories the toolkit itself fills with live URLs and order
-// references, so a target set up before the entry existed must gain it on the
-// next setup command rather than on the next accidental commit. An entry an
-// operator has placed anywhere else in the file counts as present.
-export const RUNTIME_STATE_REQUIRED_IGNORED_PATHS = ["qa-output/"];
+// these name directories the toolkit itself fills with campaign observations,
+// live URLs, or order references. A target set up before the entry existed
+// must gain it on the next setup command rather than on the next accidental
+// commit. An entry an operator has placed anywhere else in the file counts as
+// present.
+export const RUNTIME_STATE_REQUIRED_IGNORED_PATHS = ["qa-output/", ".campaign-runtime/progress/"];
 
 export const RUNTIME_STATE_IGNORE_BLOCK = [
   RUNTIME_STATE_IGNORE_MARKER,

package/src/sdk-markup.mjs

@@ -88,6 +88,7 @@ export const SDK_MARKUP_CODES = Object.freeze({
   WRONG_FIELD_NAME: { code: `${SDK_MARKUP}.wrong_field_name`, severity: "error" },
   MISSING_SELECTOR_ID_MATCH: { code: `${SDK_MARKUP}.missing_selector_id_match`, severity: "error" },
   ORPHANED_UPSELL_ACTION: { code: `${SDK_MARKUP}.orphaned_upsell_action`, severity: "error" },
+  RECEIPT_ORDER_ITEMS_CART_VISIBILITY: { code: `${SDK_MARKUP}.receipt_order_items_cart_visibility`, severity: "error" },
   DOUBLE_SELECTED: { code: `${SDK_MARKUP}.double_selected`, severity: "warning" },
   TEMPLATE_DOUBLE_BRACE: { code: `${SDK_MARKUP}.template_double_brace`, severity: "warning" },
   // Unknown data-next-* names are not a finding and carry no code: they are
@@ -122,6 +123,31 @@ export const TEMPLATE_CONTAINER_ATTRIBUTES = [
 // Elements that ARE a selector an add-to-cart button can link to by id.
 const SELECTOR_ATTRIBUTES = ["data-next-bundle-selector", "data-next-package-selector", "data-next-cart-selector", "data-next-upsell-selector"];
 
+function cartVisibilityCondition(entry) {
+  return ["data-next-hide", "data-next-show"]
+    .find((name) => referencesCartState(entry.attrs.get(name))) || null;
+}
+
+function referencesCartState(condition) {
+  const source = String(condition || "");
+  let outside = "";
+  let quote = null;
+  for (let at = 0; at < source.length; at += 1) {
+    const char = source[at];
+    if (quote) {
+      if (char === "\\") at += 1;
+      else if (char === quote) quote = null;
+      outside += " ";
+    } else if (char === "'" || char === '"' || char === "`") {
+      quote = char;
+      outside += " ";
+    } else {
+      outside += char;
+    }
+  }
+  return /(?:^|[^\w.])cart\.[A-Za-z_$][\w$]*/i.test(outside);
+}
+
 function attrs(node) {
   const map = new Map();
   for (const attr of node.attrs || []) map.set(attr.name.toLowerCase(), attr.value);
@@ -171,7 +197,7 @@ function describe(entry) {
  * `sdk_version` is the campaign's SDK pin, used when the page carries no
  * exact loader pin of its own.
  */
-export function scanPageMarkup({ page_id, file = null, content = "", sdk_version = null }) {
+export function scanPageMarkup({ page_id, file = null, content = "", sdk_version = null, page_type = null }) {
   const document = parse(String(content || ""));
   const where = file || page_id;
   const sdk = resolvePageSdkVersion(document, sdk_version);
@@ -183,6 +209,10 @@ export function scanPageMarkup({ page_id, file = null, content = "", sdk_version
   const selectorIds = new Set(); // ids of elements that are themselves a selector
   const templates = []; // { entry, sdkOwned }
   const referencedTemplateIds = new Set();
+  let receiptPage = String(page_type || "").trim().toLowerCase() === "receipt";
+  walkElements(document, ({ tag, attrs: a }) => {
+    if (tag === "meta" && a.get("name")?.toLowerCase() === "next-page-type" && a.get("content")?.trim().toLowerCase() === "receipt") receiptPage = true;
+  });
 
   walkElements(document, (entry) => {
     const { tag, attrs: a, ancestors } = entry;
@@ -217,6 +247,16 @@ export function scanPageMarkup({ page_id, file = null, content = "", sdk_version
         { tag, action: value }));
     }
 
+    if (receiptPage && a.has("data-next-order-items")) {
+      const holder = [entry, ...ancestors].find(cartVisibilityCondition);
+      if (holder) {
+        const conditionAttribute = cartVisibilityCondition(holder);
+        findings.push(finding("RECEIPT_ORDER_ITEMS_CART_VISIBILITY", page_id, where,
+          `${describe(entry)} on ${where} ${holder === entry ? "carries" : `is inside ${describe(holder)} with`} ${conditionAttribute}="${holder.attrs.get(conditionAttribute)}". After checkout the cart can be empty, so receipt order lines disappear. Remove the cart-state visibility condition from the order-items element and its ancestors.`,
+          { condition_attribute: conditionAttribute, condition: holder.attrs.get(conditionAttribute) }));
+      }
+    }
+
     const action = (a.get("data-next-action") || "").trim().toLowerCase();
     if (action === "add-to-cart") {
       addToCartButtons.push({ entry, selectorId: (a.get("data-next-selector-id") || "").trim() || null });

package/src/source-html-intake.mjs

@@ -4,7 +4,7 @@ import {
 } from "./source-html-manifest.mjs";
 // Built output of campaign-spec (same import shape as src/page-kit-sdk-version.mjs),
 // so build-time wiring and spec-time analysis share one edge resolver.
-import { declineRouteTarget, forwardRouteTarget } from "../campaign-spec/dist/index.js";
+import { checkoutPathFrom, declineRouteTarget, forwardRouteTarget, forwardTargetPage, isCheckoutStepPage } from "../campaign-spec/dist/index.js";
 import { isAbsoluteHttpUrl, normalizePageKitRoute, normalizePublicRouteSlug, stripPublicRoutePrefix } from "./route-identity.mjs";
 
 const CPK_PAGE_TYPES = new Set(["product", "checkout", "upsell", "receipt"]);
@@ -30,7 +30,7 @@ export function createSourceHtmlIntake({
   const mappings = matched.mappings.map((mapping) => {
     const specPage = pageById.get(mapping.page_id);
     if (!specPage || !mapping.path) return mapping;
-    const pageKit = pageKitProjectionForPage(specPage, { pageById, publicRouteSlug, outputDir });
+    const pageKit = pageKitProjectionForPage(specPage, { pageById, publicRouteSlug, outputDir, specPages: specPages || [] });
     projectionDecisions.push({
       id: `dec_page_kit_target_${specPage.id}`,
       stage: "prepare_build",
@@ -559,7 +559,7 @@ function addSpecHints(mapping, page) {
   if (variantLabels) mapping.variant_labels = variantLabels;
 }
 
-function pageKitProjectionForPage(page, { pageById, publicRouteSlug, outputDir }) {
+function pageKitProjectionForPage(page, { pageById, publicRouteSlug, outputDir, specPages = [] }) {
   const specRoute = publicRouteForPage(page);
   const relativeRoute = stripPublicRoutePrefix(specRoute, publicRouteSlug);
   const publicRoute = rootedCampaignRoute(relativeRoute, publicRouteSlug);
@@ -574,6 +574,7 @@ function pageKitProjectionForPage(page, { pageById, publicRouteSlug, outputDir }
   if (nextUrl) frontmatter.next_url = nextUrl;
   const declineUrl = declineUrlForPage(page, pageById, publicRouteSlug);
   if (declineUrl && declineUrl !== nextUrl) frontmatter.decline_url = declineUrl;
+  Object.assign(frontmatter, checkoutFlowFrontmatter(page, { specPages, pageById, publicRouteSlug }));
 
   return {
     target_path: targetPath,
@@ -586,6 +587,43 @@ function pageKitProjectionForPage(page, { pageById, publicRouteSlug, outputDir }
   };
 }
 
+// Multi-step checkout wiring (campaigns-os#641), for any page that leads into a
+// Checkout without being it: a select page, a checkout_step, or a landing page
+// whose forward links reach a Checkout.
+//   success_url  the Checkout's post-payment destination (its own next_url).
+//                The page's next-success-url meta tag carries it, because the
+//                SDK reads that tag for express orders placed on this page; an
+//                express order on step 1 must land on the first upsell, not on
+//                step 2. Forward navigation never uses that tag: a step form
+//                navigates by data-next-checkout-step, a select page by a link.
+//   step_number  on a checkout_step only: its position among the steps of its
+//                path, from 1, for the form's data-next-step-number.
+function checkoutFlowFrontmatter(page, { specPages, pageById, publicRouteSlug }) {
+  if (!page || page.type === "checkout") return {};
+  const path = checkoutPathFrom(specPages, page);
+  if (!path || path.length < 2) return {};
+  const out = {};
+  const successUrl = nextUrlForPage(path[path.length - 1], pageById, publicRouteSlug);
+  if (successUrl) out.success_url = successUrl;
+  if (isCheckoutStepPage(page)) out.step_number = checkoutStepNumber(page, specPages);
+  return out;
+}
+
+function checkoutStepNumber(page, specPages) {
+  let number = 1;
+  const seen = new Set([page]);
+  let current = page;
+  for (;;) {
+    const previous = specPages.find((candidate) => !seen.has(candidate)
+      && isCheckoutStepPage(candidate)
+      && forwardTargetPage(specPages, candidate) === current);
+    if (!previous) return number;
+    number += 1;
+    seen.add(previous);
+    current = previous;
+  }
+}
+
 function pageKitTargetPrompts(mappings) {
   const prompts = [];
   const byOutputPath = new Map();
@@ -664,12 +702,15 @@ function cpkPageTypeForSpecType(type) {
   if (type === "presell" || type === "landing") return "product";
   if (type === "thankyou" || type === "receipt") return "receipt";
   if (type === "upsell" || type === "downsell") return "upsell";
-  if (type === "checkout" || type === "select") return "checkout";
+  // select, checkout_step and checkout all render the SDK checkout surface
+  // (campaigns-os#641); only the Checkout places the order.
+  if (type === "checkout" || type === "checkout_step" || type === "select") return "checkout";
   return CPK_PAGE_TYPES.has(type) ? type : "product";
 }
 
 function defaultRouteForSpecType(type) {
   if (type === "thankyou" || type === "receipt") return "receipt/";
+  if (type === "checkout_step") return "checkout-step/";
   if (["presell", "landing", "checkout", "upsell", "downsell"].includes(type)) return `${type}/`;
   return `${type || "page"}/`;
 }
@@ -696,6 +737,7 @@ function pageMatchKeys(page, ordinal) {
   }
   if (page.type === "landing" || page.type === "presell") keys.add("index");
   if (page.type === "checkout") keys.add("checkout");
+  if (page.type === "checkout_step") keys.add("checkout-step");
   if (page.type === "upsell") keys.add("upsell");
   if (page.type === "downsell") keys.add("downsell");
   return [...keys];

package/src/stage-ledger.mjs

@@ -5,6 +5,7 @@ import { STATUS as QA_STATUS } from "./qa-verdict.mjs";
 import { assessInputCurrency, currentPacketInputs, effectiveStageStatus, effectiveStatusIsTerminal, wellFormedBriefMaterial } from "./input-currency.mjs";
 import { isPlainObject, normalizeString as optionalString } from "./repo-scan.mjs";
 import { withTargetLockSync } from "./target-lock.mjs";
+import { portableArtifactPaths } from "./cli-helpers.mjs";
 import {
   ASSEMBLY_REPORT_STAGE_KEYS,
   NEXT_STAGE_CONTRACTS,
@@ -541,14 +542,26 @@ export function qaGateEvidence(report, gate) {
   };
 }
 
+export function qaRecordedBuildFingerprint(report) {
+  return optionalString(report?.stages?.qa?.evidence?.qc_build_fingerprint)
+    || optionalString(report?.stages?.qa?.evidence?.source_build_fingerprint);
+}
+
+export function qaRecordedForCurrentBuild(report, buildFingerprint) {
+  const recorded = qaRecordedBuildFingerprint(report);
+  const current = optionalString(buildFingerprint);
+  return Boolean(recorded && current && recorded === current);
+}
+
 // `qaCurrency` is QA's read-time input currency
 // (derived.input_currency.stages.qa): while QA is owed again or its inputs
 // cannot be confirmed, no QA gate pass counts.
 export function qaGatePassedForCurrentBuild(report, gate, { buildFingerprint, qaCurrency = null }) {
   if (qaCurrency === "owed" || qaCurrency === "unknown") return false;
   const outcome = qaGateEvidence(report, gate);
-  const current = optionalString(buildFingerprint);
-  return Boolean(outcome && outcome.status === QA_STATUS.PASS && current && outcome.source_build_fingerprint === current);
+  return Boolean(outcome && outcome.status === QA_STATUS.PASS
+    && outcome.source_build_fingerprint === optionalString(buildFingerprint)
+    && qaRecordedForCurrentBuild(report, buildFingerprint));
 }
 
 /**
@@ -675,7 +688,7 @@ function commitAssemblyReportUnderLock(workspace, mutate, {
   const finish = () => {
     if (hasRefresh) {
       const doctor = refreshDoctor(outcome);
-      if (doctor !== null && doctor !== undefined) writeDoctorSidecar(doctorOutPath, doctor, { command: command.trim() });
+      if (doctor !== null && doctor !== undefined) writeDoctorSidecar(doctorOutPath, doctor, { command: command.trim(), targetRepo });
     } else if (outcome.written) {
       markDoctorSidecarStale(targetRepo, { command: command.trim(), reason: staleReason.trim() });
     }
@@ -719,7 +732,8 @@ function commitAssemblyReportUnderLock(workspace, mutate, {
   // (every mutator in this repo returns a copy), so the restatement is in
   // place rather than a second deep clone. Stages are read at their effective
   // status against the inputs the workspace's packet names now.
-  const next = applyDerivedAssemblyReportSummary(mutated, workspaceInputs(workspace));
+  const nextReport = applyDerivedAssemblyReportSummary(mutated, workspaceInputs(workspace));
+  const next = targetRepo ? portableArtifactPaths(nextReport, targetRepo, { artifactPath: reportPath }) : nextReport;
   if (stage && producerStageOutcomeUnchanged(report, next, stage)) {
     outcome.skipped = "unchanged";
     return finish();