@nextcommerce/campaigns-os 1.48.0 → 1.52.0

package/src/commercial-journey.mjs

@@ -104,11 +104,72 @@ function selectedShipping(page) {
 }
 
 // One predicate for "this checkout row is an order bump": the spec marks a
-// bump with `is_upsell: true` on a non-upsell page. Every consumer that must
+// bump with `is_order_bump: true` (the schema's and authoring guide's flag) or
+// `is_upsell: true` on a non-upsell page. Every consumer that must
 // tell a bump from a main selector row (parity scenarios, bump deltas, the QA
-// selector-tier planner) reads this, so a marker change lands in one place.
+// selector-tier planner, `next`'s order-bump QA command) reads this, so a
+// marker change lands in one place.
 export function isBumpRow(row) {
-  return Boolean(row?.is_upsell);
+  return Boolean(row?.is_order_bump || row?.is_upsell);
+}
+
+// A checkout package row's ref, with the doctor's specPackageRecords
+// tolerance (ref_id, then package_id, then id).
+function checkoutRowRef(pkg) {
+  return [pkg.ref_id, pkg.package_id, pkg.id]
+    .map((value) => (value == null ? "" : String(value).trim()))
+    .find(Boolean);
+}
+
+// Order bumps declared on a checkout page (isBumpRow rows), as refs in
+// declaration order. They are add-ons to a selected tier, not tiers, so the
+// QA tier planner reports and skips them and `next` names the --cart run that
+// toggles them.
+export function declaredOrderBumps(checkoutPage) {
+  const refs = [];
+  for (const pkg of array(checkoutPage?.packages)) {
+    if (!pkg || typeof pkg !== "object" || !isBumpRow(pkg)) continue;
+    const ref = checkoutRowRef(pkg);
+    if (ref && !refs.includes(ref)) refs.push(ref);
+  }
+  return refs;
+}
+
+// Selector tiers are the packages a spec declares on a checkout page, in
+// declaration order. Order-bump rows are add-ons offered alongside the
+// selected tier, not tiers of their own: they never become a tier.
+export function declaredSelectorTiers(checkoutPage) {
+  const records = [];
+  const quantitiesByRef = new Map();
+  for (const pkg of array(checkoutPage?.packages)) {
+    if (!pkg || typeof pkg !== "object" || isBumpRow(pkg)) continue;
+    const ref = checkoutRowRef(pkg);
+    const declaredQuantity = Number(pkg.qty ?? pkg.quantity ?? 1);
+    if (!ref || !Number.isInteger(declaredQuantity) || declaredQuantity < 1) continue;
+    records.push({ pkg, ref, declaredQuantity });
+    if (!quantitiesByRef.has(ref)) quantitiesByRef.set(ref, new Set());
+    quantitiesByRef.get(ref).add(declaredQuantity);
+  }
+
+  const tiers = [];
+  const seen = new Set();
+  for (const { pkg, ref, declaredQuantity } of records) {
+    // A unique ref is a catalog package bought once, even when that package's
+    // own composition is 3x. Only repeated declarations of the SAME ref at
+    // different quantities express shopper purchase multipliers (e.g. a 1x
+    // and a 2x package).
+    const quantity = quantitiesByRef.get(ref).size > 1 ? declaredQuantity : 1;
+    const identity = `${ref}:${quantity}`;
+    if (seen.has(identity)) continue;
+    seen.add(identity);
+    const label = [pkg.name, pkg.title].find((value) => typeof value === "string" && value.trim());
+    tiers.push({
+      ref,
+      quantity,
+      declared_by: label ? label.trim() : undefined,
+    });
+  }
+  return tiers;
 }
 
 function lineForRow(row) {
@@ -932,7 +993,7 @@ function makePage(scenarios, catalog) {
       row_index: row.row_index,
       package_id: row.package_id,
       quantity: row.quantity,
-      ...(row.is_upsell ? { is_upsell: true } : {}),
+      ...(isBumpRow(row) ? { is_upsell: true } : {}),
       name: row.name,
       state: PricingState.Unresolved,
       reason: pageReason,

package/src/commercial-parity.mjs

@@ -607,7 +607,12 @@ function partitionCaptures(capturesValue, { countsOnly = false } = {}) {
 
 function priceComparisonClaims(capture, page) {
   const claims = array(capture?.price_claims);
-  if (!exactMoneyFact(page?.representative_total)) {
+  // A voucher on the page that the plan cannot price (no calculated pair for
+  // its code) can move the shown price away from the planned total, so a
+  // difference there says nothing about the page. Its price claims stay
+  // unresolved, which already keeps coverage incomplete, rather than being
+  // reported as mismatches against the list-price total.
+  if (!exactMoneyFact(page?.representative_total) || voucherComparisonClaims(capture, page).unresolved > 0) {
     return { compared: [], unresolved: claims.length };
   }
   const bindings = [...new Set(claims.map((claim) => String(claim.binding)))];

package/src/doctor/checks.mjs

@@ -1,7 +1,7 @@
 // Doctor checks: the check registries, validatePacket and the validators they run.
 import { campaignSpecIdentity, resolveCampaignIdentity, campaignIdentitiesMatch } from "../spec-source-identity.mjs";
 import { withHtmlScanSnapshot, readHtmlScanText } from "../html-scan.mjs";
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { accessSync, constants as fsConstants, existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
 import { describeSdkIgnoredMetaTags, isSdkIgnoredMetaTag } from "../sdk-meta-tags.mjs";
 import { ORDER_PATH_DEPTH_DRIFT_CODE, orderPathDepthDriftText, orderPathDepthsDisagree } from "../proof-policy.mjs";
@@ -44,6 +44,7 @@ import {
   LOCAL_PROOF_BUILD_ENVIRONMENT_SCOPE,
   LOCAL_PROOF_NEVER_EDIT_RULE,
   LOCAL_PROOF_PARITY_COMMAND,
+  LOCAL_PROOF_RECORD_BUILD_COMMAND,
   LOCAL_PROOF_PARITY_FIELD,
   LOCAL_PROOF_PARITY_SCOPE,
   recordedBuildEnvironment,
@@ -84,6 +85,9 @@ import {
 import { CAMPAIGN_IDENTITY, evaluateCampaignIdentity, externalScriptSources } from "../campaign-identity.mjs";
 import { SDK_MARKUP, evaluateSdkMarkup } from "../sdk-markup.mjs";
 import { SCRIPT_SYNTAX, collectBuiltScriptSyntaxInputs, evaluateBuiltScriptSyntax } from "../built-script-syntax.mjs";
+import { CART_PLACEHOLDERS, CART_PLACEHOLDERS_LIMITS, evaluateCartPlaceholders, isFileReadFailure } from "../cart-placeholders.mjs";
+import { SMOKE_QC, SMOKE_QC_LIMITS, builtFileOf, evaluateSmokeQc, insideRoot, isBuiltPageReadFailure, pageScriptSources, parseBuiltPage, realPathOf } from "../built-smoke-qc.mjs";
+import { recordQcResults } from "../qc-results.mjs";
 import { FIGMA_EXPORT_FILE_CODES, SOURCE_PROVENANCE_SCOPE, evaluateSourceProvenanceGates, generatorClaimsFigmaExport, isSourceProvenanceCode } from "./source-provenance.mjs";
 import { validateCampaignBuildBriefArtifact } from "../build-brief.mjs";
 import { ASSEMBLY_REPORT_STAGE_KEYS, stageIsTerminal } from "../orchestration-stage-contract.mjs";
@@ -104,6 +108,7 @@ import { evaluatePageKitSdkVersion, PAGE_KIT_SDK_VERSION_SCOPE } from "../page-k
 // so a fresh install (including the git-ref consumer) always has dist.
 import { normalize as normalizeCampaignSpec, runRules, specOnlyRules } from "../../campaign-spec/dist/index.js";
 import { cmd, asInvocation } from "../install-invocation.mjs";
+import { specHashesMatch, specMaterialHash } from "../spec-identity.mjs";
 import {
   isObject,
   isNonEmptyString,
@@ -428,7 +433,7 @@ const SPEC_DOCTOR_CHECKS = createDoctorCheckRegistry([
   {
     id: CAMPAIGN_IDENTITY,
     phase: "built-output",
-    run: ({ packet, errors, ready, derived }) => validateCampaignIdentity(packet, errors, ready, derived),
+    run: ({ spec, packet, errors, ready, derived }) => validateCampaignIdentity(packet, errors, ready, derived, spec),
   },
   {
     id: SDK_MARKUP,
@@ -440,6 +445,16 @@ const SPEC_DOCTOR_CHECKS = createDoctorCheckRegistry([
     phase: "built-output",
     run: ({ packet, errors, warnings, ready, derived }) => validateBuiltScriptSyntax(packet, errors, warnings, ready, derived),
   },
+  {
+    id: CART_PLACEHOLDERS,
+    phase: "built-output",
+    run: ({ packet, warnings, ready, derived }) => validateCartPlaceholders(packet, warnings, ready, derived),
+  },
+  {
+    id: SMOKE_QC,
+    phase: "built-output",
+    run: ({ packet, warnings, ready, derived, buildState }) => validateSmokeQc(packet, warnings, ready, derived, buildState),
+  },
   {
     id: "built_output.sdk_meta_tags",
     phase: "built-output",
@@ -724,6 +739,16 @@ function validatePacket(packet, packetPath, errors, warnings, ready, derived, bu
         addIssue(errors, localIdentity ? "spec.local_identity" : "spec.map_id", "Packet identity does not match the CampaignSpec map_id/local_spec_id.", { kind: localIdentity ? "local_spec" : "saved_map" });
       }
       ready.push("Local CampaignSpec parsed");
+      // QA refuses a local-spec run whose spec no longer has the material hash
+      // prepare-build bound on the Assembly Report; doctor (and next, which
+      // prints doctor's warnings) name it at the first read instead.
+      const boundMaterialHash = buildState.report?.identity?.spec_material_hash;
+      if (packet.spec?.local_spec_id != null && isNonEmptyString(boundMaterialHash)) {
+        const currentMaterialHash = specMaterialHash(spec);
+        if (!specHashesMatch(boundMaterialHash, currentMaterialHash)) {
+          addIssue(warnings, "spec.material_stale", `The CampaignSpec at ${localSpecPath} changed materially since prepare-build bound it (Assembly Report identity.spec_material_hash ${boundMaterialHash}; the spec now hashes to ${currentMaterialHash}). The build and its recorded evidence predate the edit, and QA refuses a stale spec. Re-run ${cmd("prepare-build")} from the edited spec before building on it further.`, { spec_path: localSpecPath, bound_material_hash: boundMaterialHash, current_material_hash: currentMaterialHash });
+        }
+      }
       runDoctorChecks(SPEC_DOCTOR_CHECKS, { packet, packetPath, spec, targetRepo, errors, warnings, ready, derived, buildState });
     } else {
       runDoctorChecks(
@@ -852,7 +877,7 @@ function validateBuildBrief(packet, packetPath, spec, context, errors, warnings,
   }
 
   const brief = readJson(resolvedPath);
-  const result = validateCampaignBuildBriefArtifact(brief, { spec });
+  const result = validateCampaignBuildBriefArtifact(brief, { spec, normalizedPath });
   for (const issue of result.errors) errors.push(issue);
   for (const issue of result.warnings) warnings.push(issue);
   ready.push(...result.ready);
@@ -1129,7 +1154,7 @@ export function isLocalhostDevelopmentOrigin(value) {
 // Both facts are read from the assembly stage's free-form evidence.
 function validateLocalProof(packet, report, errors, warnings, ready) {
   if (!stageIsTerminal(report?.stages?.assembly?.status)) {
-    ready.push(`Local proof mode: the build stage renders the development environment (${LOCAL_PROOF_BUILD_COMMAND}) and records ${LOCAL_PROOF_BUILD_ENVIRONMENT_FIELD}; polish capture and QA run against that served output, and ${asInvocation(LOCAL_PROOF_PARITY_COMMAND)} proves the production render before commit.`);
+    ready.push(`Local proof mode: the build stage renders the development environment (${LOCAL_PROOF_BUILD_COMMAND}) and records ${LOCAL_PROOF_BUILD_ENVIRONMENT_FIELD} with ${asInvocation(LOCAL_PROOF_RECORD_BUILD_COMMAND)}; polish capture and QA run against that served output, and ${asInvocation(LOCAL_PROOF_PARITY_COMMAND)} proves the production render before commit.`);
     return;
   }
   const environment = recordedBuildEnvironment(report);
@@ -1137,8 +1162,8 @@ function validateLocalProof(packet, report, errors, warnings, ready) {
     ready.push(`Local proof mode: the built _site/ is recorded as a ${LOCAL_PROOF_BUILD_ENVIRONMENT} render (${LOCAL_PROOF_BUILD_ENVIRONMENT_FIELD}); vendor loaders are environment-gated out, SDK dl_* events still fire.`);
   } else {
     addIssue(warnings, LOCAL_PROOF_BUILD_ENVIRONMENT_SCOPE, environment
-      ? `${LOCAL_PROOF_BUILD_ENVIRONMENT_FIELD} is "${singleLineField(environment)}" under deploy.target local-serve. A production build served over plain HTTP fails polish capture unwaivably on its protocol-relative vendor loaders (//host/...). Rebuild with ${LOCAL_PROOF_BUILD_COMMAND}, record the environment as "${LOCAL_PROOF_BUILD_ENVIRONMENT}", and recapture. ${LOCAL_PROOF_NEVER_EDIT_RULE}`
-      : `${LOCAL_PROOF_BUILD_ENVIRONMENT_FIELD} is not recorded under deploy.target local-serve. The build stage renders the development environment for local proof (${LOCAL_PROOF_BUILD_COMMAND}) and records it there; without the record doctor cannot tell a development render from a production build that will fail polish capture over plain HTTP. ${LOCAL_PROOF_NEVER_EDIT_RULE}`);
+      ? `${LOCAL_PROOF_BUILD_ENVIRONMENT_FIELD} is "${singleLineField(environment)}" under deploy.target local-serve. A production build served over plain HTTP fails polish capture unwaivably on its protocol-relative vendor loaders (//host/...). Rebuild with ${LOCAL_PROOF_BUILD_COMMAND}, record it with ${asInvocation(LOCAL_PROOF_RECORD_BUILD_COMMAND)}, and recapture. ${LOCAL_PROOF_NEVER_EDIT_RULE}`
+      : `${LOCAL_PROOF_BUILD_ENVIRONMENT_FIELD} is not recorded under deploy.target local-serve. The build stage renders the development environment for local proof (${LOCAL_PROOF_BUILD_COMMAND}) and records it with ${asInvocation(LOCAL_PROOF_RECORD_BUILD_COMMAND)}; without the record doctor cannot tell a development render from a production build that will fail polish capture over plain HTTP. ${LOCAL_PROOF_NEVER_EDIT_RULE}`);
   }
   const parity = recordedProductionParity(report);
   const parityCommand = asInvocation(LOCAL_PROOF_PARITY_COMMAND);
@@ -1983,17 +2008,30 @@ function recordUpsellSelectorScopeGate({ subject, pages, waivers, errors, warnin
 // carries another funnel's key or tag arrives in a later edit round as often
 // as at first assembly. Enumerates from the filesystem so both doctor paths
 // scan the same pages, and stays blocking regardless of stage status.
-function validateCampaignIdentity(packet, errors, ready, derived) {
+//
+// With a CampaignSpec, each built page is marked by whether some active spec
+// page builds to it (the same path route drift claims), so a finding on a
+// file no spec page produces names it as leftover output.
+export function validateCampaignIdentity(packet, errors, 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 pages = scope?.ok ? collectBuiltPageIdentityInputs(scope, targetRepo) : [];
+  const specPages = isObject(spec) ? activeSpecPages(spec) : [];
+  if (specPages.length) {
+    const claimed = new Set(specPages
+      .map((page) => builtHtmlPathForPage(targetRepo, publicRouteSlug, page, derived))
+      .filter(Boolean)
+      .map((path) => resolve(path)));
+    for (const page of pages) page.spec_page = claimed.has(resolve(targetRepo, page.file));
+  }
   recordCampaignIdentityGate({
     subject: {
       public_route_slug: publicRouteSlug || null,
       site_root: siteRoot && targetRepo ? relFromDir(targetRepo, siteRoot) : null,
     },
-    pages: scope?.ok ? collectBuiltPageIdentityInputs(scope, targetRepo) : [],
+    pages,
     errors,
     ready,
     derived,
@@ -2009,7 +2047,24 @@ function validateCampaignIdentity(packet, errors, ready, derived) {
 // `/<slug>/config.js`), then the campaign directory (a root-served campaign
 // emits `/config.js`); relative srcs resolve against the page. Remote and
 // missing scripts contribute nothing.
-function collectBuiltPageIdentityInputs(scope, targetRepo) {
+//
+// The bounded form ({ pages, bounds }) takes pages the caller already read
+// ({file, content?}, as collectCartPlaceholderPages gives them) and adds each
+// page's `scripts` as the smoke check's anchor script hint reads them
+// (boundedPageScripts), listed from the page's bounded parse5 tree
+// (pageScriptSources: any attribute quoting, spacing or case; never a
+// non-JavaScript type or a script in <template> or <noscript>). A page with
+// no content, or one that cannot be parsed, is returned as given. The smoke
+// check itself hands boundedPageScripts the srcs its own parse lists, so a
+// page is parsed once.
+function collectBuiltPageIdentityInputs(scope, targetRepo, { pages = null, bounds = null } = {}) {
+  if (pages && bounds) {
+    const scriptsOf = boundedPageScripts(scope.site_root, targetRepo, bounds);
+    return pages.map((page) => {
+      const sources = typeof page?.content === "string" ? boundedScriptSources(page.content) : null;
+      return sources ? { ...page, scripts: scriptsOf(sources, join(targetRepo, page.file)) } : page;
+    });
+  }
   const scriptCache = new Map();
   const readScript = (path) => {
     if (!scriptCache.has(path)) {
@@ -2023,23 +2078,11 @@ function collectBuiltPageIdentityInputs(scope, targetRepo) {
     }
     return scriptCache.get(path);
   };
-  const resolveLocalScript = (src, builtPath) => {
-    const raw = String(src || "").trim();
-    if (!raw || raw.startsWith("//") || isAbsoluteHttpUrl(raw) || raw.startsWith("data:")) return null;
-    const clean = raw.replace(/[?#].*$/, "");
-    if (!clean) return null;
-    if (clean.startsWith("/")) {
-      const rel = clean.replace(/^\/+/, "");
-      const candidates = [join(scope.site_root, rel), join(scope.campaign_dir, rel)];
-      return candidates.find((candidate) => existsSync(candidate)) || null;
-    }
-    return resolve(dirname(builtPath), clean);
-  };
   return scope.pages.map((page) => {
     const content = readFileSync(page.built_path, "utf8");
     const scripts = [];
     for (const src of externalScriptSources(content)) {
-      const path = resolveLocalScript(src, page.built_path);
+      const path = builtLocalScriptPath(scope, src, page.built_path);
       const scriptContent = path ? readScript(path) : null;
       if (scriptContent == null) continue;
       scripts.push({ src, file: relFromDir(targetRepo, path), content: scriptContent });
@@ -2054,6 +2097,84 @@ function collectBuiltPageIdentityInputs(scope, targetRepo) {
   });
 }
 
+// Where a page's local `<script src>` lives, or null for a remote, data: or
+// empty src. An absolute src is the first of its site-root and campaign
+// candidates that exists, otherwise null.
+function builtLocalScriptPath(scope, src, builtPath) {
+  const raw = String(src || "").trim();
+  if (!raw || raw.startsWith("//") || isAbsoluteHttpUrl(raw) || raw.startsWith("data:")) return null;
+  const clean = raw.replace(/[?#].*$/, "");
+  if (!clean) return null;
+  if (clean.startsWith("/")) {
+    const rel = clean.replace(/^\/+/, "");
+    const candidates = [join(scope.site_root, rel), join(scope.campaign_dir, rel)];
+    return candidates.find((candidate) => existsSync(candidate)) || null;
+  }
+  return resolve(dirname(builtPath), clean);
+}
+
+// The srcs of the scripts a page loads, or null when it cannot be parsed.
+function boundedScriptSources(content) {
+  try {
+    return pageScriptSources(parseBuiltPage(content));
+  } catch (error) {
+    if (!isBuiltPageReadFailure(error)) throw error;
+    return null;
+  }
+}
+
+// The smoke check's script reader: given the srcs a page loads and the
+// page's file, every local script, read or not. The first `bounds.scripts`
+// are read when their real path lies inside the site root and they hold at
+// most `bounds.script_bytes` bytes ({src, file, content}); any other reads
+// {src, file, unread} with `missing`, `outside_site`, `too_large`,
+// `unreadable` or `script_cap`, or {src, unread: "unmappable"} when its src
+// names no file. Each src maps to its file through builtFileOf: the URL
+// parser resolves it against the page's URL under the site root (a
+// root-relative src starts at the site root, never the campaign directory),
+// and its path segments are percent-decoded. Each script file is read at most
+// once per run.
+function boundedPageScripts(siteRoot, targetRepo, bounds) {
+  const realSiteRoot = realPathOf(siteRoot);
+  const cache = new Map();
+  const read = (path) => {
+    if (!cache.has(path)) cache.set(path, readBoundedScript(realSiteRoot, path, bounds.script_bytes));
+    return cache.get(path);
+  };
+  return (sources, builtPath) => {
+    const scripts = [];
+    for (const src of sources) {
+      const mapped = builtFileOf(src, builtPath, siteRoot);
+      if (!mapped) continue;
+      if (mapped.unmappable) {
+        scripts.push({ src, unread: "unmappable" });
+        continue;
+      }
+      const path = mapped.path;
+      const file = relFromDir(targetRepo, path);
+      scripts.push(scripts.length < bounds.scripts ? { src, file, ...read(path) } : { src, file, unread: "script_cap" });
+    }
+    return scripts;
+  };
+}
+
+// { content } or { unread }. A file-system read failure reads unread; any
+// other error is a defect and throws.
+function readBoundedScript(realSiteRoot, path, maxBytes) {
+  try {
+    const real = realpathSync(path);
+    if (!realSiteRoot || !insideRoot(realSiteRoot, real)) return { unread: "outside_site" };
+    const stat = statSync(real);
+    if (!stat.isFile()) return { unread: "unreadable" };
+    if (stat.size > maxBytes) return { unread: "too_large" };
+    const bytes = readFileSync(real);
+    return bytes.length > maxBytes ? { unread: "too_large" } : { content: bytes.toString("utf8") };
+  } catch (error) {
+    if (!isFileReadFailure(error)) throw error;
+    return { unread: error.code === "ENOENT" || error.code === "ENOTDIR" ? "missing" : "unreadable" };
+  }
+}
+
 function recordCampaignIdentityGate({ subject, pages, errors, ready, derived }) {
   const gate = evaluateCampaignIdentity({ subject, pages });
   if (Array.isArray(derived?.checkpoint_gates)) derived.checkpoint_gates.push(gate);
@@ -2143,6 +2264,148 @@ function recordScriptSyntaxGate({ subject, inputs, errors, warnings, ready, deri
   return gate;
 }
 
+// Raw cart placeholders. Every doctor invocation, both entry
+// points, filesystem enumeration, like the gates above; but a QC check, not a
+// checkpoint gate: its results land in derived.qc_results (warning and review
+// also in warnings[]), never in errors[] or derived.checkpoint_gates, so no
+// blocker elsewhere can withhold them and checkpoint waive never sees them.
+function validateCartPlaceholders(packet, warnings, ready, derived) {
+  const targetRepo = derived.target_repo;
+  const publicRouteSlug = normalizePublicRouteSlug(packet?.campaign?.public_route_slug);
+  const siteRoot = targetRepo && publicRouteSlug ? join(targetRepo, "_site", publicRouteSlug) : null;
+  recordCartPlaceholders({
+    subject: {
+      public_route_slug: publicRouteSlug || null,
+      site_root: siteRoot && targetRepo ? relFromDir(targetRepo, siteRoot) : null,
+    },
+    pages: siteRoot && existsSync(siteRoot) ? collectCartPlaceholderPages(targetRepo, publicRouteSlug) : [],
+    warnings,
+    ready,
+    derived,
+  });
+}
+
+// Every built page under the campaign directory, in path order, including
+// every symbolic link that may hold a page (an .html link, a directory link,
+// or a link whose target cannot be inspected; each one entry, read as
+// unreadable, never followed). Pages within the page cap carry their HTML,
+// read one page at a time, unless they are over the size cap or cannot be
+// read; pages past it carry only their path.
+function collectCartPlaceholderPages(targetRepo, slug) {
+  const scope = resolveBuiltSiteScope(targetRepo, { slug, includeLinkedPages: true });
+  const linked = new Set((scope.linked_pages || []).map((page) => page.built_path));
+  const all = [...(scope.ok ? scope.pages : []), ...(scope.linked_pages || [])]
+    .sort((a, b) => (a.built_path < b.built_path ? -1 : a.built_path > b.built_path ? 1 : 0));
+  const fileOf = (page) => builtPageFile(targetRepo, page.built_path);
+  return [
+    ...all.slice(0, CART_PLACEHOLDERS_LIMITS.pages).map((page) => readCartPlaceholderPage(page.built_path, fileOf(page), linked.has(page.built_path))),
+    ...all.slice(CART_PLACEHOLDERS_LIMITS.pages).map((page) => ({ file: fileOf(page) })),
+  ];
+}
+
+// One page within the page cap: its HTML, its size when over the size cap, or
+// unreadable. A file-system read failure, before or after the readability
+// precheck (EIO, EACCES, EISDIR ...), reads it unreadable; any other error is
+// a defect and throws.
+function readCartPlaceholderPage(path, file, linked) {
+  if (linked) return { file, unreadable: true };
+  try {
+    const bytes = statSync(path).size;
+    if (!isReadableFile(path)) return { file, unreadable: true };
+    if (bytes > CART_PLACEHOLDERS_LIMITS.page_bytes) return { file, bytes };
+    return { file, content: readFileSync(path, "utf8") };
+  } catch (error) {
+    if (!isFileReadFailure(error)) throw error;
+    return { file, unreadable: true };
+  }
+}
+
+// A built page's path relative to the doctor target, "/"-separated and with no
+// "./" prefix ("_site/<slug>/index.html"). The directory is resolved, the file
+// name never is, so a symlinked page keeps its own name.
+function builtPageFile(targetRepo, path) {
+  const dir = relFromDir(targetRepo, dirname(path)).replace(/^\.(?:\/|$)/, "");
+  return [...(dir ? dir.split(sep) : []), basename(path)].join("/");
+}
+
+// Whether the page can be opened for reading. Only a file-system read failure
+// says it cannot; any other error is a defect and throws.
+function isReadableFile(path) {
+  try {
+    accessSync(path, fsConstants.R_OK);
+    return true;
+  } catch (error) {
+    if (!isFileReadFailure(error)) throw error;
+    return false;
+  }
+}
+
+function recordCartPlaceholders({ subject, pages, warnings, ready, derived }) {
+  const results = evaluateCartPlaceholders({ subject, pages });
+  recordQcResults({ derived, warnings, results });
+  if (!pages.length) {
+    ready.push("Cart placeholder check not applicable: no built page to scan yet.");
+    return results;
+  }
+  // A ready line only when no page went unexercised.
+  if (results.some((row) => row.result === "unexercised")) return results;
+  const passed = results.filter((row) => row.result === "pass").length;
+  const flagged = results.filter((row) => row.result === "warning" || row.result === "review").length;
+  ready.push(`Cart placeholder check on ${pages.length} built page(s): ${passed} page(s) pass, ${flagged} warning or review result(s)`);
+  return results;
+}
+
+// Built-output smoke checks. Same placement and the same QC wiring as the
+// cart placeholder check above, over the same built pages. The build
+// environment is the one the Assembly Report records (nothing measures it),
+// and the deploy URLs give the base an absolute og:image maps from.
+function validateSmokeQc(packet, warnings, ready, derived, buildState = {}) {
+  const targetRepo = derived.target_repo;
+  const publicRouteSlug = normalizePublicRouteSlug(packet?.campaign?.public_route_slug);
+  const siteRoot = targetRepo && publicRouteSlug ? join(targetRepo, "_site", publicRouteSlug) : null;
+  recordSmokeQc({
+    subject: {
+      public_route_slug: publicRouteSlug || null,
+      site_root: siteRoot && targetRepo ? relFromDir(targetRepo, siteRoot) : null,
+    },
+    targetRepo,
+    pages: siteRoot && existsSync(siteRoot) ? collectCartPlaceholderPages(targetRepo, publicRouteSlug) : [],
+    environment: recordedBuildEnvironment(buildState?.report),
+    deployBase: [packet?.deploy?.preview_url, packet?.deploy?.production_url],
+    warnings,
+    ready,
+    derived,
+  });
+}
+
+function recordSmokeQc({ subject, targetRepo, pages, environment, deployBase, warnings, ready, derived }) {
+  // The site root is the scope's, whichever form of target doctor was given
+  // (the repo, its _site/ or a campaign directory). The anchor script hint
+  // reads each page's local scripts through boundedPageScripts, from the srcs
+  // the gate's own parse lists. With no scope to resolve them in, a page's
+  // local scripts read unread.
+  const scope = targetRepo && pages.length ? resolveBuiltSiteScope(targetRepo, { slug: subject?.public_route_slug || null }) : null;
+  const siteRoot = scope?.site_root || null;
+  const results = evaluateSmokeQc({
+    pages,
+    environment,
+    siteRoot,
+    targetDir: targetRepo || null,
+    readScripts: siteRoot ? boundedPageScripts(siteRoot, targetRepo, SMOKE_QC_LIMITS) : null,
+    deployBase,
+  });
+  recordQcResults({ derived, warnings, results });
+  if (!pages.length) {
+    ready.push("Smoke checks not applicable: no built page to scan yet.");
+    return results;
+  }
+  // A ready line only when no result went unexercised (contract 1.0).
+  if (results.some((row) => row.result === "unexercised")) return results;
+  const count = (...values) => results.filter((row) => values.includes(row.result)).length;
+  ready.push(`Smoke checks on ${pages.length} built page(s): ${count("pass")} pass, ${count("warning", "review")} warning or review result(s)`);
+  return results;
+}
+
 function recordSdkMarkupGate({ subject, pages, errors, warnings, ready, derived }) {
   const gate = evaluateSdkMarkup({ subject, pages });
   if (Array.isArray(derived?.checkpoint_gates)) derived.checkpoint_gates.push(gate);
@@ -2565,7 +2828,7 @@ function pageKitAssetPathViolation(reference, publicRouteSlug) {
   };
 }
 
-function resolveBuiltAssetPath(src, builtPath, targetRepo) {
+export function resolveBuiltAssetPath(src, builtPath, targetRepo) {
   if (!isNonEmptyString(src)) return null;
   const raw = src.trim();
   if (raw.startsWith("//") || isAbsoluteHttpUrl(raw) || raw.startsWith("data:") || raw.startsWith("mailto:") || raw.startsWith("tel:")) return null;
@@ -3090,7 +3353,7 @@ function coverageErrorMessage(page, { figmaGate = false } = {}) {
       return `Active CampaignSpec page "${page.id}" has no source mapping. design_source.type="ai-generated"${fileUrlHint} — re-run the producing agent so the source HTML and source-html manifest land in the source root, then rerun prepare-build. ${sourceManifestHint(page, figmaGate)} See docs/entry-points.md for the AI-generated entry point contract.`;
     }
     if (!fileUrl) {
-      return `Active CampaignSpec page "${page.id}" has no source mapping. design_source is set but file_url is missing — add file_url to the spec before requesting a build.`;
+      return `Active CampaignSpec page "${page.id}" has no source mapping. design_source is set but file_url is missing — add file_url to the spec before requesting a build, or, for hand-written or template HTML, remove design_source from the page and map it in the source-html manifest. ${sourceManifestHint(page, figmaGate)}`;
     }
     return `Active CampaignSpec page "${page.id}" has no source mapping. design_source.type="${designSource.type}" at ${fileUrl}; produce the source HTML for this page (or update design_source.type to a recognized producer — see docs/entry-points.md) before rerunning prepare-build. ${sourceManifestHint(page, figmaGate)}`;
   }
@@ -3329,6 +3592,7 @@ function validateSourcePreparation(packet, packetPath, errors, warnings, ready,
     sourceRoot,
     pages,
     wrapperPolicy: packet.source_html?.adapter_contract?.wrapper_policy,
+    targetRoot: resolveFromFile(packetPath, packet.assembly?.target_repo),
   });
   derived.source_preparation = {
     checked_page_count: result.checked_page_count,
@@ -4636,6 +4900,9 @@ export {
   recordCampaignIdentityGate,
   recordScriptSyntaxGate,
   recordSdkMarkupGate,
+  recordCartPlaceholders,
+  collectCartPlaceholderPages,
+  recordSmokeQc,
   summarizeCopyMatches,
   resolveBrandContract,
   resolveBrandContractOnce,