@nextcommerce/campaigns-os 1.55.0 → 1.57.0

package/src/qa-node.mjs

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

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/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/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,
@@ -687,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() });
     }
@@ -731,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();

package/src/stage-record.mjs

@@ -29,7 +29,7 @@ import { BRAND_LAYER_FILENAMES } from "./brand-theme.mjs";
 import { ADAPTER_DECISION_SCALAR_VALUES } from "./adapter-decision-contract.mjs";
 import { computeBuildFingerprint, resolveBuiltSiteScope } from "./built-site-scope.mjs";
 import { resolveCampaignWorkspace, targetRepoFor } from "./campaign-workspace.mjs";
-import { isObject, optionalString, readJsonIfExists, requireArg } from "./cli-helpers.mjs";
+import { isObject, optionalString, portableArtifactPaths, readJsonIfExists, requireArg } from "./cli-helpers.mjs";
 import { LOCAL_PROOF_BUILD_ENVIRONMENT, LOCAL_PROOF_PRODUCTION_ENVIRONMENT, isLocalServePacket } from "./local-proof.mjs";
 import { polishCarriedForwardForLadder } from "./local-preview-policy.mjs";
 import { isLoopbackHostname } from "./remit.mjs";
@@ -1017,8 +1017,8 @@ function recordUnderLock({ stage, packetPath, sidecars, lockedTarget, input, dry
     if (dryRun) return null;
     // Written inside the report's critical section, after every check and
     // before the report itself, so the files move together.
-    if (next.context) writeJsonAtomic(contextPath, next.context);
-    if (next.packet) writeJsonAtomic(packetPath, next.packet);
+    if (next.context) writeJsonAtomic(contextPath, portableArtifactPaths(next.context, workspace.targetRepo, { artifactPath: contextPath }));
+    if (next.packet) writeJsonAtomic(packetPath, portableArtifactPaths(next.packet, workspace.targetRepo, { artifactPath: packetPath }));
     return next.report;
   };
   // Already inside the target lock, which commitAssemblyReport re-enters.