@nextcommerce/campaigns-os 1.60.0 → 1.62.0

package/src/spec-identity.mjs

@@ -19,6 +19,20 @@ export function specMaterialHash(spec) {
   return `sha256:${createHash("sha256").update(canonicalJson(materialSpec(spec))).digest("hex")}`;
 }
 
+// The spec material with every page's page_url left out (funnels[].pages[]
+// and the legacy funnel_pages[] mirror). Intake and record spec record it in
+// the Build Context, so record spec can tell a change of routes alone from
+// one that also touched anything else the build reads (#531).
+export function routeMaskedSpecMaterialHash(spec) {
+  if (!spec || typeof spec !== "object" || Array.isArray(spec)) return specMaterialHash(spec);
+  const masked = JSON.parse(JSON.stringify(spec));
+  const lists = [...(Array.isArray(masked.funnels) ? masked.funnels.map((funnel) => funnel?.pages) : []), masked.funnel_pages];
+  for (const pages of lists) {
+    for (const page of Array.isArray(pages) ? pages : []) if (page && typeof page === "object") delete page.page_url;
+  }
+  return specMaterialHash(masked);
+}
+
 // The three pure comparators live in `./spec-hash.mjs`, a dependency-free
 // leaf, so that browser-targeted consumers of the public
 // `./commercial-journey` export can reach them without pulling this module's

package/src/stage-ledger.mjs

@@ -11,6 +11,7 @@ import {
   NEXT_STAGE_CONTRACTS,
   NEXT_STAGE_OWNERS,
   stageIsBlocked,
+  stageIsTerminal,
 } from "./orchestration-stage-contract.mjs";
 
 const PRODUCER_STAGES = new Set(["doctor", "qa"]);
