@nextcommerce/campaigns-os 1.61.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

@@ -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";
 
@@ -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,
@@ -519,12 +555,12 @@ const routeKey = (route) => String(route || "").replace(/^\/+|\/+$/g, "");
 // 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, context = null) {
+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(derived.target_repo, ".campaign-runtime/theme", BRAND_FONTS_FILENAME));
+    : (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);
@@ -616,10 +652,10 @@ function brandLayerFacts(doctor, context = null) {
       : `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,
@@ -1148,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"] : []),
@@ -1163,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 } : {}),
@@ -1175,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
@@ -1218,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, readJsonIfExists(contextPath));
+    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}. `