@nextcommerce/campaigns-os 1.50.0 → 1.53.0

package/src/doctor/checks.mjs

@@ -1,7 +1,8 @@
 // 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 { createHash } from "node:crypto";
+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 +45,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,8 +86,12 @@ 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 { briefFileUnusable, deriveInputCurrency, wellFormedBriefMaterial } from "../input-currency.mjs";
 import { ASSEMBLY_REPORT_STAGE_KEYS, stageIsTerminal } from "../orchestration-stage-contract.mjs";
 import {
   assemblySourcePackageFingerprintMissing,
@@ -104,6 +110,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 +435,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 +447,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",
@@ -496,7 +513,10 @@ const PACKET_DOCTOR_CHECKS = createDoctorCheckRegistry([
   {
     id: "build_brief.artifact",
     phase: "brief",
-    run: ({ packet, packetPath, spec, context, errors, warnings, ready }) => validateBuildBrief(packet, packetPath, spec, context, errors, warnings, ready),
+    run: ({ packet, packetPath, spec, context, report, errors, warnings, ready, derived }) => {
+      validateBuildBrief(packet, packetPath, spec, context, errors, warnings, ready);
+      validateInputCurrency({ packet, packetPath, spec, report, warnings, derived });
+    },
   },
 ], { registryId: "packet.always" });
 
@@ -716,14 +736,22 @@ function validatePacket(packet, packetPath, errors, warnings, ready, derived, bu
     }
     buildState.specStatus = specStatus;
     if (specStatus === "ok") {
-      const specMapId = spec.spec_identity?.map_id || spec.map_id;
-      if ((specMapId && specMapId !== packet.spec.map_id)
-        || ((spec.spec_identity?.local_spec_id != null || packet.spec?.local_spec_id != null)
-          && !campaignIdentitiesMatch(campaignSpecIdentity(spec), packet.spec))) {
-        const localIdentity = spec.spec_identity?.local_spec_id != null || packet.spec?.local_spec_id != null;
-        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" });
+      const identityKind = specIdentityMismatch(spec, packet.spec);
+      if (identityKind) {
+        addIssue(errors, identityKind === "local_spec" ? "spec.local_identity" : "spec.map_id", "Packet identity does not match the CampaignSpec map_id/local_spec_id.", { kind: identityKind });
       }
       ready.push("Local CampaignSpec parsed");
+      // The spec no longer has the material hash the Assembly Report binds:
+      // a local spec, or the copy a saved-Map or gateway packet fetched.
+      // Doctor (and next, which prints doctor's warnings) name it at the
+      // first read.
+      const boundMaterialHash = buildState.report?.identity?.spec_material_hash;
+      if (isNonEmptyString(boundMaterialHash)) {
+        const currentMaterialHash = specMaterialHash(spec);
+        if (!specHashesMatch(boundMaterialHash, currentMaterialHash)) {
+          addIssue(warnings, "spec.material_stale", SPEC_MATERIAL_STALE_MESSAGE, { 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(
@@ -737,6 +765,9 @@ function validatePacket(packet, packetPath, errors, warnings, ready, derived, bu
   if (synthesizedBuiltSite) {
     ready.push("Packet source/proof checks skipped for synthesized built-site packet");
   } else {
+    // Computed once, before the checks that read it (the QA gate pass the
+    // built-output residue scan defers to) and the input warnings below.
+    derived.input_currency = deriveInputCurrency({ packet, packetPath, report: buildState.report, spec: isObject(spec) ? spec : null });
     runDoctorChecks(PACKET_DOCTOR_CHECKS, { packet, packetPath, spec, context: buildState.context, report: buildState.report, errors, warnings, ready, derived, buildState });
   }
 
@@ -756,6 +787,25 @@ function validatePacket(packet, packetPath, errors, warnings, ready, derived, bu
   // stage progression.
 }
 
+// A stage's spec stamp, as record build, record polish and the QA write store it.
+const SPEC_STAMP = /^sha256:[0-9a-f]{64}$/;
+const SPEC_MATERIAL_STALE_MESSAGE = "CampaignSpec material changed since it was bound; run `record spec` (keeps history). `prepare-build --force` resets every stage and archives their records.";
+
+/**
+ * Whether a parsed CampaignSpec names another campaign than `bound` (the
+ * packet's spec block, or an Assembly Report identity): null when they
+ * agree, otherwise the kind of identity that differs ("local_spec" when
+ * either side carries a local spec id, else "saved_map").
+ */
+export function specIdentityMismatch(spec, bound) {
+  const specMapId = spec?.spec_identity?.map_id || spec?.map_id;
+  const localIdentity = spec?.spec_identity?.local_spec_id != null || bound?.local_spec_id != null;
+  if ((specMapId && specMapId !== bound?.map_id) || (localIdentity && !campaignIdentitiesMatch(campaignSpecIdentity(spec), bound))) {
+    return localIdentity ? "local_spec" : "saved_map";
+  }
+  return null;
+}
+
 function validateCampaignSpecRuleRegistry(spec, errors, warnings) {
   // ADR-003: run the shared campaign-spec rule registry — the single public
   // source of CampaignSpec validation. specOnlyRules is the right preset here:
@@ -851,8 +901,18 @@ function validateBuildBrief(packet, packetPath, spec, context, errors, warnings,
     return;
   }
 
-  const brief = readJson(resolvedPath);
-  const result = validateCampaignBuildBriefArtifact(brief, { spec });
+  let brief;
+  try {
+    brief = readJson(resolvedPath);
+  } catch {
+    addIssue(errors, "build_brief.normalized_path", `Campaign Build Brief normalized artifact is not valid JSON: ${normalizedPath}. Restore it, or save the brief again with ${cmd("record")} brief --packet <packet>.`);
+    return;
+  }
+  if (!isObject(brief)) {
+    addIssue(errors, "build_brief.normalized_path", `Campaign Build Brief normalized artifact is not a valid brief object: ${normalizedPath}. Restore it, or save the brief again with ${cmd("record")} brief --packet <packet>.`);
+    return;
+  }
+  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);
@@ -862,6 +922,86 @@ function validateBuildBrief(packet, packetPath, spec, context, errors, warnings,
   }
 }
 
+// derived.input_currency, computed once per doctor read, and the warnings it
+// gives: a stage owed on the brief or on the CampaignSpec, a completed stage
+// with no valid brief or spec stamp, or read against a brief or CampaignSpec
+// that cannot be read, a brief file edited (or unreadable) since it was saved,
+// and the build replay after an input change (owed, or kept by the
+// operator's recorded decision). None is an error; `next` routes to the owed
+// stage itself.
+function validateInputCurrency({ packet, packetPath, spec, report, warnings, derived }) {
+  const currency = derived.input_currency || deriveInputCurrency({ packet, packetPath, report, spec: isObject(spec) ? spec : null });
+  derived.input_currency = currency;
+  if (!isObject(report?.stages)) return;
+  // A stage stamped with other spec content than the file holds now, while
+  // the report identity already names the file's content (an identity edited
+  // by hand): the same warning the identity comparison gives.
+  const owedOnSpec = Object.keys(currency.reasons).filter((key) => currency.reasons[key] === "spec_material_changed");
+  if (owedOnSpec.length && !warnings.some((issue) => issue.code === "spec.material_stale")) {
+    addIssue(warnings, "spec.material_stale", SPEC_MATERIAL_STALE_MESSAGE, { stages: owedOnSpec, bound_material_hash: currency.spec.bound, current_material_hash: currency.spec.current });
+  }
+  const specUnstamped = Object.keys(currency.stages).filter((key) => currency.reasons[key] === "input_binding_unknown" && !SPEC_STAMP.test(String(report.stages[key]?.source_spec_material_hash ?? "")));
+  if (specUnstamped.length) {
+    addIssue(warnings, "spec.binding_unknown", `Recorded ${specUnstamped.join(", ")} ${specUnstamped.length === 1 ? "does" : "do"} not say which CampaignSpec content ${specUnstamped.length === 1 ? "it was" : "they were"} made against, so ${specUnstamped.length === 1 ? "it reads" : "they read"} unconfirmed, not current. Record ${specUnstamped.join(", ")} again (${specUnstamped.map((key) => (key === "assembly" ? "record build" : key === "polish" ? "record polish" : "qa run")).join(", ")}).`, { stages: specUnstamped });
+  }
+  const owedOnBrief = Object.keys(currency.reasons).filter((key) => currency.reasons[key] === "brief_material_changed");
+  if (owedOnBrief.length) {
+    addIssue(warnings, "build_brief.material_changed", `The Campaign Build Brief's content changed since ${owedOnBrief.join(", ")} ${owedOnBrief.length === 1 ? "was" : "were"} recorded, so ${owedOnBrief.length === 1 ? "it is" : "they are"} owed again. Save the brief with ${cmd("record")} brief --packet <packet> (it keeps stage history), then record ${owedOnBrief.join(", ")} again.`, { stages: owedOnBrief });
+  }
+  const unstamped = Object.keys(currency.stages).filter((key) => {
+    const stage = report.stages[key];
+    if (currency.reasons[key] !== "input_binding_unknown") return false;
+    const stamp = stage?.source_brief_material;
+    return !wellFormedBriefMaterial(stamp);
+  });
+  if (unstamped.length) {
+    addIssue(warnings, "build_brief.binding_unknown", `Recorded ${unstamped.join(", ")} ${unstamped.length === 1 ? "does" : "do"} not say which Campaign Build Brief content ${unstamped.length === 1 ? "it was" : "they were"} made against, so ${unstamped.length === 1 ? "it reads" : "they read"} unconfirmed, not current. Record ${unstamped.join(", ")} again (${unstamped.map((key) => (key === "assembly" ? "record build" : key === "polish" ? "record polish" : "qa run")).join(", ")}).`, { stages: unstamped });
+  }
+  // A completed stage with a well-formed stamp also reads unknown when the
+  // current brief or CampaignSpec cannot be read: there is nothing to compare
+  // that stamp with. The warning names the file to restore; a stage whose
+  // stamp is missing or malformed is named by the stamp warning above only.
+  const unknownStages = Object.keys(currency.stages).filter((key) => currency.reasons[key] === "input_binding_unknown");
+  const unconfirmed = (stages) => `recorded ${stages.join(", ")} ${stages.length === 1 ? "reads" : "read"} unconfirmed, not current`;
+  const briefUnreadable = unknownStages.filter((key) => !unstamped.includes(key));
+  if (briefUnreadable.length && currency.brief.current === null) {
+    const normalizedPath = optionalString(packet?.build_brief?.normalized_path);
+    addIssue(warnings, "build_brief.binding_unknown", `${normalizedPath ? `The normalized Campaign Build Brief ${normalizedPath} cannot be read as a brief object` : "The Build Packet names no build_brief.normalized_path, so the current Campaign Build Brief cannot be read"}, so ${unconfirmed(briefUnreadable)}. Restore it, or save the brief again with ${cmd("record")} brief --packet <packet>.`, { stages: briefUnreadable, ...(normalizedPath ? { normalized_path: normalizedPath } : {}) });
+  }
+  const specPath = optionalString(packet?.spec?.local_path);
+  const specUnreadable = unknownStages.filter((key) => !specUnstamped.includes(key));
+  if (specUnreadable.length && currency.spec.current === null && specPath) {
+    addIssue(warnings, "spec.binding_unknown", `The CampaignSpec ${specPath} cannot be read as a JSON object, so ${unconfirmed(specUnreadable)}. Restore it, then run doctor again.`, { stages: specUnreadable, spec_path: specPath });
+  }
+  const inputPath = optionalString(packet?.build_brief?.input_path);
+  const savedSha = optionalString(report.build_brief?.input_sha256);
+  const briefFile = inputPath ? resolveFromFile(packetPath, inputPath) : null;
+  if (briefFile && savedSha && existsSync(briefFile)) {
+    // Read only a readable regular file: a pipe would block, a directory throws.
+    const unusable = briefFileUnusable(briefFile);
+    let bytes = null;
+    if (!unusable) {
+      try {
+        bytes = `sha256:${createHash("sha256").update(readFileSync(briefFile)).digest("hex")}`;
+      } catch {
+        bytes = null;
+      }
+    }
+    if (bytes === null) {
+      addIssue(warnings, "build_brief.input_unsaved", `The brief file ${inputPath} ${unusable || "cannot be read"}, so doctor cannot tell whether it changed since it was saved; the build reads the saved brief. Restore it, or save a readable brief file with ${cmd("record")} brief --packet <packet> --brief <file>.`, { input_path: inputPath });
+    } else if (bytes !== savedSha) {
+      addIssue(warnings, "build_brief.input_unsaved", `The brief file ${inputPath} changed since it was saved. Save it with ${cmd("record")} brief --packet <packet>; until then the build reads the saved brief.`, { input_path: inputPath });
+    }
+  }
+  if (currency.reasons.assembly === "output_unchanged_after_input_change") {
+    addIssue(warnings, "assembly.output_unchanged_after_input_change", `The build output is unchanged since the brief or CampaignSpec change was recorded, so the change has not reached the pages and build is owed again. Rebuild, or, only on the operator's explicit decision that the change needs no output change, record build with --deviation-reason "<the operator's reason>".`);
+  }
+  const keptReason = report.stages.assembly?.unchanged_output_reason;
+  if (currency.stages.assembly === "current" && isObject(keptReason) && typeof keptReason.text === "string") {
+    addIssue(warnings, "assembly.output_unchanged_by_operator_decision", `The build output was kept unchanged after an input change by the operator's recorded decision: "${keptReason.text}".`, { reason: keptReason.text });
+  }
+}
+
 function validateProofPolicyObject(policy, location, warnings, ready, { requireBrowserQa = false } = {}) {
   if (!isObject(policy)) {
     addIssue(warnings, location, `${location} must be an object when present.`);
@@ -1129,7 +1269,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 +1277,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 +2123,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 +2162,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 +2193,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 +2212,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 +2379,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 +2943,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 +3468,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 +3707,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,
@@ -3993,7 +4372,7 @@ export function validateBuiltPlaceholderTextResidue(brandContract, warnings, rea
     return;
   }
   const terms = [...new Set(hits.map((hit) => hit.label))].join(", ");
-  if (report && qaGatePassedForCurrentBuild(report, QA_GATE_PLACEHOLDER_TEXT_RESIDUE, { buildFingerprint: currentBuildFingerprint(report) })) {
+  if (report && qaGatePassedForCurrentBuild(report, QA_GATE_PLACEHOLDER_TEXT_RESIDUE, { buildFingerprint: currentBuildFingerprint(report), qaCurrency: derived.input_currency?.stages?.qa ?? "unknown" })) {
     ready.push(`Static scan still sees placeholder-term text (${terms}: ${summarizeCopyMatches(hits)}), but the browser residue gate passed on this build; QA's rendered-text verdict stands.`);
     return;
   }
@@ -4636,6 +5015,9 @@ export {
   recordCampaignIdentityGate,
   recordScriptSyntaxGate,
   recordSdkMarkupGate,
+  recordCartPlaceholders,
+  collectCartPlaceholderPages,
+  recordSmokeQc,
   summarizeCopyMatches,
   resolveBrandContract,
   resolveBrandContractOnce,