@@ -226,6 +227,20 @@ export function restorePolishKeptWithOutput(polish, { fingerprint, sourcePackage
   return { ...restored, stage: "polish", ...stamps };
 }
 
+/**
+ * True when the campaign has been handed off (#721): its deploy or its QA was
+ * completed, as the live record or as a record the stage's history keeps
+ * (a deploy or QA made owed again by a later change still happened). From
+ * then on the repo, not the design source, is the authority for which pages
+ * the funnel has, so `spec derive` adds and removes pages from the page tree
+ * and `record spec` binds that change without intake.
+ */
+export function campaignHandedOff(report) {
+  const completedIn = (stage) => isPlainObject(stage) && (isCompletedStatus(stage.status)
+    || (Array.isArray(stage.history) && stage.history.some((entry) => isPlainObject(entry) && isCompletedStatus(entry.status))));
+  return completedIn(report?.stages?.deploy) || completedIn(report?.stages?.qa);
+}
+
 /**
  * True when any stage of `report` carries a non-empty history: recorded
  * operator-visible state an intake must not silently drop.
@@ -573,6 +588,30 @@ export function qaRecordedBuildFingerprint(report) {
     || optionalString(report?.stages?.qa?.evidence?.source_build_fingerprint);
 }
 
+// #720: the build whose completed QA a page-scoped run extends. A completed
+// QA record extends its own build. A page-scoped run that did not complete
+// extends the build of the full QA it was based on, which was completed when
+// that run was accepted. Any other record (blocked or pending full QA, a
+// skip, a required stage) extends nothing, so it owes a full QA run.
+const QA_EXTENDABLE_STATUSES = Object.freeze(["completed", "completed_with_warnings"]);
+export function qaExtendedBuildFingerprint(report) {
+  const qa = report?.stages?.qa;
+  if (QA_EXTENDABLE_STATUSES.includes(qa?.status)) return qaRecordedBuildFingerprint(report);
+  if (qa?.status === "blocked") return optionalString(qa?.evidence?.page_scope?.base_build_fingerprint);
+  return null;
+}
+
+// The build Polish last reviewed: the output a terminal Polish is bound to,
+// or, once a rebuild has made it required, the build that rebuild kept for
+// it. A blocked or pending Polish reviewed nothing.
+export function polishReviewedBuild(polish) {
+  if (stageIsTerminal(String(polish?.status || ""))) return optionalString(polish.source_build_fingerprint);
+  // A brief or spec change since then (input_change, which only a restored
+  // or new Polish clears) owes the full review, whatever the build change.
+  if (Object.hasOwn(polish || {}, "input_change")) return null;
+  return polish?.status === "required" && polish.required_by === "build" ? optionalString(polish.owed_since_build_fingerprint) : null;
+}
+
 export function qaRecordedForCurrentBuild(report, buildFingerprint) {
   const recorded = qaRecordedBuildFingerprint(report);
   const current = optionalString(buildFingerprint);
@@ -716,7 +755,7 @@ function commitAssemblyReportUnderLock(workspace, mutate, {
       const doctor = refreshDoctor(outcome);
       if (doctor !== null && doctor !== undefined) writeDoctorSidecar(doctorOutPath, doctor, { command: command.trim(), targetRepo });
     } else if (outcome.written) {
-      markDoctorSidecarStale(targetRepo, { command: command.trim(), reason: staleReason.trim() });
+      markDoctorSidecarStale(targetRepo, { command: command.trim(), reason: staleReason.trim(), ...(doctorOutPath ? { path: doctorOutPath } : {}) });
     }
     return outcome;
   };

package/src/stage-record.mjs

@@ -23,12 +23,12 @@
 // stylesheets must also match the built output byte for byte).
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, statSync } from "node:fs";
-import { dirname, join, relative, resolve, sep } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import Ajv2020 from "ajv/dist/2020.js";
 
-import { BRAND_LAYER_FILENAMES } from "./brand-theme.mjs";
+import { BRAND_FONTS_FILENAME, BRAND_LAYER_FILENAMES } from "./brand-theme.mjs";
 import { ADAPTER_DECISION_SCALAR_VALUES } from "./adapter-decision-contract.mjs";
 import { buildManifestEntries, computeBuildFingerprint, resolveBuiltSiteScope } from "./built-site-scope.mjs";
 import { resolveCampaignWorkspace, targetRepoFor } from "./campaign-workspace.mjs";
@@ -36,7 +36,9 @@ import { isObject, optionalString, portableArtifactPaths, readJsonIfExists, requ
 import { LOCAL_PROOF_BUILD_ENVIRONMENT, LOCAL_PROOF_PRODUCTION_ENVIRONMENT, isLocalServePacket } from "./local-proof.mjs";
 import { polishCarriedForwardForLadder } from "./local-preview-policy.mjs";
 import { isLoopbackHostname } from "./remit.mjs";
-import { campaignRouteRoot } from "./route-identity.mjs";
+import { campaignRouteRoot, normalizePublicRouteSlug } from "./route-identity.mjs";
+import { buildChangeEntry, buildCommerceSignature, nextBuildChanges } from "./change-scope.mjs";
+import { assessEvidenceDebt } from "./evidence-debt.mjs";
 import { writeJsonAtomic } from "./doctor-sidecar.mjs";
 import { doctorPacket } from "./doctor/inspect.mjs";
 import { validateAssemblyReport } from "./doctor/checks.mjs";
@@ -52,7 +54,7 @@ import {
 import { evaluateRecordedHiddenEagerMediaCheckpoint } from "./polish-node.mjs";
 import { effectiveStageStatus, effectiveStatusIsTerminal, inputStamps, stageWriteInputs } from "./input-currency.mjs";
 import { demoteStages, recordBrief, recordSpec } from "./input-refresh.mjs";
-import { applyDerivedAssemblyReportSummary, archiveStageRecord, archiveSupersededRecord, assemblyReportMatchesPacket, commitAssemblyReport, inputChangeFor, restorePolishKeptWithOutput } from "./stage-ledger.mjs";
+import { applyDerivedAssemblyReportSummary, archiveStageRecord, archiveSupersededRecord, assemblyReportMatchesPacket, commitAssemblyReport, inputChangeFor, polishReviewedBuild, qaExtendedBuildFingerprint, qaRecordedBuildFingerprint, restorePolishKeptWithOutput } from "./stage-ledger.mjs";
 import { withTargetLockSync } from "./target-lock.mjs";
 import { commerceScopeFromScope } from "./theme-gate.mjs";
 
@@ -127,7 +129,7 @@ function typeName(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", "readability"]);
+export const PACKAGE_OWNED_VISUAL_REVIEW_KEYS = Object.freeze(["page_load", "media_weight", "readability", "captures", "element_parity"]);
 export const PACKAGE_OWNED_KEY_REFUSAL = "package_owned_key";
 
 export function refuseRecord(stage, problems) {
@@ -330,17 +332,39 @@ function currentStamps(inputs) {
   return Object.fromEntries(Object.entries(stamps).filter(([, value]) => value !== null));
 }
 
-function composeBuild(report, { now, recordedBy, fingerprint, manifest = null, buildEnvironment = null, adapterDecisions = null, fallbackAdapterDecisions = null, inputs = {}, deviationReason = null }) {
+// #707/#720: what this rebuild changed against the build recorded before it,
+// classified page-only or commerce-affecting, appended to the kept history so
+// a stage that reviewed an older build can still read its changed pages; and
+// the commerce signature of this output, for the next rebuild to compare
+// against. Read from the same packet and output doctor fingerprinted.
+function buildChangeFacts(report, { packet, packetPath, fingerprint, now }) {
+  if (!packet || !packetPath) return {};
+  const previousAssembly = stageObject(report, "assembly");
+  const targetRepo = targetRepoFor(packetPath, packet);
+  const slug = normalizePublicRouteSlug(packet?.campaign?.public_route_slug);
+  const outputRoot = join(targetRepo, "_site", slug);
+  const signature = buildCommerceSignature({ scope: resolveBuiltSiteScope(outputRoot), outputRoot, targetRepo, publicRouteSlug: slug });
+  const from = optionalString(previousAssembly.build_fingerprint);
+  if (!from || from === fingerprint) return { signature, buildChanges: previousAssembly.build_changes };
+  const debt = assessEvidenceDebt({ packet, packetPath, report });
+  const entry = buildChangeEntry({ from, to: fingerprint, at: now, changes: debt.changes,
+    classification: { kind: debt.changes.kind, reasons: debt.changes.reasons } });
+  const anchors = [qaRecordedBuildFingerprint(report), qaExtendedBuildFingerprint(report), polishReviewedBuild(stageObject(report, "polish"))];
+  return { signature, buildChanges: nextBuildChanges(previousAssembly.build_changes, entry, anchors) };
+}
+
+function composeBuild(report, { now, recordedBy, fingerprint, manifest = null, buildEnvironment = null, adapterDecisions = null, fallbackAdapterDecisions = null, inputs = {}, deviationReason = null, packet = null, packetPath = null }) {
   const nextReport = adapterDecisions ? { ...report, adapter_decisions: { ...(report.adapter_decisions || fallbackAdapterDecisions || {}), ...adapterDecisions } } : report;
   const sourcePackageFingerprint = currentSourcePackageMaterialFingerprint(report);
   const previousAssembly = stageObject(report, "assembly");
+  const { signature, buildChanges } = buildChangeFacts(report, { packet, packetPath, fingerprint, now });
   const stamps = currentStamps(inputs);
   // A replaced completed record whose stamps differ from the current inputs
   // records the change now, if nothing recorded it before.
   const writeInputs = stageWriteInputs("assembly", inputs);
   const detected = REPLACED_COMPLETED_STATUSES.includes(previousAssembly.status) ? writeInputs.detectChange(previousAssembly) : null;
   let assembly = {
-    ...withoutKeys(previousAssembly, ["source_package_material_fingerprint", "unchanged_output_reason", "build_manifest", ...STAMP_FIELDS]),
+    ...withoutKeys(previousAssembly, ["source_package_material_fingerprint", "unchanged_output_reason", "build_manifest", "commerce_signature", "build_changes", ...STAMP_FIELDS]),
     ...(buildEnvironment ? { evidence: { ...(isObject(previousAssembly.evidence) ? previousAssembly.evidence : {}), build_environment: buildEnvironment } } : {}),
     stage: "assembly",
     status: "completed",
@@ -349,6 +373,14 @@ function composeBuild(report, { now, recordedBy, fingerprint, manifest = null, b
     // (doctor's built_output.fingerprint_stale, polish capture) can name the
     // files that differ. Left out when it cannot be read back as this value.
     ...(manifest ? { build_manifest: manifest } : {}),
+    // One hash per built page over its commerce-bearing markup, and one of
+    // the campaign's Page Kit config entry, so the next change can be read
+    // as page-only or commerce-affecting (change-scope.mjs).
+    ...(signature ? { commerce_signature: signature } : {}),
+    // The rebuilds since the builds Polish and QA last reviewed, each with
+    // its changed pages and classification, so the changed-page list
+    // survives this record (readback evidence_debt.<stage>.change).
+    ...(Array.isArray(buildChanges) && buildChanges.length ? { build_changes: buildChanges } : {}),
     ...(sourcePackageFingerprint ? { source_package_material_fingerprint: sourcePackageFingerprint } : {}),
     ...stamps,
     completed_at: now,
@@ -393,14 +425,18 @@ function composeBuild(report, { now, recordedBy, fingerprint, manifest = null, b
   if (keptPolish) return { report: { ...nextReport, stages: { ...nextReport.stages, assembly, polish: keptPolish, ...deploy } }, context: null };
   const polishStillCurrent = stageIsTerminal(String(previousPolish.status || ""))
     && optionalString(previousPolish.source_build_fingerprint) === fingerprint;
+  // The build Polish reviewed stays named once its binding is cleared, so a
+  // page-only change since then reads as advisory (evidence-debt.mjs).
+  const reviewed = polishReviewedBuild(previousPolish);
   const polish = polishStillCurrent
     ? previousPolish
     : {
-        ...withoutKeys(previousPolish, ["performed_by", "source_build_fingerprint", "source_package_material_fingerprint", "completed_at", "recorded_by", ...STAMP_FIELDS]),
+        ...withoutKeys(previousPolish, ["performed_by", "source_build_fingerprint", "source_package_material_fingerprint", "completed_at", "recorded_by", "owed_since_build_fingerprint", ...STAMP_FIELDS]),
         stage: "polish",
         status: "required",
         required_by: "build",
         required_for: ["qa"],
+        ...(reviewed ? { owed_since_build_fingerprint: reviewed } : {}),
       };
   return { report: { ...nextReport, stages: { ...nextReport.stages, assembly, polish, ...deploy } }, context: null };
 }
@@ -456,7 +492,7 @@ function composePolish(report, { now, recordedBy, fingerprint, input, inputs = {
     : previous.evidence;
   const sourcePackageFingerprint = currentSourcePackageMaterialFingerprint(report);
   let polish = {
-    ...withoutKeys(previous, ["source_package_material_fingerprint", "completed_at", "skip_reason", "evidence", ...STAMP_FIELDS]),
+    ...withoutKeys(previous, ["source_package_material_fingerprint", "completed_at", "skip_reason", "evidence", "owed_since_build_fingerprint", ...STAMP_FIELDS]),
     stage: "polish",
     status: input.status,
     performed_by: POLISH_PRODUCER,
@@ -512,10 +548,24 @@ const routeKey = (route) => String(route || "").replace(/^\/+|\/+$/g, "");
 // family components, so it must load a brand layer (brand-theme.css or
 // checkout-brand.css) after it, and that file must be in the built output. A
 // page that loads neither renders the design's own markup and needs no brand
-// layer (docs/brand-theme-bridge.md, "Where next-core.css belongs"). Any page
+// layer (docs/brand-theme-bridge.md, "Where next-core.css belongs"). When
+// theme generate wrote brand-fonts.css (the design's own faces), each styled
+// page must load the campaign's copy too, or the families brand-theme.css
+// names fall back to the system font. Where it was written is the Build
+// Context's theme.generated.fonts_css_path (theme generate --out-dir moves
+// it); the default path is read only when the context names none. Any page
 // that breaks the rule is a refusal naming the page.
-function brandLayerFacts(doctor) {
+function brandLayerFacts(doctor, context = null, runtimeDir = resolve(doctor.derived?.target_repo || ".", ".campaign-runtime")) {
   const derived = doctor.derived || {};
+  const recordedFonts = context?.theme?.generated?.fonts_css_path;
+  const generatedFonts = typeof recordedFonts === "string" && recordedFonts
+    ? resolve(derived.target_repo, recordedFonts)
+    : (context?.theme?.generated ? null : resolve(runtimeDir, "theme", BRAND_FONTS_FILENAME));
+  const fontsRequired = Boolean(generatedFonts) && existsSync(generatedFonts);
+  const insideSite = (file) => {
+    const rel = relative(site.site_root, file);
+    return Boolean(rel) && !rel.startsWith("..") && !isAbsolute(rel);
+  };
   const commerce = commerceScopeFromScope(derived.scope);
   if (!commerce.all.length) {
     throw refuseRecord("theme", ["The campaign ships no commerce pages, so there is no brand layer to record; the theme gate does not apply."]);
@@ -566,6 +616,30 @@ function brandLayerFacts(doctor) {
       problems.push(`${label}: ${builtRel} links ${hrefs[brand]}, which is not in the built output.`);
       continue;
     }
+    // brand-fonts.css holds only @font-face rules, so unlike the brand layer
+    // its position relative to next-core.css does not matter.
+    if (fontsRequired) {
+      const fontsHref = hrefs.find((candidate) => hrefName(candidate) === BRAND_FONTS_FILENAME);
+      const bare = fontsHref ? fontsHref.split(/[?#]/)[0] : null;
+      const fontsFile = bare && !/^(?:[a-z][a-z0-9+.-]*:)?\/\//i.test(bare)
+        ? (bare.startsWith("/") ? join(site.site_root, bare) : resolve(dirname(built.built_path), bare))
+        : null;
+      const generatedRel = relative(derived.target_repo, generatedFonts);
+      const problem = !fontsHref
+        ? `${label}: ${builtRel} links no ${BRAND_FONTS_FILENAME}. Theme generate wrote the design's font faces to ${generatedRel}; copy it into the campaign assets/css folder beside the brand layer, list it in the page's frontmatter styles and rebuild.`
+        : !fontsFile || !insideSite(fontsFile)
+          ? `${label}: ${builtRel} links ${fontsHref}, which is not a file in this campaign's built output; link the campaign's own copy of ${generatedRel}.`
+          : !existsSync(fontsFile)
+            ? `${label}: ${builtRel} links ${fontsHref}, which is not in the built output.`
+            : readFileSync(fontsFile, "utf8") !== readFileSync(generatedFonts, "utf8")
+              ? `${label}: ${builtRel} links ${fontsHref}, which differs from the generated ${generatedRel}; copy the generated file and rebuild.`
+              : null;
+      if (problem) {
+        problems.push(problem);
+        continue;
+      }
+      evidence.push(`${label}: ${builtRel} loads ${relative(derived.target_repo, fontsFile)}, identical to the generated ${generatedRel}.`);
+    }
     layers.push(file);
     styled.push(label);
     evidence.push(`${label}: ${builtRel} loads ${relative(derived.target_repo, file)} after ${CORE_STYLESHEET}.`);
@@ -578,10 +652,10 @@ function brandLayerFacts(doctor) {
       : `No built commerce page loads ${CORE_STYLESHEET} (${unstyled.join(", ")}${outOfScope.length ? `; declared but not built: ${outOfScope.join(", ")}` : ""}), so no page renders family components for a brand layer to style. If shipping without one is intended, record that with ${cmd("theme")} waive.`]);
   }
   const cssPath = relative(derived.target_repo, layers[0]);
-  const generated = resolve(derived.target_repo, ".campaign-runtime/theme/brand-theme.css");
+  const generated = resolve(runtimeDir, "theme/brand-theme.css");
   if (existsSync(generated)) {
     const same = readFileSync(generated, "utf8") === readFileSync(layers[0], "utf8");
-    evidence.push(`${cssPath} ${same ? "matches" : "differs from"} the generated .campaign-runtime/theme/brand-theme.css.`);
+    evidence.push(`${cssPath} ${same ? "matches" : "differs from"} the generated ${relative(derived.target_repo, generated).split(sep).join("/")}.`);
   }
   return {
     cssPath,
@@ -865,7 +939,7 @@ function validateRecord(stage, { report, context, packet, fingerprint }) {
     // over the report this record would write. A blocked or skipped Polish is
     // not a pass the gate could grant; doctor keeps QA blocked on it.
     const hiddenEagerMediaGate = evaluateRecordedHiddenEagerMediaCheckpoint({ packet, report });
-    const gate = evaluatePolishGate({ report, hiddenEagerMediaGate, currentOutputFingerprint: fingerprint });
+    const gate = evaluatePolishGate({ report, hiddenEagerMediaGate, currentOutputFingerprint: fingerprint, newEvidence: true });
     if (gate.status === "blocked") {
       problems.push(`${gate.code}: ${gate.reason}`);
       for (const problem of gate.problems || []) problems.push(problem);
@@ -1110,6 +1184,7 @@ export function recordStageCommand(args, { now = () => new Date(), beforeLock =
     ...(stage === "build" && Array.isArray(composed.report.stages.assembly.build_manifest) ? [`stages.assembly.build_manifest lists ${composed.report.stages.assembly.build_manifest.length} file(s), so a later fingerprint mismatch names the paths that differ`] : []),
     ...(stage === "build" && buildEnvironment ? [`stages.assembly.evidence.build_environment = ${buildEnvironment}`] : []),
     ...(stage === "build" && adapterDecisions ? Object.entries(adapterDecisions).map(([key, value]) => `report.adapter_decisions.${key} = ${value}`) : []),
+    ...(stage === "build" ? buildChangeReadyLines(composed.report.stages.assembly) : []),
     ...(stage === "build" ? [`stages.polish.status = ${composed.report.stages.polish.status}`] : []),
     ...(stage === "build" && composed.report.stages.deploy?.required_by === "build" ? [`stages.deploy.status = ${composed.report.stages.deploy.status} (the recorded deploy probed other output; run ${cmd("record")} deploy again)`] : []),
     ...(composed.context ? ["Build Context scaffold.required = false"] : []),
@@ -1125,7 +1200,7 @@ export function recordStageCommand(args, { now = () => new Date(), beforeLock =
     ...(dryRun ? { would_write: writes } : { written: writes }),
     build_fingerprint: facts.fingerprint || null,
     // The manifest is kept in the report, not echoed: it lists every built file.
-    record: stage === "theme" ? composed.report.theme : stage === "build" ? withoutKeys(composed.report.stages.assembly, ["build_manifest"]) : composed.report.stages[stageKey],
+    record: stage === "theme" ? composed.report.theme : stage === "build" ? withoutKeys(composed.report.stages.assembly, ["build_manifest", "commerce_signature"]) : composed.report.stages[stageKey],
     ...(stage === "build" ? { polish: composed.report.stages.polish } : {}),
     ...(composed.context ? { scaffold: composed.context.scaffold } : {}),
     ...(stage === "polish" && input.hasRepairLoopDefect ? { repair_loop_defect: input.repairLoopDefect } : {}),
@@ -1137,6 +1212,14 @@ export function recordStageCommand(args, { now = () => new Date(), beforeLock =
   };
 }
 
+// One line for the rebuild this record kept, when it replaced another build.
+function buildChangeReadyLines(assembly) {
+  const latest = Array.isArray(assembly.build_changes) ? assembly.build_changes.at(-1) : null;
+  if (!latest || latest.build_fingerprint !== assembly.build_fingerprint) return [];
+  const pages = latest.changed_pages.map((page) => page.page_id).join(", ") || "none";
+  return [`stages.assembly.build_changes: this rebuild is ${latest.kind.replace("_", "-")} (changed pages: ${pages}${latest.unmapped_file_count ? `; ${latest.unmapped_file_count} file(s) outside any page` : ""})`];
+}
+
 // Everything a record reads from the target, in order, all under the target
 // lock (except a dry run, which writes nothing): the packet and the Build
 // Context's report pointer (the workspace), the report, the Build Context
@@ -1180,12 +1263,12 @@ function recordUnderLock({ stage, packetPath, sidecars, lockedTarget, input, dry
     }
     facts = doctorFacts(stage, doctor, report, packet);
     if (typeof afterDoctorRead === "function") afterDoctorRead();
-    if (stage === "theme") layer = brandLayerFacts(doctor);
+    if (stage === "theme") layer = brandLayerFacts(doctor, readJsonIfExists(contextPath), workspace.runtimeDir);
     if (stage === "deploy") deployFacts(doctor, packet, input, facts.fingerprint);
     const next = stage === "setup"
       ? composeSetup(report, context, { now: timestamp, recordedBy })
       : stage === "build"
-        ? composeBuild(report, { now: timestamp, recordedBy, fingerprint: facts.fingerprint, manifest: outputManifest(facts), buildEnvironment, adapterDecisions, fallbackAdapterDecisions: adapterDecisions && !report.adapter_decisions ? readJsonIfExists(contextPath)?.adapter_decisions || packet.source_html?.adapter_contract : null, inputs: recordInputs(doctor), deviationReason })
+        ? composeBuild(report, { now: timestamp, recordedBy, fingerprint: facts.fingerprint, manifest: outputManifest(facts), buildEnvironment, adapterDecisions, fallbackAdapterDecisions: adapterDecisions && !report.adapter_decisions ? readJsonIfExists(contextPath)?.adapter_decisions || packet.source_html?.adapter_contract : null, inputs: recordInputs(doctor), deviationReason, packet, packetPath })
         : stage === "theme"
           ? composeTheme(report, { now: timestamp, recordedBy, layer })
           : stage === "deploy"

package/src/target-lock.mjs

@@ -22,9 +22,19 @@ export function targetLockPath(targetRepo) {
 // holds it, only a pid, so the holder is described generically. A lock with
 // no owner record is called out on its own: it is never taken over, and the
 // operator needs to know it will not clear by waiting. So is anything at the
-// lock path that is not a lock at all, named by what it is (#514).
+// lock path that is not a lock at all, named by what it is, and a lock held
+// by a live process of another campaigns-os release, which is refused at once
+// (#514).
 function unavailable(targetRepo, lockPath, command) {
   return (error) => {
+    if (error?.code === "ELOCKFORMAT") {
+      return Object.assign(new Error(
+        `${command}: the target lock at ${lockPath} is held by process ${error.holderPid}, which runs a different campaigns-os release. `
+        + "Two releases taking this lock at the same moment can both get it, so this run stops instead of waiting. "
+        + `Let that run finish, then retry with one campaigns-os release working on ${targetRepo} at a time.`,
+        { cause: error },
+      ), { code: error.code, holderPid: error.holderPid, lockFormat: error.lockFormat });
+    }
     if (error?.code === "ENOTLOCK") {
       return Object.assign(new Error(
         `${command}: the target lock path ${lockPath} is occupied by ${error.obstruction}. `

package/src/theme-gate.mjs

@@ -166,13 +166,13 @@ export function evaluateThemeGate({ reportTheme = null, contextTheme = null, sco
         id: "theme_generate",
         kind: "command",
         command: `campaigns-os theme generate --packet ${packetArg}`,
-        description: "Generate .campaign-runtime/theme/brand-theme.css from the inspected source tokens.",
+        description: "Generate .campaign-runtime/theme/brand-theme.css from the inspected source tokens, and brand-fonts.css beside it when the design source ships the faces its headings, body copy or buttons use.",
       },
       {
         id: "apply_brand_layer",
         kind: "manual",
         command: null,
-        description: `Copy brand-theme.css into the campaign assets/css folder, list it after next-core.css in the frontmatter styles of the commerce pages that render family components, rebuild, run campaigns-os record build, then campaigns-os record theme --packet ${packetArg}, which records report.theme from the built pages.`,
+        description: `Copy brand-theme.css (and brand-fonts.css, when theme generate wrote one) into the campaign assets/css folder, list brand-theme.css after next-core.css, and brand-fonts.css anywhere, in the frontmatter styles of the commerce pages that render family components, rebuild, run campaigns-os record build, then campaigns-os record theme --packet ${packetArg}, which records report.theme from the built pages.`,
       },
       {
         id: "waive_theme",