@nextcommerce/campaigns-os 1.50.0 → 1.52.0

package/src/sdk-attribute-index.mjs

@@ -210,3 +210,74 @@ export function isKnownCheckoutFieldName(value) {
   return SDK_CHECKOUT_FIELD_NAMES.includes(name)
     || SDK_CHECKOUT_FIELD_PREFIXES.some((prefix) => name.startsWith(prefix) && name.length > prefix.length);
 }
+
+// The Campaign Cart template placeholders, for the raw cart placeholder check
+// (built_output.cart_placeholders). Generated from the SDK renderers at the
+// same tag as the attribute index above, v0.4.38:
+//
+//   src/features/cart/cart-summary/cart-summary.renderer.ts:46-83 (bare vars)
+//   src/features/cart/cart-summary/cart-summary.line-renderer.ts:150-173,
+//     228-240,256-314 ({item.*} and its {line.*} alias, {property.*},
+//     {discount.*})
+//   src/features/cart/package-selector/package-selector.renderer.ts:26
+//     ({package.<any key>})
+//   src/features/cart/bundle-selector/bundle-selector.renderer.ts:37-42
+//     ({bundle.<any key>})
+//   src/features/cart/package-toggle/package-toggle.enhancer.ts:59-65
+//     ({toggle.<any key>})
+//   src/features/cart/quantity-control/quantity-control.renderer.ts:69-70
+//     ({quantity}, {step})
+//   src/features/cart/remove-item/remove-item.renderer.ts:26 ({quantity})
+//   src/features/display/quantity-text/quantity-text.enhancer.ts:124,149
+//     ({qty...} and {singular|plural})
+//
+// Every namespaced renderer replaces any `{<namespace>.<key>}` in its
+// template (item.property.<key> and the package, bundle and toggle keys are
+// open-ended; an unmapped key renders empty), so the namespace alone makes a
+// token known. `{tax}` is not a cart-summary var at this tag. Regenerate the
+// lists whole from the renderers when the index pin advances; never edit them
+// by hand.
+export const SDK_TEMPLATE_PLACEHOLDERS = Object.freeze({
+  cart_summary_vars: Object.freeze([
+    "subtotal",
+    "total",
+    "shipping",
+    "shippingName",
+    "shippingCode",
+    "shippingOriginal",
+    "shippingDiscountAmount",
+    "shippingDiscountPercentage",
+    "totalDiscount",
+    "totalDiscountPercentage",
+    "discounts",
+    "currency",
+    "isCalculating",
+    "isEmpty",
+    "itemCount",
+    "totalQuantity",
+    "isFreeShipping",
+    "hasShippingDiscount",
+    "hasDiscounts",
+  ]),
+  namespaces: Object.freeze(["item", "line", "discount", "property", "package", "bundle", "toggle"]),
+  // Tokens the SDK substitutes in live markup, and the elements that own them.
+  live_tokens: Object.freeze(["quantity", "step", "qty"]),
+  // [data-next-quantity="increase|decrease|set"]: {quantity} and {step}.
+  quantity_control: Object.freeze({ attribute: "data-next-quantity", values: Object.freeze(["increase", "decrease", "set"]), tokens: Object.freeze(["quantity", "step"]) }),
+  // [data-next-remove-item]: {quantity} only.
+  remove_item: Object.freeze({ attribute: "data-next-remove-item", tokens: Object.freeze(["quantity"]) }),
+  // [data-next-quantity-text]: {qty...} and the singular/plural form.
+  // `qty_forms` is the renderer's own {qty} pattern (quantity-text.enhancer.ts:
+  // 124, /\{qty([*+\-]?\d*)\}/): {qty}, {qty*2}, {qty+1}, {qty-1}.
+  quantity_text: Object.freeze({ attribute: "data-next-quantity-text", tokens: Object.freeze(["qty"]), qty_forms: "qty[*+\\-]?\\d*" }),
+  // Item lists whose innerHTML the SDK uses as the row template or replaces
+  // (cart-item-list.enhancer.ts:21-35, order-item-list.enhancer.ts:26-36).
+  item_list_containers: Object.freeze(["data-next-cart-items", "data-next-order-items"]),
+  item_template_selector: "data-item-template-selector",
+  item_template: "data-item-template",
+});
+
+// The SDK versions whose renderer files above were verified unchanged from
+// v0.4.38 (git blob ids equal at v0.4.38, v0.4.39 and v0.4.40). A page whose
+// loader pins another version cannot pass the placeholder check.
+export const SDK_TEMPLATE_PLACEHOLDERS_VERIFIED_PINS = Object.freeze(["0.4.38", "0.4.39", "0.4.40"]);

