@nextcommerce/campaigns-os 1.54.0 → 1.57.0

package/src/commercial-journey.mjs

@@ -11,6 +11,7 @@
  */
 
 import { specHashOf, specHashesMatch } from "./spec-hash.mjs";
+import { CHECKOUT_FLOW_PAGE_TYPES, upgradeCampaignSpec } from "../campaign-spec/dist/index.js";
 
 export const CALC_LABEL = "Campaigns-calculated · before tax";
 export const CALCULATED_PAIR_EVIDENCE = "calculated_pair";
@@ -213,6 +214,20 @@ function catalogImportedAt(mapDoc) {
     ?? null;
 }
 
+// The page's type in the v5 vocabulary: a v4 Map's `checkout → checkout` chain
+// reads as `checkout_step` pages ahead of the one Checkout (campaigns-os#641).
+const upgradedMaps = new WeakMap();
+function v5PageType(mapDoc, page) {
+  if (!mapDoc || typeof mapDoc !== "object") return page?.type ?? null;
+  if (!upgradedMaps.has(mapDoc)) upgradedMaps.set(mapDoc, upgradeCampaignSpec(mapDoc));
+  const upgraded = upgradedMaps.get(mapDoc);
+  for (const funnel of array(upgraded?.funnels)) {
+    const hit = array(funnel?.pages).find((candidate) => present(page?.id) && String(candidate?.id) === String(page.id));
+    if (hit) return hit.type ?? null;
+  }
+  return page?.type ?? null;
+}
+
 function descriptor(page, mapDoc, role, lines, options = {}) {
   const funnel = findFunnel(mapDoc, page);
   const suffix = options.id_suffix ? `:${options.id_suffix}` : "";
@@ -221,7 +236,7 @@ function descriptor(page, mapDoc, role, lines, options = {}) {
     upsell: page?.type === "upsell" || page?.type === "downsell",
     context: {
       page_id: page?.id ?? null,
-      page_type: page?.type ?? null,
+      page_type: v5PageType(mapDoc, page),
       page_label: page?.label ?? page?.name ?? page?.id ?? null,
       page_order: Number(page?.order) || 0,
       funnel_id: funnel?.id ?? null,
@@ -1045,8 +1060,16 @@ function acceptDelta(page) {
   return moneyFact(signedCents(cents), total.state);
 }
 
+// The checkout total is the cart the shopper pays for at the Checkout. That cart
+// is priced on whichever checkout-flow page carries it: the select page of a
+// two-step flow, the first step of a split checkout, or the Checkout itself
+// (campaigns-os#641). The Checkout of a multi-step path carries no packages, so
+// looking for the page typed "checkout" priced nothing on those flows. Only
+// pages that declare packages are planned, so every page here carries a cart;
+// pages arrive sorted by page_order, and with several paths the first is
+// summarized.
 function journeySummary(pages) {
-  const checkout = pages.find((page) => page.page_type === "checkout");
+  const checkout = pages.find((page) => CHECKOUT_FLOW_PAGE_TYPES.includes(page.page_type));
   const checkoutTotal = checkout?.representative_total
     || unresolvedFact("Unresolved: checkout scenario unavailable");
   const bumps = pages.flatMap((page) => page.bumps.map((bump) => ({ ...bump, page_id: page.page_id })));

package/src/consent.mjs

@@ -14,6 +14,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { timeOperatorWait } from "./lifecycle.mjs";
 
 export const TELEMETRY_ENV_VAR = "CAMPAIGNS_OS_TELEMETRY";
 export const TELEMETRY_CONFIG_SCHEMA = "campaigns-os-telemetry-config/v0";
@@ -337,9 +338,9 @@ export async function promptAndPersistConsent({
   if (existing.resolved) return { ...existing, prompted: false };
   if (!isTTY) return { state: "off", source: "default", resolved: false, prompted: false };
 
-  const answer = await ask(
+  const answer = await timeOperatorWait(() => ask(
     "Campaigns OS can send build telemetry and minimal stage observations to Next Commerce to improve templates, tools, and guidance; stage observations support Workspace progress. Share telemetry from this machine? [Y/n] (change any time): ",
-  );
+  ));
   const normalized = String(answer || "").trim().toLowerCase();
   const state = (normalized === "" || ["y", "yes", "1", "true", "on"].includes(normalized)) ? "on" : "off";
   writeConsentConfig(state, { configPath, proxyBase, source: "prompt", now });

package/src/design-source-package.mjs

@@ -2085,7 +2085,7 @@ function sourceReferenceKindForManifestFile(file) {
 function normalizedPageRole(type) {
   const normalized = slugify(type || "page");
   if (["landing", "product", "presell", "advertorial"].includes(normalized)) return "landing";
-  if (["checkout", "select", "cart"].includes(normalized)) return "checkout";
+  if (["checkout", "checkout-step", "checkout_step", "select", "cart"].includes(normalized)) return "checkout";
   if (["upsell", "oto", "one-time-offer"].includes(normalized)) return "upsell";
   if (["downsell", "downsell-offer"].includes(normalized)) return "downsell";
   if (["receipt", "thank-you", "thankyou", "confirmation"].includes(normalized)) return "receipt";

package/src/design-source-publication.mjs

@@ -4,7 +4,7 @@ import { randomUUID } from "node:crypto";
 import { accessSync, constants as fsConstants, existsSync, linkSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { writeThemeArtifacts } from "./brand-theme.mjs";
-import { cloneJson, filesystemPathsMatch, isObject, isNonEmptyString, optionalString, readJson, resolveFromFile, sha256File } from "./cli-helpers.mjs";
+import { cloneJson, filesystemPathsMatch, isObject, isNonEmptyString, optionalString, portableArtifactPaths, readJson, resolveFromFile, sha256File } from "./cli-helpers.mjs";
 import { DESIGN_SOURCE_PACKAGE_REL_PATH, createDesignSourcePackageArtifactReference, hashSerializedDesignSourcePackage, serializeDesignSourcePackage, synthesizeHtmlFunnelDesignSourcePackage, validateDesignSourcePackage } from "./design-source-package.mjs";
 import { stampDoctorProducer } from "./doctor-sidecar.mjs";
 import { stageWriteInputs } from "./input-currency.mjs";
@@ -21,7 +21,7 @@ import { resolveTemplateFamilyDesignSource } from "./template-reference.mjs";
 // states never count as accumulated agent evidence. setup's seed state may
 // legitimately be "skipped" (scaffold already present); every other stage is
 // seeded "pending" with empty ledger arrays.
-function assemblyReportStagesWithEvidence(existingReport) {
+export function assemblyReportStagesWithEvidence(existingReport) {
   const stages = existingReport?.stages;
   if (!isObject(stages)) return [];
   const withEvidence = [];
@@ -69,7 +69,7 @@ function guardAssemblyReportOverwrite(reportPath, args, { announced = null } = {
     throw new Error(
       `Assembly report at ${reportPath} ${announced ? "gained stage evidence while prepare-build was running" : "already carries stage evidence"} (${stageKeys.join(", ")}). `
       + `Rerunning prepare-build/start/build would reset ${stageKeys.length === 1 ? "this stage" : "these stages"} to pending and destroy that evidence. `
-      + `Pass --force to overwrite (destructive).`,
+      + `If the brief or CampaignSpec changed, run record brief or record spec instead to bind it while keeping that evidence. Pass --force only to overwrite (destructive).`,
     );
   }
   const unannounced = announced ? stageKeys.filter((key) => !announced.includes(key)) : stageKeys;
@@ -979,10 +979,10 @@ export async function withDesignSourcePublication({ targetRepo, outputs, force =
             : [],
         );
         publishPrepareBuildJsonOutputs([
-          { label: "Build Packet", path: packetPath, value: packet },
-          { label: "Campaign Build Brief", path: briefPath, value: brief },
-          { label: "Build Context", path: contextPath, value: context },
-          { label: "Assembly Report", path: reportPath, value: report },
+          { label: "Build Packet", path: packetPath, value: portableArtifactPaths(packet, targetRepo, { artifactPath: packetPath }) },
+          { label: "Campaign Build Brief", path: briefPath, value: portableArtifactPaths(brief, targetRepo, { artifactPath: briefPath }) },
+          { label: "Build Context", path: contextPath, value: portableArtifactPaths(context, targetRepo, { artifactPath: contextPath }) },
+          { label: "Assembly Report", path: reportPath, value: portableArtifactPaths(report, targetRepo, { artifactPath: reportPath }) },
         ], prepareBuildCollisionPaths, {
           beforePublish: recheckStageEvidence,
         });
@@ -997,7 +997,7 @@ export async function withDesignSourcePublication({ targetRepo, outputs, force =
         // stamped with the intake command that ran doctor (`start` or `build`,
         // #312) without a second write path for it.
         publishPrepareBuildJsonOutputs([
-          { label: "Doctor Output", path: doctorOutPath, value: stampDoctorProducer(doctor, command) },
+          { label: "Doctor Output", path: doctorOutPath, value: portableArtifactPaths(stampDoctorProducer(doctor, command), targetRepo) },
         ], prepareBuildCollisionPaths);
       },
     }));

package/src/deviation.mjs

@@ -15,7 +15,7 @@ export const DEVIATION_JOURNAL_REL_PATH = ".campaign-runtime/agent-deviations.js
 
 // Commands that advance the pipeline. Read-only / bookkeeping commands
 // (doctor, next, findings, telemetry, run, validate-*) never deviate.
-export const TRACKED_STAGE_COMMANDS = Object.freeze(new Set(["start", "prepare-build", "theme", "polish", "qa", "run-record"]));
+export const TRACKED_STAGE_COMMANDS = Object.freeze(new Set(["prepare-build", "theme", "polish", "qa", "run-record"]));
 
 // Setup and metadata subcommands of a tracked command. They produce no stage
 // output, so running one outside the recommendation is not a detour:
@@ -77,6 +77,7 @@ export function buildRecommendation({ stage, status, expectedCommands, now = new
  * recommendation. Returns a deviation entry or null.
  */
 export function detectDeviation({ lastRecommendation, command, subcommand = null, argvShape = [], runId = null, deviationReason = null, now = new Date() }) {
+  if (argvShape.includes("--help")) return null;
   if (!TRACKED_STAGE_COMMANDS.has(command)) return null;
   if (subcommand && UNTRACKED_SUBCOMMANDS.has(`${command} ${subcommand}`)) return null;
   if (!lastRecommendation || !Array.isArray(lastRecommendation.expected_commands)) return null;

package/src/doctor/checks.mjs

@@ -93,6 +93,7 @@ import { FIGMA_EXPORT_FILE_CODES, SOURCE_PROVENANCE_SCOPE, evaluateSourceProvena
 import { validateCampaignBuildBriefArtifact } from "../build-brief.mjs";
 import { briefFileUnusable, deriveInputCurrency, wellFormedBriefMaterial } from "../input-currency.mjs";
 import { ASSEMBLY_REPORT_STAGE_KEYS, stageIsTerminal } from "../orchestration-stage-contract.mjs";
+import { assemblyReportStagesWithEvidence } from "../design-source-publication.mjs";
 import {
   assemblySourcePackageFingerprintMissing,
   assessAssemblySourcePackageFreshnessWaivers,
@@ -108,7 +109,7 @@ import { evaluatePageKitSdkVersion, PAGE_KIT_SDK_VERSION_SCOPE } from "../page-k
 // `npm run build:spec` (tsc -> campaign-spec/dist) so the package runs on the
 // node engine in package.json without type-stripping. build runs on `prepare`,
 // so a fresh install (including the git-ref consumer) always has dist.
-import { isReleasedSdkVersion, normalize as normalizeCampaignSpec, runRules, specOnlyRules } from "../../campaign-spec/dist/index.js";
+import { CHECKOUT_FLOW_PAGE_TYPES, checkoutPathFrom, isReleasedSdkVersion, normalize as normalizeCampaignSpec, runRules, specOnlyRules, upgradeCampaignSpec } from "../../campaign-spec/dist/index.js";
 import { cmd, asInvocation } from "../install-invocation.mjs";
 import { specHashesMatch, specMaterialHash } from "../spec-identity.mjs";
 import {
@@ -237,8 +238,12 @@ const US_MARKET_COPY_PATTERNS = [
 const HARDCODED_CURRENCY_REGEX = /\$\s?\d[\d,]*(?:\.\d+)?(?:\/[A-Za-z]+)?/g;
 const HARDCODED_PHONE_REGEX = /\b(?:\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b/g;
 
+// Pages read through here see the v5 vocabulary: a v4 spec's `checkout → checkout`
+// chain is retyped `checkout_step` on read (campaigns-os#641), so every doctor
+// check asks "is this the page that takes payment" of `type === "checkout"`.
 function normalizeFunnels(spec) {
-  if (Array.isArray(spec?.funnels)) return spec.funnels;
+  const upgraded = upgradeCampaignSpec(spec);
+  if (Array.isArray(upgraded?.funnels)) return upgraded.funnels;
   if (Array.isArray(spec?.funnel_pages)) {
     return [{ id: "default", weight: 100, pages: spec.funnel_pages }];
   }
@@ -440,7 +445,7 @@ const SPEC_DOCTOR_CHECKS = createDoctorCheckRegistry([
   {
     id: SDK_MARKUP,
     phase: "built-output",
-    run: ({ packet, errors, warnings, ready, derived }) => validateSdkMarkup(packet, errors, warnings, ready, derived),
+    run: ({ spec, packet, errors, warnings, ready, derived }) => validateSdkMarkup(packet, errors, warnings, ready, derived, spec),
   },
   {
     id: SCRIPT_SYNTAX,
@@ -542,6 +547,11 @@ function validatePacket(packet, packetPath, errors, warnings, ready, derived, bu
     addIssue(errors, "packet.type", "Build Packet must be a JSON object.");
     return;
   }
+  Object.defineProperty(derived, "page_kit_entry_mappings", {
+    value: Object.fromEntries((packet.source_html?.pages || [])
+      .filter((page) => page?.page_kit?.target_path).map((page) => [page.page_id, page])),
+    configurable: true,
+  });
   const synthesizedBuiltSite = isSynthesizedBuiltSitePacket(packet);
   if (packet.schema_version !== PACKET_SCHEMA) addIssue(errors, "schema_version", `Expected ${PACKET_SCHEMA}.`);
   else ready.push(`Build Packet schema ${PACKET_SCHEMA}`);
@@ -832,7 +842,7 @@ function validateAdapterContracts(packet, packetPath, spec, errors, warnings, re
   const packetContract = packet.source_html?.adapter_contract;
   validateAdapterDecisionShape(packetContract, "source_html.adapter_contract", warnings, ready, { addIssue });
   validateAdapterSourceFiles({
-    decisions: packetContract,
+    decisions: buildState.report?.adapter_decisions || buildState.context?.adapter_decisions || packetContract,
     sourceRoot: resolveFromFile(packetPath, packet.source_html?.root),
     pages: packet.source_html?.pages || [],
     warnings,
@@ -1201,17 +1211,20 @@ function paymentLogoForcedOn(html, method) {
 // unless the checkout page passes show_<method>=false.
 export const STARTER_TEMPLATE_DEFAULT_ON_PAYMENT_METHODS = Object.freeze(["paypal", "klarna", "apple_pay", "google_pay"]);
 
-// Built checkout pages on disk for the spec's active checkout pages: the
-// rendered _site/<slug>/<route>/index.html files that exist. Empty before a
-// build (or when the spec declares no checkout page), which is the pre-build
-// state the spec-only advisory covers.
+// Built checkout-flow pages on disk for the spec's active select, checkout_step
+// and checkout pages: the rendered _site/<slug>/<route>/index.html files that
+// exist. Steps and select pages are included on purpose: they carry express
+// payment buttons upstream of the Checkout (campaigns-os#641), and an
+// unsupported method rendered there ships just the same. Empty before a build
+// (or when the spec declares no checkout page), which is the pre-build state
+// the spec-only advisory covers.
 function builtCheckoutPagesForSpec(spec, packet, derived = {}) {
   const targetRepo = derived?.target_repo;
   const publicRouteSlug = normalizePublicRouteSlug(packet?.campaign?.public_route_slug);
   if (!targetRepo || !publicRouteSlug) return [];
   const built = [];
   for (const page of activeSpecPages(spec)) {
-    if (String(page?.type || page?.page_type || "").toLowerCase().trim() !== "checkout") continue;
+    if (!CHECKOUT_FLOW_PAGE_TYPES.includes(String(page?.type || page?.page_type || "").toLowerCase().trim())) continue;
     const path = builtHtmlPathForPage(targetRepo, publicRouteSlug, page, derived);
     if (!path || !existsSync(path) || !statSync(path).isFile()) continue;
     built.push({ page_id: page.id, path, file: relative(targetRepo, path).split(sep).join("/") });
@@ -2147,6 +2160,10 @@ export function validateCampaignIdentity(packet, errors, ready, derived, spec =
       site_root: siteRoot && targetRepo ? relFromDir(targetRepo, siteRoot) : null,
     },
     pages,
+    expectedApiKey: (() => {
+      const resolved = resolveCampaignsApiKeySource(packet, null, process.env, { spec });
+      return resolved.key ? { key: resolved.key, source: resolved.origin } : null;
+    })(),
     errors,
     ready,
     derived,
@@ -2290,8 +2307,8 @@ function readBoundedScript(realSiteRoot, path, maxBytes) {
   }
 }
 
-function recordCampaignIdentityGate({ subject, pages, errors, ready, derived }) {
-  const gate = evaluateCampaignIdentity({ subject, pages });
+function recordCampaignIdentityGate({ subject, pages, expectedApiKey = null, errors, ready, derived }) {
+  const gate = evaluateCampaignIdentity({ subject, pages, expectedApiKey });
   if (Array.isArray(derived?.checkpoint_gates)) derived.checkpoint_gates.push(gate);
 
   if (gate.status === "blocked") {
@@ -2315,17 +2332,23 @@ function recordCampaignIdentityGate({ subject, pages, errors, ready, derived })
 // Static SDK markup checks (#303). Every doctor invocation, both entry points,
 // filesystem enumeration, blocking regardless of stage status — the same
 // contract as the two gates above, for the same reasons.
-function validateSdkMarkup(packet, errors, warnings, ready, derived) {
+function validateSdkMarkup(packet, errors, warnings, ready, derived, spec = null) {
   const targetRepo = derived.target_repo;
   const publicRouteSlug = normalizePublicRouteSlug(packet?.campaign?.public_route_slug);
   const siteRoot = targetRepo && publicRouteSlug ? join(targetRepo, "_site", publicRouteSlug) : null;
   const scope = siteRoot && existsSync(siteRoot) ? resolveBuiltSiteScope(targetRepo, { slug: publicRouteSlug }) : null;
+  const declaredTypes = new Map(activeSpecPages(spec).filter((page) => ["receipt", "thankyou"].includes(page.type)).map((page) => [
+    builtHtmlPathForPage(targetRepo, publicRouteSlug, page, derived), "receipt",
+  ]));
   recordSdkMarkupGate({
     subject: {
       public_route_slug: publicRouteSlug || null,
       site_root: siteRoot && targetRepo ? relFromDir(targetRepo, siteRoot) : null,
     },
-    pages: scope?.ok ? collectBuiltPageIdentityInputs(scope, targetRepo) : [],
+    pages: scope?.ok ? collectBuiltPageIdentityInputs(scope, targetRepo).map((page) => ({
+      ...page,
+      page_type: declaredTypes.get(resolve(targetRepo, page.file)) || null,
+    })) : [],
     errors,
     warnings,
     ready,
@@ -2805,7 +2828,7 @@ function bumpDisplaysPresent(block, displays) {
   return displays.some((name) => new RegExp(`data-next-toggle-display\\s*=\\s*["']${name}["']`, "i").test(block));
 }
 
-const CHECKOUT_BUMP_PAGE_TYPES = new Set(["checkout", "select"]);
+const CHECKOUT_BUMP_PAGE_TYPES = new Set(CHECKOUT_FLOW_PAGE_TYPES);
 
 export function validateBuiltBumpPricing(content, builtPath, targetRepo, page, issueTarget) {
   const type = String(page?.type || page?.page_type || "").toLowerCase().trim();
@@ -2990,6 +3013,11 @@ function validateBuiltCommerceRefs(content, builtPath, targetRepo, page, spec, i
 
 function builtHtmlPathForPage(targetRepo, publicRouteSlug, page, derived = {}) {
   if (!targetRepo || !publicRouteSlug) return null;
+  const entryRoute = entryPageKitServingRoute(targetRepo, publicRouteSlug, page, {
+    targetOutputDir: derived?.target_output_dir,
+    mapping: derived?.page_kit_entry_mappings?.[page?.id],
+  });
+  if (entryRoute) return join(targetRepo, "_site", publicRouteSlug, ...(entryRoute.route ? [entryRoute.route] : []), "index.html");
   const sourcePermalink = sourcePermalinkForPage(derived?.target_output_dir, publicRouteSlug, page);
   const route = sourcePermalink || runtimeRelativeRouteForSpecValue(publicRouteForPage(page), publicRouteSlug);
   if (!route) return join(targetRepo, "_site", publicRouteSlug, "index.html");
@@ -2997,6 +3025,63 @@ function builtHtmlPathForPage(targetRepo, publicRouteSlug, page, derived = {}) {
   return clean ? join(targetRepo, "_site", publicRouteSlug, clean, "index.html") : join(targetRepo, "_site", publicRouteSlug, "index.html");
 }
 
+export function isRootRoutedEntryPage(page, publicRouteSlug) {
+  return Boolean(page?.is_entry) && runtimeRelativeRouteForSpecValue(publicRouteForPage(page), publicRouteSlug) === "";
+}
+
+// An explicit permalink belongs to this entry's Page Kit source file. It wins
+// even when an older build left output at the filename-derived route.
+export function entryPageKitServingRoute(targetRepo, publicRouteSlug, page, { targetOutputDir = null, mapping = null } = {}) {
+  if (!targetRepo || !publicRouteSlug || !isRootRoutedEntryPage(page, publicRouteSlug)) return null;
+  const permalink = entrySourcePermalink(targetOutputDir, publicRouteSlug, page, mapping);
+  if (permalink !== null) return { route: permalink, source: "permalink" };
+  const root = join(targetRepo, "_site", publicRouteSlug, "index.html");
+  if (existsSync(root) && statSync(root).isFile()) return { route: "", source: "root" };
+  const fileRoute = entryPageKitFileRoute(targetRepo, publicRouteSlug, page, { targetOutputDir, mapping });
+  return fileRoute ? { route: `${fileRoute}/`, source: "file" } : { route: "", source: "declared" };
+}
+
+function entrySourcePermalink(targetOutputDir, publicRouteSlug, page, mapping) {
+  if (!targetOutputDir || !existsSync(targetOutputDir) || !statSync(targetOutputDir).isDirectory()) return null;
+  const names = mapping?.page_kit?.target_path
+    ? [mapping.page_kit.target_path]
+    : [...new Set([page.id, page.type].filter(isNonEmptyString).map((name) => `${name}.html`))];
+  const routes = names
+    .filter((name) => /^[a-zA-Z0-9][a-zA-Z0-9_-]*\.html$/.test(name))
+    .map((name) => join(targetOutputDir, name))
+    .filter((path) => existsSync(path) && statSync(path).isFile())
+    .map((path) => extractFrontmatterValue(readFileSync(path, "utf8"), "permalink"))
+    .filter(isNonEmptyString)
+    .map((value) => stripPublicRoutePrefix(normalizePageKitRoute(value), publicRouteSlug));
+  return routes[0] ?? null;
+}
+
+// Page Kit serves a page file without a permalink at its basename route.
+// Only the recorded target file (or the family's own materialised stock file)
+// may identify an entry fallback; an unrelated built index is not evidence.
+export function entryPageKitFileRoute(targetRepo, publicRouteSlug, page, { targetOutputDir = null, mapping = null } = {}) {
+  if (!targetRepo || !publicRouteSlug || !isRootRoutedEntryPage(page, publicRouteSlug)) return null;
+  if (entrySourcePermalink(targetOutputDir, publicRouteSlug, page, mapping) !== null) return null;
+  const root = join(targetRepo, "_site", publicRouteSlug, "index.html");
+  if (existsSync(root) && statSync(root).isFile()) return null;
+  let names;
+  if (mapping?.page_kit?.target_path) {
+    names = [mapping.page_kit.target_path];
+  } else {
+    if (!targetOutputDir) return null;
+    names = [...new Set([page.id, page.type].filter(isNonEmptyString).map((name) => `${name}.html`))];
+  }
+  const routes = names
+    .filter((name) => /^[a-zA-Z0-9][a-zA-Z0-9_-]*\.html$/.test(name) && name !== "index.html")
+    .filter((name) => mapping?.page_kit || (existsSync(join(targetOutputDir, name)) && statSync(join(targetOutputDir, name)).isFile()))
+    .map((name) => name.slice(0, -".html".length))
+    .filter((route) => {
+      const built = join(targetRepo, "_site", publicRouteSlug, route, "index.html");
+      return existsSync(built) && statSync(built).isFile();
+    });
+  return routes[0] ?? null;
+}
+
 function sourcePermalinkForPage(targetOutputDir, publicRouteSlug, page) {
   if (!targetOutputDir || !existsSync(targetOutputDir) || !statSync(targetOutputDir).isDirectory()) return null;
 
@@ -3436,7 +3521,7 @@ function validateSpecPublicRoutes(spec, errors, ready) {
 }
 
 function pageRole(type) {
-  if (["checkout", "upsell", "downsell", "thankyou", "receipt", "select"].includes(type)) return "runtime";
+  if (["checkout", "checkout_step", "upsell", "downsell", "thankyou", "receipt", "select"].includes(type)) return "runtime";
   return "visual";
 }
 
@@ -3540,6 +3625,7 @@ function templateStockDecision(buildState, pageId) {
 function validateSourceCoverage(packet, packetPath, spec, errors, warnings, ready, derived = {}, buildState = {}) {
   const pages = packet.source_html?.pages || [];
   const publicRouteSlug = normalizePublicRouteSlug(packet?.campaign?.public_route_slug);
+  const routeRoot = campaignRouteRoot(packet);
   const materialisedTemplateStock = [];
   const sourceRoot = resolveFromFile(packetPath, packet.source_html?.root);
   validateSourceHtmlManifestAtRoot(sourceRoot, {
@@ -3567,6 +3653,20 @@ function validateSourceCoverage(packet, packetPath, spec, errors, warnings, read
     }
     mappedIds.add(page.page_id);
     const specPage = activeById.get(page.page_id);
+    const entryRoute = specPage
+      ? entryPageKitServingRoute(derived.target_repo, publicRouteSlug, specPage, {
+        targetOutputDir: derived.target_output_dir,
+        mapping: page,
+      })
+      : null;
+    const builtRoute = entryRoute ? entryRoute.route : specPage ? publicRouteForPage(specPage) : null;
+    const rootOutput = entryRoute?.route ? join(derived.target_repo, "_site", publicRouteSlug, "index.html") : null;
+    if (rootOutput && (entryRoute.source === "file" || entryRoute.source === "permalink")
+      && !(existsSync(rootOutput) && statSync(rootOutput).isFile())) {
+      const emittedRoute = `${routeRoot}${entryRoute.route}`;
+      const pageKitRoot = `/${normalizePublicRouteSlug(publicRouteSlug)}/`;
+      addIssue(warnings, "entry_route.unserved", `CampaignSpec entry page "${specPage.id}" is routed to ${routeRoot}, but Page Kit emitted it at ${emittedRoute} and nothing serves ${routeRoot}. Add a redirect from ${routeRoot} to ${emittedRoute}, or set \`permalink: ${pageKitRoot}\` (the campaign root as Page Kit emits it) on the entry page.`, { page_id: specPage.id, root_route: routeRoot, emitted_route: emittedRoute });
+    }
     if (!activeIds.has(page.page_id)) {
       addIssue(warnings, "source_html.pages.extra", `Source mapping "${page.page_id}" is not an active CampaignSpec page.`);
     }
@@ -3601,7 +3701,7 @@ function validateSourceCoverage(packet, packetPath, spec, errors, warnings, read
             page_id: specPage.id,
             type: specPage.type || "page",
             role: pageRole(specPage.type),
-            route: publicRouteForPage(specPage),
+            route: builtRoute,
             source_path: page.path,
           });
         }
@@ -3617,7 +3717,7 @@ function validateSourceCoverage(packet, packetPath, spec, errors, warnings, read
           page_id: specPage.id,
           type: specPage.type || "page",
           role: pageRole(specPage.type),
-          route: publicRouteForPage(specPage),
+          route: builtRoute,
           source_path: null,
           template_stock: true,
           template_family: family,
@@ -3946,6 +4046,98 @@ function packageRefsFromEntries(entries) {
     .filter((value) => value !== undefined && value !== null && String(value).trim().length > 0)
     .map((value) => String(value));
 }
+
+function supportsCheckoutVariantSlots(agentContract) {
+  const required = frontmatterList(agentContract, "requiredWhenCloning");
+  return required.includes("variant_slots[].id") && required.includes("variant_slots[].quantity");
+}
+
+function selectableVariantMatrixCount(packages) {
+  const selectable = Array.isArray(packages)
+    ? packages.filter((pkg) => pkg && pkg.is_order_bump !== true && pkg.is_upsell !== true)
+    : [];
+  const quantityRows = selectable.filter((pkg) => String(pkg.qty ?? "").trim());
+  if (quantityRows.length <= 1) return 0;
+  const attributeIdentity = (pkg) => {
+    if (!Array.isArray(pkg.variant_attributes) || pkg.variant_attributes.length === 0) return null;
+    const attributes = pkg.variant_attributes.map((attribute) => {
+      const value = String(attribute?.value ?? "").trim();
+      if (!value) return null;
+      return [String(attribute?.code || attribute?.name || "").trim(), value];
+    });
+    return attributes.every(Boolean) ? JSON.stringify(attributes.sort(([a], [b]) => a.localeCompare(b))) : null;
+  };
+  const textIdentity = (key) => (pkg) => {
+    const value = pkg[key];
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+  };
+  for (const identity of [attributeIdentity, textIdentity("product_variant_name")]) {
+    const values = quantityRows.map(identity);
+    if (!values.every(Boolean)) continue;
+    const quantitiesByVariant = new Map();
+    for (const [index, value] of values.entries()) {
+      const qty = String(quantityRows[index].qty).trim();
+      if (!quantitiesByVariant.has(value)) quantitiesByVariant.set(value, new Set());
+      quantitiesByVariant.get(value).add(qty);
+    }
+    return quantitiesByVariant.size > 1 && [...quantitiesByVariant.values()].some((quantities) => quantities.size > 1)
+      ? quantitiesByVariant.size
+      : 0;
+  }
+  return 0;
+}
+
+function warnCheckoutPackageFamilyFit(specPages, family, catalog, warnings, report) {
+  const selectedContract = catalog.families?.[family]?.agentContract;
+  if (
+    !selectedContract ||
+    !isCertifiedTemplateFamily(family, catalog) ||
+    !frontmatterList(selectedContract, "requiredWhenCloning").includes("packages.main_package") ||
+    supportsCheckoutVariantSlots(selectedContract)
+  ) return;
+  const fittingFamilies = [...certifiedTemplateFamilies(catalog)]
+    .filter((candidate) => supportsCheckoutVariantSlots(catalog.families[candidate]?.agentContract))
+    .sort();
+  const checkoutPages = specPages.filter((page) => CHECKOUT_FLOW_PAGE_TYPES.includes(page.type));
+  const byFunnel = new Map();
+  for (const page of checkoutPages) {
+    if (!byFunnel.has(page.funnel_id)) byFunnel.set(page.funnel_id, []);
+    byFunnel.get(page.funnel_id).push(page);
+  }
+  const paths = new Map();
+  for (const page of checkoutPages) {
+    const pages = byFunnel.get(page.funnel_id);
+    const path = checkoutPathFrom(pages, page) || [page];
+    const end = path[path.length - 1];
+    const key = `${page.funnel_id}:${end.id}`;
+    if (!paths.has(key)) paths.set(key, []);
+    const pathPages = paths.get(key);
+    for (const candidate of path) {
+      if (!pathPages.includes(candidate)) pathPages.push(candidate);
+    }
+  }
+  const hasStageEvidence = assemblyReportStagesWithEvidence(report).length > 0;
+  const multiStep = [...paths.values()].some((pathPages) =>
+    pathPages.some((candidate) => candidate.type === "checkout_step" || candidate.type === "select"));
+  for (const pathPages of paths.values()) {
+    const page = pathPages.find((candidate) => selectableVariantMatrixCount(candidate.packages) > 1);
+    if (!page) continue;
+    const variantCount = selectableVariantMatrixCount(page.packages);
+    const shapeMatches = fittingFamilies.filter((candidate) => Boolean(catalog.families[candidate]?.canonicalSurfaces?.selectStep) === multiStep);
+    // The catalog has no base-family field; its family-name prefix is the shared-base convention.
+    const baseMatches = shapeMatches.filter((candidate) => candidate.startsWith(`${family}-`));
+    const ranked = [...baseMatches, ...shapeMatches.filter((candidate) => !baseMatches.includes(candidate))];
+    const action = hasStageEvidence
+      ? "The template family is a build-time decision; changing it requires re-running intake with --force (destructive; clears recorded stage evidence)."
+      : "The family is chosen at intake with --template-family.";
+    addIssue(
+      warnings,
+      "template_contract.checkout_package_fit",
+      `Checkout path through page "${page.id}" has ${variantCount} variants, some offered at several quantities, but template family "${family}" has no configurable variant_slots[] checkout surface. ${ranked.length ? `Families that can present it: ${ranked.join(", ")}.` : "No certified family has a matching configurable variant-slot checkout surface."} ${action}`,
+      { page_id: page.id, funnel_id: page.funnel_id, template_family: family, distinct_product_variants: variantCount, fitting_families: ranked },
+    );
+  }
+}
 function offerRefsFromEntries(entries) {
   if (!Array.isArray(entries)) return [];
   return entries
@@ -4130,6 +4322,7 @@ export function validateCommerceCatalog(packet, packetPath, spec, errors, warnin
 
     // ADR-003 step 2: template-contract checks ported from the private doctor.
     const specPages = activeSpecPages(spec);
+    warnCheckoutPackageFamilyFit(specPages, family, catalog, warnings, buildState.report);
 
     const mismatchedFamilies = specPages.filter(
       (page) => isNonEmptyString(page.sdk_hints?.template_family) && page.sdk_hints.template_family !== family
@@ -4143,7 +4336,7 @@ export function validateCommerceCatalog(packet, packetPath, spec, errors, warnin
     }
 
     const checkoutPackageRefs = specPages
-      .filter((page) => page.type === "checkout" || page.type === "select")
+      .filter((page) => CHECKOUT_FLOW_PAGE_TYPES.includes(page.type))
       .flatMap((page) => packageRefsFromEntries(page.packages));
     if (familyAutomatable && contractMentions(contract, /\b(packages\.main_package|single_offer\.package_id|variant_slots)\b/) && checkoutPackageRefs.length === 0) {
       addIssue(
@@ -4258,7 +4451,7 @@ export function validateExitPopContract(contract, spec, family, warnings, ready,
   const exitPop = contract?.exit_pop;
   if (!exitPop || !spec) return;
   const hasGovernedOfferSurface = activeSpecPages(spec).some((page) => (
-    page?.type === "checkout" && (page?.exit_intent?.enabled === true || page?.promo_code_input?.enabled === true)
+    CHECKOUT_FLOW_PAGE_TYPES.includes(page?.type) && (page?.exit_intent?.enabled === true || page?.promo_code_input?.enabled === true)
   ));
   if (hasGovernedOfferSurface) {
     ready.push(`${family} exit-pop/promo-code behavior is governed by CampaignSpec offer-surface fields`);

package/src/doctor/inspect.mjs

@@ -34,6 +34,7 @@ import {
   readJsonIfExists,
   relFromDir,
   isLocalAbsolutePath,
+  portableArtifactPaths,
   addIssue,
 } from "../cli-helpers.mjs";
 import {
@@ -187,18 +188,19 @@ export function doctorCommand(args, { runDoctor = doctorPacket, liveCampaign = u
     commitAssemblyReport(workspace, (report) => recordDoctorStageOutcome(report, result, {
       command: `campaigns-os ${DOCTOR_PRODUCER}`,
       doctorOutPath: workspace.doctorOutPath,
+      targetRepo: workspace.targetRepo,
     }), { stage: "doctor", command: DOCTOR_PRODUCER, refreshDoctor: () => result });
   }
   return result;
 }
 
-function recordDoctorStageOutcome(report, result, { command, doctorOutPath }) {
+function recordDoctorStageOutcome(report, result, { command, doctorOutPath, targetRepo }) {
   return recordProducerStageOutcome(report, {
     stage: "doctor",
     disposition: result.ok ? (result.warnings?.length ? "ready_with_warnings" : "ready") : "blocked",
     timestamp: result.generated_at,
     command,
-    outputs: [doctorOutPath],
+    outputs: portableArtifactPaths([doctorOutPath], targetRepo),
     blockers: (result.errors || []).map((issue) => issue?.message).filter(isNonEmptyString),
     warnings: (result.warnings || []).map((issue) => issue?.message).filter(isNonEmptyString),
   });