package/src/sdk-markup.mjs

@@ -86,7 +86,7 @@ export const SDK_MARKUP_CODES = Object.freeze({
 
 // Attributes whose value names a <template> by id. The SDK reads the template
 // they point at, so that template is SDK-owned wherever it sits.
-const TEMPLATE_ID_ATTRIBUTES = /^data-(?:next-)?[a-z0-9-]*template-id$/;
+export const TEMPLATE_ID_ATTRIBUTES = /^data-(?:next-)?[a-z0-9-]*template-id$/;
 
 // Containers whose DIRECT <template> child the SDK clones (each does a
 // `:scope > template` lookup at v0.4.38: cart-summary and its
@@ -98,7 +98,7 @@ const TEMPLATE_ID_ATTRIBUTES = /^data-(?:next-)?[a-z0-9-]*template-id$/;
 // package-toggle).
 // Only the direct child: a vendor template nested deeper inside SDK chrome is
 // never read, so it may use any syntax.
-const TEMPLATE_CONTAINER_ATTRIBUTES = [
+export const TEMPLATE_CONTAINER_ATTRIBUTES = [
   "data-next-cart-summary",
   "data-summary-lines",
   "data-next-discounts",

package/src/sdk-storage-compatibility.mjs

@@ -1,6 +1,7 @@
 // Read-only source evidence. SDK migration names come exclusively from the supplied manifest.
 import { parse as parseJs } from 'acorn';
 import { parse as parseHtml } from 'parse5';
+import { parseDocument, isSeq, isScalar, LineCounter } from 'yaml';
 import { execFileSync } from 'node:child_process';
 import { readFileSync, lstatSync, realpathSync, statSync } from 'node:fs';
 import { resolve, relative, dirname, posix, sep } from 'node:path';
@@ -261,6 +262,35 @@ export function analyzeStorageJavaScript(source, { path = '<source>', lineOffset
   visit(ast, null);
   return findings;
 }
+// Page Kit's campaign_asset filter serves src/<slug>/assets/<path>, <slug> being
+// the campaign folder the template sits in. A layout's {% for script in scripts %}
+// loop loads each page's frontmatter `scripts:` entries through the same filter.
+const CAMPAIGN_ASSET_SRC = /^\{\{-?\s*(?:'([^']*)'|"([^"]*)"|([A-Za-z_]\w*))\s*\|\s*campaign_asset\s*-?\}\}$/;
+function campaignAssetRoot(path) {
+  const match = /^((?:.*\/)?src\/[^/]+)\//.exec(path);
+  return match ? `${match[1]}/assets` : null;
+}
+function loopsOverPageScripts(text, name) {
+  return new RegExp(`\\{%-?\\s*for\\s+${name}\\s+in\\s+(?:page\\.)?scripts\\b`).test(text);
+}
+// Each local-or-remote entry of a page's frontmatter `scripts:` list with the
+// file line it is declared on, or an error naming why the list cannot be read.
+function frontmatterScripts(text) {
+  const block = /^\uFEFF?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+  if (!block) return { scripts: [] };
+  const lineCounter = new LineCounter();
+  const document = parseDocument(block[1], { lineCounter });
+  if (document.errors.length) {
+    const { line } = lineCounter.linePos(document.errors[0].pos[0]);
+    return { error: `Frontmatter is not valid YAML (${document.errors[0].code}); review the scripts this page loads.`, line: line + 1 };
+  }
+  const scripts = document.get('scripts', true);
+  if (scripts === undefined || scripts === null || (isScalar(scripts) && scripts.value === null)) return { scripts: [] };
+  if (!isSeq(scripts) || !scripts.items.every(item => isScalar(item) && typeof item.value === 'string'))
+    return { error: 'Frontmatter scripts is not a list of paths; review the scripts this page loads.', line: lineCounter.linePos(scripts.range?.[0] ?? 0).line + 1 };
+  // linePos is 1-based within the YAML block, which starts on the file's line 2.
+  return { scripts: scripts.items.map(item => ({ value: item.value, line: lineCounter.linePos(item.range[0]).line + 1 })) };
+}
 export function scanSdkStorageCompatibility({ cwd = process.cwd(), targetSdkVersion, manifestPath, scope, exclude = [] }) {
   version(targetSdkVersion);
   if (!Array.isArray(scope) || !scope.length)
@@ -320,20 +350,50 @@ export function scanSdkStorageCompatibility({ cwd = process.cwd(), targetSdkVers
       for (const child of node.childNodes ?? []) findBase(child);
     }
     findBase(document);
+    const assetRoot = campaignAssetRoot(path);
+    const requireSelected = (sourcePath, line) => {
+      if (!selected.includes(sourcePath))
+        unknown(path, 'shared-script-outside-scope', sourcePath, line);
+    };
+    // Page Kit serves campaign_asset paths from the assets folder only; an entry
+    // that normalizes outside it is not a file the page loads from there.
+    const requireAsset = (asset, line) => {
+      const sourcePath = posix.normalize(`${assetRoot}/${asset.split(/[?#]/)[0]}`);
+      if (sourcePath.startsWith(`${assetRoot}/`)) requireSelected(sourcePath, line);
+      else unknown(path, 'shared-script-outside-scope', `${asset} resolves outside ${assetRoot}`, line);
+    };
+    if (assetRoot) {
+      const frontmatter = frontmatterScripts(text);
+      if (frontmatter.error)
+        unknown(path, 'shared-script-outside-scope', frontmatter.error, frontmatter.line);
+      for (const { value, line } of frontmatter.scripts ?? []) {
+        if (/^(?:[a-z]+:)?\/\//i.test(value) || value.startsWith('data:')) continue;
+        requireAsset(value, line);
+      }
+    }
     function html(node) {
       if (node.tagName === 'script') {
         const attrs = Object.fromEntries((node.attrs ?? []).map(a => [a.name, a.value]));
         const type = (attrs.type ?? '').trim().toLowerCase();
         if (!type || ['module', 'text/javascript', 'application/javascript', 'text/ecmascript', 'application/ecmascript'].includes(type)) {
-          if (attrs.src) {
+          const campaignAsset = attrs.src ? CAMPAIGN_ASSET_SRC.exec(attrs.src.trim()) : null;
+          if (campaignAsset) {
+            const line = node.sourceCodeLocation?.startLine ?? 1;
+            const literal = campaignAsset[1] ?? campaignAsset[2];
+            if (assetRoot && literal !== undefined)
+              requireAsset(literal, line);
+            else if (!assetRoot || !loopsOverPageScripts(text, campaignAsset[3]))
+              unknown(path, 'shared-script-outside-scope', attrs.src, line);
+            // A frontmatter scripts loop: each page's own entries are checked above.
+          }
+          else if (attrs.src) {
             if (baseHref !== null && !attrs.src.startsWith('/') && !/^[a-z]+:/i.test(attrs.src)) {
               unknown(path, 'html-base-script-resolution', `Relative script ${attrs.src} resolves against base ${baseHref}; include/review the actual dependency.`, node.sourceCodeLocation?.startLine ?? 1);
             }
             if (!/^(?:[a-z]+:)?\/\//i.test(attrs.src) && !attrs.src.startsWith('data:')) {
               const localSource = attrs.src.split(/[?#]/)[0];
               const sourcePath = posix.normalize(localSource.startsWith('/') ? localSource.slice(1) : posix.join(posix.dirname(path), localSource));
-              if (!selected.includes(sourcePath))
-                unknown(path, 'shared-script-outside-scope', sourcePath, node.sourceCodeLocation?.startLine ?? 1);
+              requireSelected(sourcePath, node.sourceCodeLocation?.startLine ?? 1);
             }
           }
           else if (node.sourceCodeLocation?.startTag) {

package/src/source-prep.mjs

@@ -8,7 +8,7 @@
 // source asset crawl (source_asset.* codes) so the two checks never disagree
 // about the same reference.
 import { existsSync, readFileSync, statSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { collectDocumentWrapperNames } from "./adapter-decision-contract.mjs";
 
 export const SOURCE_PREP_DOCUMENT_WRAPPER = "source_html.prep.document_wrapper";
@@ -201,7 +201,7 @@ function describeFinding(code, pages, { wrapperPolicy }) {
     const policyNote = wrapperPolicy === "preserve_document_wrappers"
       ? " The adapter contract records wrapper_policy \"preserve_document_wrappers\", so this is reported without blocking."
       : "";
-    return `Mapped source HTML is a full browser document, not page-kit-ready source: ${listed}${more}. Strip <!doctype>, <html>, <head>, and <body> so the campaign layout can wrap the page, or, for a standalone page meant to stay whole, record wrapper_policy "preserve_document_wrappers" as an explicit adapter decision: re-run start or prepare-build with --wrapper-policy preserve_document_wrappers, or set "wrapper_policy" in the source-html manifest.${policyNote} See ${docs}.`;
+    return `Mapped source HTML (the converted page-kit page once it exists at page_kit.output_path, else the design) is a full browser document, not page-kit-ready source: ${listed}${more}. Strip <!doctype>, <html>, <head>, and <body> so the campaign layout can wrap the page, or, for a standalone page meant to stay whole, record wrapper_policy "preserve_document_wrappers" as an explicit adapter decision: re-run start or prepare-build with --wrapper-policy preserve_document_wrappers, or set "wrapper_policy" in the source-html manifest.${policyNote} See ${docs}.`;
   }
   if (code === SOURCE_PREP_FRONTMATTER_RESIDUE) {
     const listed = sample.map((page) => {
@@ -220,6 +220,26 @@ function describeFinding(code, pages, { wrapperPolicy }) {
   return `Mapped source HTML still links to source files instead of CampaignSpec routes: ${listed}${more}. Replace internal links and CTA destinations with CampaignSpec-derived routes, usually via campaign_link; source filenames like checkout.html are not built campaign URLs. See ${docs}.`;
 }
 
+// The converted page-kit page for a mapped design (page_kit.output_path under
+// the target repo), when it has been written.
+function convertedPageContent(targetRoot, page) {
+  const outputPath = page?.page_kit?.output_path;
+  if (!isNonEmptyString(targetRoot) || !isNonEmptyString(outputPath)) return null;
+  // output_path is repo-relative. One that is absolute or climbs out of the
+  // target repo is not a converted page of this campaign, so it reads like a
+  // missing one and the design is checked instead.
+  const root = resolve(targetRoot);
+  const fullPath = resolve(root, outputPath);
+  const rel = relative(root, fullPath);
+  if (isAbsolute(outputPath) || rel === "" || rel.startsWith("..") || isAbsolute(rel)) return null;
+  if (!safeIsFile(fullPath)) return null;
+  try {
+    return { path: toPosixPath(outputPath), content: readFileSync(fullPath, "utf8") };
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Evaluates the page-kit source-preparation expectations for every mapped
  * source page. Deterministic: same files in, same findings out. Unreadable or
@@ -227,7 +247,7 @@ function describeFinding(code, pages, { wrapperPolicy }) {
  *
  * @returns {{ checked_page_count: number, findings: Array<{code, severity, message, docs, pages}> }}
  */
-export function evaluateSourcePreparation({ sourceRoot, pages = [], wrapperPolicy = null }) {
+export function evaluateSourcePreparation({ sourceRoot, pages = [], wrapperPolicy = null, targetRoot = null }) {
   const mappedPaths = new Set(
     pages
       .map((page) => (isNonEmptyString(page?.path) ? toPosixPath(page.path) : null))
@@ -247,14 +267,24 @@ export function evaluateSourcePreparation({ sourceRoot, pages = [], wrapperPolic
       continue;
     }
     checked += 1;
-    const pageFindings = inspectPageContent({ content, sourceRoot, pagePath: page.path, mappedPaths });
+    let pageFindings = inspectPageContent({ content, sourceRoot, pagePath: page.path, mappedPaths });
+    // Wrappers are stripped when the design is converted into the page-kit
+    // page at page_kit.output_path, the file page-kit builds. Once that page
+    // exists, it is the one checked; the design keeps its wrappers.
+    const converted = convertedPageContent(targetRoot, page);
+    if (converted) {
+      pageFindings = pageFindings.filter((finding) => finding.code !== SOURCE_PREP_DOCUMENT_WRAPPER);
+      const wrappers = collectDocumentWrapperNames(converted.content);
+      if (wrappers.length) pageFindings.push({ code: SOURCE_PREP_DOCUMENT_WRAPPER, wrappers, path: converted.path });
+    }
     for (const finding of pageFindings) {
       if (!byCode.has(finding.code)) byCode.set(finding.code, new Map());
       const pagesForCode = byCode.get(finding.code);
-      if (!pagesForCode.has(page.path)) {
-        pagesForCode.set(page.path, { page_id: page.page_id || null, path: page.path, wrappers: [], hrefs: [], variants: [] });
+      const findingPath = finding.path || page.path;
+      if (!pagesForCode.has(findingPath)) {
+        pagesForCode.set(findingPath, { page_id: page.page_id || null, path: findingPath, wrappers: [], hrefs: [], variants: [] });
       }
-      const entry = pagesForCode.get(page.path);
+      const entry = pagesForCode.get(findingPath);
       if (finding.wrappers) entry.wrappers.push(...finding.wrappers);
       if (finding.hrefs) entry.hrefs.push(...finding.hrefs);
       if (finding.variant) entry.variants.push({ variant: finding.variant, lines: finding.lines || [] });

package/src/stage-record.mjs

@@ -29,7 +29,8 @@ import { BRAND_LAYER_FILENAMES } from "./brand-theme.mjs";
 import { computeBuildFingerprint, resolveBuiltSiteScope } from "./built-site-scope.mjs";
 import { resolveCampaignWorkspace, targetRepoFor } from "./campaign-workspace.mjs";
 import { isObject, optionalString, readJsonIfExists, requireArg } from "./cli-helpers.mjs";
-import { isLocalServePacket } from "./local-proof.mjs";
+import { LOCAL_PROOF_BUILD_ENVIRONMENT, LOCAL_PROOF_PRODUCTION_ENVIRONMENT, isLocalServePacket } from "./local-proof.mjs";
+import { CARRIED_FORWARD } from "./local-preview-policy.mjs";
 import { isLoopbackHostname } from "./remit.mjs";
 import { campaignRouteRoot } from "./route-identity.mjs";
 import { writeJsonAtomic } from "./doctor-sidecar.mjs";
@@ -51,11 +52,17 @@ import { commerceScopeFromScope } from "./theme-gate.mjs";
 
 export const RECORD_STAGES = Object.freeze(["setup", "build", "polish", "theme", "deploy"]);
 
-// Every flag `record` reads, plus the two any command accepts (run id and
-// lifecycle journal). Anything else is refused before a file is read.
-const RECORD_FLAGS = Object.freeze(["packet", "context", "report", "dry-run", "json", "run-id", "lifecycle-journal"]);
+// Every flag `record` reads, plus the three any command accepts (run id,
+// lifecycle journal, and the deviation reason the deviation notice asks
+// agents to declare). Anything else is refused before a file is read.
+const RECORD_FLAGS = Object.freeze(["packet", "context", "report", "dry-run", "json", "run-id", "lifecycle-journal", "deviation-reason"]);
 const POLISH_RECORD_FLAGS = Object.freeze(["evidence"]);
 const DEPLOY_RECORD_FLAGS = Object.freeze(["base-url"]);
+const BUILD_RECORD_FLAGS = Object.freeze(["build-environment"]);
+// The page-kit environment the built output was rendered in, recorded on
+// stages.assembly.evidence.build_environment (local proof mode builds in
+// development; doctor and page-kit parity read it).
+export const BUILD_ENVIRONMENTS = Object.freeze([LOCAL_PROOF_BUILD_ENVIRONMENT, LOCAL_PROOF_PRODUCTION_ENVIRONMENT]);
 
 // The keys a --evidence file may carry. `evidence` is stages.polish.evidence;
 // `repair_loop_defect` is report.theme.repair_loop_defect; `blockers` (status
@@ -74,6 +81,13 @@ function schemaValidator(file) {
   return validators.get(file);
 }
 
+// The value at an Ajv instancePath (JSON Pointer) in the validated document.
+function valueAt(document, pointer) {
+  return pointer.split("/").slice(1)
+    .map((part) => part.replace(/~1/g, "/").replace(/~0/g, "~"))
+    .reduce((node, key) => (node == null ? undefined : node[key]), document);
+}
+
 // Ajv's instancePath (`/theme/repair_loop_defect`) as the dotted field name
 // the rest of the toolkit prints (`theme.repair_loop_defect`).
 function schemaProblems(file, value, label) {
@@ -83,7 +97,11 @@ function schemaProblems(file, value, label) {
   const problems = [];
   for (const error of validate.errors || []) {
     const field = error.instancePath.split("/").filter(Boolean).join(".") || "(root)";
-    const line = `${label} ${field} ${error.message}`;
+    // Ajv's enum message names no values; the allowed list is the remedy.
+    const allowed = error.keyword === "enum" && Array.isArray(error.params?.allowedValues)
+      ? `: ${error.params.allowedValues.map((allowedValue) => JSON.stringify(allowedValue)).join(", ")} (got ${JSON.stringify(valueAt(value, error.instancePath))})`
+      : "";
+    const line = `${label} ${field} ${error.message}${allowed}`;
     if (seen.has(line)) continue;
     seen.add(line);
     problems.push(line);
@@ -96,6 +114,11 @@ function typeName(value) {
   return Array.isArray(value) ? "array" : typeof value;
 }
 
+// visual_review keys only `polish capture` writes. `record polish --evidence`
+// refuses them by name and carries the captured values forward.
+export const PACKAGE_OWNED_VISUAL_REVIEW_KEYS = Object.freeze(["page_load", "media_weight"]);
+export const PACKAGE_OWNED_KEY_REFUSAL = "package_owned_key";
+
 function refuseRecord(stage, problems) {
   return new Error(`record ${stage} refused; nothing was written:\n${problems.map((problem) => `- ${problem}`).join("\n")}`);
 }
@@ -103,26 +126,31 @@ function refuseRecord(stage, problems) {
 export function parseRecordArgs(args) {
   const stage = args._[1];
   if (!RECORD_STAGES.includes(stage) || args._.length !== 2) {
-    throw refused(`Use: ${cmd("record")} <${RECORD_STAGES.join("|")}> --packet <campaign-runtime.build.json> [--context <json>] [--report <json>] [--dry-run] [--json]; record polish also takes --evidence <polish-evidence.json>, and record deploy --base-url <served url>.`);
+    throw refused(`Use: ${cmd("record")} <${RECORD_STAGES.join("|")}> --packet <campaign-runtime.build.json> [--context <json>] [--report <json>] [--dry-run] [--json]; record polish also takes --evidence <polish-evidence.json>, record deploy --base-url <served url>, and record build [--build-environment <${BUILD_ENVIRONMENTS.join("|")}>].`);
   }
-  const known = new Set([...RECORD_FLAGS, ...(stage === "polish" ? POLISH_RECORD_FLAGS : []), ...(stage === "deploy" ? DEPLOY_RECORD_FLAGS : [])]);
+  const known = new Set([...RECORD_FLAGS, ...(stage === "polish" ? POLISH_RECORD_FLAGS : []), ...(stage === "deploy" ? DEPLOY_RECORD_FLAGS : []), ...(stage === "build" ? BUILD_RECORD_FLAGS : [])]);
   const unknown = Object.keys(args).filter((key) => key !== "_" && !known.has(key));
   if (unknown.length) {
     throw refused(`Unknown flag${unknown.length > 1 ? "s" : ""} for record ${stage}: ${unknown.map((key) => `--${key}`).join(", ")}. Known flags: ${[...known].map((key) => `--${key}`).join(", ")}.`);
   }
-  for (const flag of ["context", "report", "run-id", "lifecycle-journal"]) {
+  for (const flag of ["context", "report", "run-id", "lifecycle-journal", "deviation-reason"]) {
     if (Object.hasOwn(args, flag)) requireArg(args, flag);
   }
   if (Object.hasOwn(args, "dry-run") && args["dry-run"] !== true) {
     throw refused(`--dry-run takes no value (got ${JSON.stringify(args["dry-run"])}); write \`--dry-run\` on its own, after the other flags.`);
   }
   if (Object.hasOwn(args, "json") && args.json !== true) throw refused("--json is a boolean flag and takes no value.");
+  const buildEnvironment = Object.hasOwn(args, "build-environment") ? args["build-environment"] : null;
+  if (buildEnvironment !== null && !BUILD_ENVIRONMENTS.includes(buildEnvironment)) {
+    throw refused(`--build-environment must be one of: ${BUILD_ENVIRONMENTS.join(", ")} (got ${JSON.stringify(buildEnvironment)}).`);
+  }
   return {
     stage,
     packetPath: resolve(requireArg(args, "packet")),
     evidencePath: stage === "polish" ? resolve(requireArg(args, "evidence")) : null,
     baseUrl: stage === "deploy" ? requireArg(args, "base-url") : null,
     dryRun: args["dry-run"] === true,
+    buildEnvironment,
   };
 }
 
@@ -181,8 +209,13 @@ export function readPolishEvidenceFile(path) {
     }
     if (evidence.visual_review !== undefined && !isObject(evidence.visual_review)) {
       problems.push(`evidence.visual_review must be an object with a screenshots array (got ${typeName(evidence.visual_review)}).`);
-    } else if (isObject(evidence.visual_review) && Object.hasOwn(evidence.visual_review, "page_load")) {
-      problems.push(`evidence.visual_review.page_load is written only by ${cmd("polish")} capture; remove it from the file (the captured value on the report is kept).`);
+    } else if (isObject(evidence.visual_review)) {
+      // Package-owned keys are refused by name and listed first, so the
+      // refusal leads with its code.
+      const owned = PACKAGE_OWNED_VISUAL_REVIEW_KEYS.filter((key) => Object.hasOwn(evidence.visual_review, key));
+      if (owned.length) {
+        problems.unshift(`${PACKAGE_OWNED_KEY_REFUSAL}: ${owned.map((key) => `evidence.visual_review.${key}`).join(" and ")} ${owned.length === 1 ? "is" : "are"} written only by ${cmd("polish")} capture; remove ${owned.length === 1 ? "it" : "them"} from the file (the captured value on the report is kept).`);
+      }
     }
   }
   if (Object.hasOwn(input, "repair_loop_defect") && input.repair_loop_defect !== null && !isObject(input.repair_loop_defect)) {
@@ -235,10 +268,12 @@ function composeSetup(report, context, { now, recordedBy }) {
   return { report: nextReport, context: nextContext };
 }
 
-function composeBuild(report, { now, recordedBy, fingerprint }) {
+function composeBuild(report, { now, recordedBy, fingerprint, buildEnvironment = null }) {
   const sourcePackageFingerprint = currentSourcePackageMaterialFingerprint(report);
+  const previousAssembly = stageObject(report, "assembly");
   const assembly = {
-    ...withoutKeys(stageObject(report, "assembly"), ["source_package_material_fingerprint"]),
+    ...withoutKeys(previousAssembly, ["source_package_material_fingerprint"]),
+    ...(buildEnvironment ? { evidence: { ...(isObject(previousAssembly.evidence) ? previousAssembly.evidence : {}), build_environment: buildEnvironment } } : {}),
     stage: "assembly",
     status: "completed",
     build_fingerprint: fingerprint,
@@ -275,7 +310,7 @@ function composePolish(report, { now, recordedBy, fingerprint, input }) {
         ...input.evidence,
         visual_review: {
           ...input.evidence.visual_review,
-          ...(Object.hasOwn(previousVisual, "page_load") ? { page_load: previousVisual.page_load } : {}),
+          ...Object.fromEntries(PACKAGE_OWNED_VISUAL_REVIEW_KEYS.filter((key) => Object.hasOwn(previousVisual, key)).map((key) => [key, previousVisual[key]])),
         },
       }
     : previous.evidence;
@@ -580,6 +615,9 @@ function ladderProblems(stage, doctor, report) {
   if (gate) return [`next answers prepare-build: ${gate.reason}`];
   const problems = [];
   for (const earlier of NEXT_STAGE_ORDER.slice(0, NEXT_STAGE_ORDER.indexOf(stage))) {
+    // The rule next's stage picker reads: on the local preview a missing polish
+    // is carried forward (local-preview-policy), and next moves on to deploy.
+    if (earlier === "polish" && doctor.derived?.polish_gate?.status === CARRIED_FORWARD) continue;
     const key = reportKeyForCliStage(earlier);
     const status = String(report.stages[key]?.status || "");
     if (!stageIsTerminal(status)) {
@@ -697,7 +735,7 @@ function readPacketFile(stage, packetPath) {
  * composed or written.
  */
 export function recordStageCommand(args, { now = () => new Date(), beforeLock = null, afterDoctorRead = null, probe = null } = {}) {
-  const { stage, packetPath, evidencePath, dryRun } = parseRecordArgs(args);
+  const { stage, packetPath, evidencePath, dryRun, buildEnvironment } = parseRecordArgs(args);
   if (!existsSync(packetPath)) throw new Error(`record ${stage}: Build Packet not found at ${packetPath}; run ${cmd("start")} or ${cmd("prepare-build")} first.`);
   if (stage === "deploy" && !probe) throw new Error("record deploy needs the served-route probe; run it through recordCommand.");
   // Operator input, not target state: no campaigns-os writer produces it.
@@ -718,7 +756,7 @@ export function recordStageCommand(args, { now = () => new Date(), beforeLock =
   // A dry run writes nothing, so it takes no lock and creates no lock files
   // (the commitAssemblyReport preview convention); it reads in the same order.
   const run = () => recordUnderLock({
-    stage, packetPath, sidecars, lockedTarget, input, dryRun, timestamp, recordedBy, afterDoctorRead,
+    stage, packetPath, sidecars, lockedTarget, input, dryRun, timestamp, recordedBy, afterDoctorRead, buildEnvironment,
   });
   const recorded = dryRun ? run() : withTargetLockSync(lockedTarget, run, { command: `record ${stage}` });
   const { composed, facts, layer, reportPath, contextPath, after } = recorded;
@@ -735,6 +773,7 @@ export function recordStageCommand(args, { now = () => new Date(), beforeLock =
   ] : [
     `stages.${stageKey}.status = ${composed.report.stages[stageKey].status}`,
     ...(facts.fingerprint ? [`build output fingerprint ${facts.fingerprint} (doctor derived.build_output_fingerprint.value)`] : []),
+    ...(stage === "build" && buildEnvironment ? [`stages.assembly.evidence.build_environment = ${buildEnvironment}`] : []),
     ...(stage === "build" ? [`stages.polish.status = ${composed.report.stages.polish.status}`] : []),
     ...(composed.context ? ["Build Context scaffold.required = false"] : []),
   ];
@@ -767,7 +806,7 @@ export function recordStageCommand(args, { now = () => new Date(), beforeLock =
 // re-check, and the post-write doctor read for `next_stage`. No campaigns-os
 // writer can rebind, rewrite or republish any of them between the read and
 // the write.
-function recordUnderLock({ stage, packetPath, sidecars, lockedTarget, input, dryRun, timestamp, recordedBy, afterDoctorRead }) {
+function recordUnderLock({ stage, packetPath, sidecars, lockedTarget, input, dryRun, timestamp, recordedBy, afterDoctorRead, buildEnvironment = null }) {
   // The same workspace `next` resolves, so the record lands in the report
   // `next` reads now, not the one it read before the lock was free.
   const workspace = resolveCampaignWorkspace(packetPath, { ...sidecars, followContextPointer: true });
@@ -802,7 +841,7 @@ function recordUnderLock({ stage, packetPath, sidecars, lockedTarget, input, dry
     const next = stage === "setup"
       ? composeSetup(report, context, { now: timestamp, recordedBy })
       : stage === "build"
-        ? composeBuild(report, { now: timestamp, recordedBy, fingerprint: facts.fingerprint })
+        ? composeBuild(report, { now: timestamp, recordedBy, fingerprint: facts.fingerprint, buildEnvironment })
         : stage === "theme"
           ? composeTheme(report, { now: timestamp, recordedBy, layer })
           : stage === "deploy"