@nextcommerce/campaigns-os 1.61.0 → 1.62.0

package/src/input-refresh.mjs

@@ -12,11 +12,16 @@
 // brief from the brief file last saved by intake or record brief (never by
 // discovery), and makes build, Polish and QA owed again unless a stage was
 // already recorded against the new content; waivers, accepts, the theme,
-// the packet and the setup and deploy records are never touched. Refusals
-// are checked in a fixed order before anything is written; --dry-run runs
-// every check and writes nothing.
-import { createHash } from "node:crypto";
-import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+// the packet and the setup and deploy records are never touched, except when
+// the active pages changed in a way record spec binds (#531, #721): a move of
+// routes alone, or on a handed-off campaign a page added or removed. Then the
+// packet's and the Build Context's page-kit projection, the Design Source
+// Package's page surfaces and the three references to that package are
+// rewritten too, and deploy is owed again when the set of built pages
+// changes. Refusals are checked in a fixed order before anything is written;
+// --dry-run runs every check and writes nothing.
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 
 import {
@@ -27,6 +32,8 @@ import {
 } from "./build-brief.mjs";
 import { resolveCampaignWorkspace, targetRepoFor } from "./campaign-workspace.mjs";
 import { isObject, optionalString, portableArtifactPaths, relFromDir, resolveFromFile } from "./cli-helpers.mjs";
+import { createDesignSourcePackageArtifactReference, hashSerializedDesignSourcePackage, rebindDesignSourcePackagePages, serializeDesignSourcePackage, validateDesignSourcePackage } from "./design-source-package.mjs";
+import { readPriorDesignSourceProvenance, recordPendingDesignSourceProvenance } from "./design-source-publication.mjs";
 import { writeJsonAtomic } from "./doctor-sidecar.mjs";
 import { activeSpecPages, specIdentityMismatch } from "./doctor/checks.mjs";
 import {
@@ -42,9 +49,11 @@ import {
   wellFormedBriefMaterial,
 } from "./input-currency.mjs";
 import { cmd } from "./install-invocation.mjs";
-import { publicRouteForPage } from "./source-html-intake.mjs";
-import { specHashesMatch } from "./spec-identity.mjs";
-import { archiveSupersededRecord, assemblyReportMatchesPacket, commitAssemblyReport, inputChangeFor } from "./stage-ledger.mjs";
+import { campaignRouteRoot, intakeRouteRoot, normalizePublicRouteSlug, specPublicRouteSlug } from "./route-identity.mjs";
+import { projectPageKitTargets, publicRouteForPage } from "./source-html-intake.mjs";
+import { staleRoutingHints } from "./spec-derive.mjs";
+import { routeMaskedSpecMaterialHash, specHashesMatch } from "./spec-identity.mjs";
+import { archiveSupersededRecord, assemblyReportMatchesPacket, campaignHandedOff, commitAssemblyReport, inputChangeFor } from "./stage-ledger.mjs";
 import { refuseRecord } from "./stage-record.mjs";
 import { withTargetLockSync } from "./target-lock.mjs";
 
@@ -219,14 +228,33 @@ function briefTooLarge(path) {
   return entries > BRIEF_MAX_DESIGN_AUTHORITY_ENTRIES ? `${path} has ${entries} design_authority entries; the limit is ${BRIEF_MAX_DESIGN_AUTHORITY_ENTRIES}.` : null;
 }
 
-const sameActivePages = (a, b) => a.length === b.length && a.every((page, index) => page.id === b[index]?.id && (page.page_url ?? null) === (b[index]?.page_url ?? null));
+// An active page as the Build Context records it.
+const recordedActivePage = (page) => ({ id: page.id, type: page.type || null, label: page.label || null, page_url: publicRouteForPage(page) });
 
-// True when the CampaignSpec's active pages (ids, order or routes) differ
-// from the ones intake recorded in the Build Context (or none are recorded).
-function pageScopeChanged(spec, context) {
+/**
+ * How the CampaignSpec's active pages differ from the ones the Build Context
+ * records, split the way record spec binds them (#531, #721): page identity
+ * (`added` and `removed` ids, and whether the pages both lists keep are in
+ * another order) and routes (`moved`: kept pages whose route changed).
+ * `changed` is true when anything differs, or when the context records no
+ * pages, or a page id twice (then `unbindable`, as a reorder is).
+ */
+export function pageScopeChange(spec, context) {
   const recorded = Array.isArray(context?.spec?.active_pages) ? context.spec.active_pages : null;
-  const derived = activeSpecPages(spec).map((page) => ({ id: page.id, page_url: publicRouteForPage(page) }));
-  return !recorded || !sameActivePages(derived, recorded);
+  const current = activeSpecPages(spec).map(recordedActivePage);
+  if (!recorded) return { recorded: false, current, added: [], removed: [], moved: [], reordered: false, unbindable: true, changed: true };
+  const recordedIds = recorded.map((page) => page?.id);
+  const currentIds = current.map((page) => page.id);
+  const duplicate = new Set(recordedIds).size !== recordedIds.length || new Set(currentIds).size !== currentIds.length;
+  const added = currentIds.filter((id) => !recordedIds.includes(id));
+  const removed = recordedIds.filter((id) => !currentIds.includes(id));
+  const keptRecorded = recordedIds.filter((id) => currentIds.includes(id));
+  const keptCurrent = currentIds.filter((id) => recordedIds.includes(id));
+  const reordered = keptRecorded.length !== keptCurrent.length || keptRecorded.some((id, index) => id !== keptCurrent[index]);
+  const recordedById = new Map(recorded.map((page) => [page?.id, page]));
+  const moved = current.filter((page) => recordedById.has(page.id) && (page.page_url ?? null) !== (recordedById.get(page.id)?.page_url ?? null)).map((page) => page.id);
+  const unbindable = duplicate || reordered;
+  return { recorded: true, current, added, removed, moved, reordered, unbindable, changed: unbindable || added.length > 0 || removed.length > 0 || moved.length > 0 };
 }
 
 // The files Campaigns OS writes itself, which a brief path must never name.
@@ -292,8 +320,8 @@ function briefRefusal({ candidates, packageArtifacts, context, spec, report }) {
   if (!current || !bound || current !== `sha256:${bound.replace(/^sha256:/, "")}`) {
     return ["spec_changed_run_record_spec", `the CampaignSpec material (${current || "unreadable"}) differs from the one the Assembly Report binds (${bound || "none"}); save the spec change with ${cmd("record")} spec first.`];
   }
-  if (pageScopeChanged(spec, context)) {
-    return ["page_scope_changed", "the CampaignSpec's active pages (ids, order or routes) differ from the Build Context's spec.active_pages; a page-scope change needs intake."];
+  if (pageScopeChange(spec, context).changed) {
+    return ["page_scope_changed", `the CampaignSpec's active pages (ids, order or routes) differ from the Build Context's spec.active_pages; bind the page change with ${cmd("record")} spec first (a routes-only change, or a page added or removed after handoff), or re-run intake for any other.`];
   }
   return null;
 }
@@ -531,6 +559,17 @@ function readSpecFile(specPath) {
   }
 }
 
+// A text file written whole or not at all: staged beside it, then renamed.
+function writeTextAtomic(path, text) {
+  const staged = join(dirname(path), `.${relative(dirname(path), path)}.${randomUUID()}.tmp`);
+  try {
+    writeFileSync(staged, text, { flag: "wx" });
+    renameSync(staged, path);
+  } finally {
+    rmSync(staged, { force: true });
+  }
+}
+
 // The brief file last saved, by intake or record brief: its --brief path,
 // otherwise the file that save found; never discovery. Null when intake
 // generated the guided draft and no brief file was saved since.
@@ -544,19 +583,206 @@ function recordedBriefFile(context, { targetRepo, previousNormalizedBrief }) {
 
 // Every record spec refusal, in the fixed order: the spec checks first (the
 // page-scope comparison needs a readable spec of the bound identity), then
-// the recorded brief file. Returns [code, detail] or null.
-function specRefusal({ read, specPath, packet, report, context, briefFile, packageArtifacts }) {
-  if (!read) return ["spec_unreadable", `the CampaignSpec at ${specPath || "(the packet names no spec.local_path)"} could not be read as a JSON object; restore it, then run ${cmd("record")} spec again.`];
+// the page rebind's own checks, then the recorded brief file. Returns
+// { refusal: [code, detail] | null, rebind } where `rebind` is the page
+// rebind plan (null when the active pages are the ones recorded).
+function specRefusal({ read, specPath, packet, packetPath, report, reportPath, context, targetRepo, briefFile, packageArtifacts }) {
+  const refuse = (code, detail) => ({ refusal: [code, detail], rebind: null });
+  if (!read) return refuse("spec_unreadable", `the CampaignSpec at ${specPath || "(the packet names no spec.local_path)"} could not be read as a JSON object; restore it, then run ${cmd("record")} spec again.`);
   const packetKind = specIdentityMismatch(read.spec, packet.spec);
   const reportKind = isObject(report.identity) ? specIdentityMismatch(read.spec, report.identity) : null;
   if (packetKind || reportKind) {
-    return ["spec_identity_changed", `the CampaignSpec's ${(packetKind || reportKind) === "local_spec" ? "local_spec_id" : "map_id"} names another campaign than the ${packetKind ? "Build Packet" : "Assembly Report"} binds; point spec.local_path at this campaign's spec. A new campaign identity needs intake.`];
+    return refuse("spec_identity_changed", `the CampaignSpec's ${(packetKind || reportKind) === "local_spec" ? "local_spec_id" : "map_id"} names another campaign than the ${packetKind ? "Build Packet" : "Assembly Report"} binds; point spec.local_path at this campaign's spec. A new campaign identity needs intake.`);
+  }
+  const scope = pageScopeChange(read.spec, context);
+  const intake = `${cmd("prepare-build")}; with --force it clears recorded stage evidence and operator decisions, archiving the build, Polish and QA records`;
+  if (scope.unbindable) {
+    return refuse("page_scope_changed", `the CampaignSpec's active pages are ${scope.recorded ? "in another order than" : "not comparable with"} the Build Context's spec.active_pages. record spec binds a move of routes, and after handoff a page added or removed; a reorder needs intake (${intake}).`);
   }
-  if (pageScopeChanged(read.spec, context)) {
-    return ["page_scope_changed", `the CampaignSpec's active pages (ids, order or routes) differ from the Build Context's spec.active_pages. The Design Source Package and the source mapping are built per page, so a page-scope change needs intake (${cmd("prepare-build")}); with --force it clears recorded stage evidence and operator decisions, archiving the build, Polish and QA records.`];
+  if ((scope.added.length || scope.removed.length) && !campaignHandedOff(report)) {
+    return refuse("page_scope_changed", `the CampaignSpec ${[scope.added.length ? `adds ${scope.added.map((id) => `"${id}"`).join(", ")}` : null, scope.removed.length ? `removes ${scope.removed.map((id) => `"${id}"`).join(", ")}` : null].filter(Boolean).join(" and ")} against the Build Context's spec.active_pages. Before handoff (no deploy or QA completed) the design source decides the pages, and the Design Source Package and the source mapping are built per page, so a page added or removed needs intake (${intake}).`);
   }
-  if (!briefFile) return null;
-  return briefFileRefusal([briefFile], packageArtifacts, (file) => `the brief file last saved, ${briefFile.path}, ${file?.why || "does not exist"}; restore it, or save a brief file with ${cmd("record")} brief --brief <file>.`);
+  let rebind = null;
+  if (scope.changed) {
+    const planned = planPageRebind({ spec: read.spec, packet, packetPath, report, reportPath, context, targetRepo, scope });
+    if (planned.refusal) return { refusal: planned.refusal, rebind: null };
+    rebind = planned;
+  }
+  if (!briefFile) return { refusal: null, rebind };
+  const fileRefusal = briefFileRefusal([briefFile], packageArtifacts, (file) => `the brief file last saved, ${briefFile.path}, ${file?.why || "does not exist"}; restore it, or save a brief file with ${cmd("record")} brief --brief <file>.`);
+  return { refusal: fileRefusal, rebind: fileRefusal ? null : rebind };
+}
+
+const canonicalJson = (value) => {
+  if (value === null || typeof value !== "object") return JSON.stringify(value ?? null);
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`;
+};
+
+/**
+ * What binding the changed active pages writes (#531, #721), or the refusal
+ * that stops it. Every page is re-projected to its page-kit target (a page's
+ * next_url reads the routes of the pages it links to). Refused, in order:
+ * a move of the route root or slug, a routing hint left stale, two pages on
+ * one target, and a Design Source Package record spec cannot rewrite (one
+ * prepare-build did not synthesize, or one edited since it was recorded).
+ * Returns the next packet pages and page map, the rewritten package (or
+ * null when its bytes do not change), whether the build's targets or the set
+ * of built pages changed, and whether the change touched routes alone.
+ */
+function planPageRebind({ spec, packet, packetPath, report, reportPath, context, targetRepo, scope }) {
+  const refuse = (code, detail) => ({ refusal: [code, detail] });
+  const slug = normalizePublicRouteSlug(packet.campaign?.public_route_slug);
+  const specSlug = specPublicRouteSlug(spec);
+  const packetRoot = campaignRouteRoot(packet);
+  const declaredRoot = optionalString(spec.spec_identity?.route_root) || optionalString(spec.campaign?.route_root);
+  const specRoot = declaredRoot ? intakeRouteRoot(declaredRoot, slug) : null;
+  if ((specSlug && specSlug !== slug) || (declaredRoot && specRoot !== packetRoot)) {
+    return refuse("route_root_changed", `the CampaignSpec ${specSlug && specSlug !== slug ? `names route slug "${specSlug}"` : `declares route_root ${JSON.stringify(declaredRoot)}`}, but the packet serves the campaign at ${packetRoot || "(no route root)"}; the recorded preview and deploy are rooted there, so moving the route root or slug needs intake (${cmd("prepare-build")}).`);
+  }
+  const stale = staleRoutingHints(spec, { publicRouteSlug: slug });
+  if (stale.length) {
+    return refuse("routing_hint_stale", `the CampaignSpec's routing hints name routes their pages no longer have: ${stale.map((hint) => `${hint.page_id} sdk_hints.meta_tags.${hint.tag} ${JSON.stringify(hint.value)} (page "${hint.target_page_id}" routes to ${JSON.stringify(hint.derived_route)})`).join("; ")}. The built meta tag follows the hint, so shoppers would be sent to the old path. Edit each hint to the route shown in the spec (${cmd("spec")} derive rewrites the ones on an edge it re-points after handoff; while the Map is still the spec's source, re-saving it regenerates them), then run ${cmd("record")} spec again.`);
+  }
+
+  const activePages = activeSpecPages(spec);
+  const pageById = new Map(activePages.map((page) => [page.id, page]));
+  const outputDir = optionalString(packet.assembly?.output_dir) || `src/${slug}`;
+  const projections = projectPageKitTargets({ specPages: activePages, publicRouteSlug: slug, outputDir });
+  const removed = new Set(scope.removed);
+  const previousPages = Array.isArray(packet.source_html?.pages) ? packet.source_html.pages : [];
+  const nextPages = [];
+  for (const entry of previousPages) {
+    if (!isObject(entry) || removed.has(entry.page_id)) continue;
+    nextPages.push(isObject(entry.page_kit) && projections.has(entry.page_id) ? { ...entry, page_kit: projections.get(entry.page_id) } : entry);
+  }
+  for (const id of scope.added) {
+    nextPages.push({ page_id: id, ...(optionalString(pageById.get(id)?.type) ? { page_type: pageById.get(id).type } : {}), origin: "repo", page_kit: projections.get(id) });
+  }
+  const byTarget = new Map();
+  for (const entry of nextPages) {
+    const target = entry.page_kit?.output_path;
+    if (!target) continue;
+    if (byTarget.has(target)) {
+      return refuse("page_kit_target_conflict", `pages "${byTarget.get(target)}" and "${entry.page_id}" both project to page-kit target ${target}; give one page a distinct route, then run ${cmd("record")} spec again.`);
+    }
+    byTarget.set(target, entry.page_id);
+  }
+  const kitOf = (entries) => new Map(entries.filter((entry) => isObject(entry?.page_kit)).map((entry) => [entry.page_id, canonicalJson(entry.page_kit)]));
+  const differs = (before, after) => before.size !== after.size || [...after].some(([id, kit]) => before.get(id) !== kit);
+  const afterKits = kitOf(nextPages);
+  // Compared with the Build Context's page map as well as the packet's: a
+  // run that stopped after writing the packet leaves the packet already
+  // re-projected, and the Context still says what was built.
+  const projectionChanged = differs(kitOf(previousPages), afterKits) || differs(kitOf(Array.isArray(context.page_map) ? context.page_map : []), afterKits);
+  const routesOf = (entries) => [...new Set(entries.filter((entry) => isObject(entry?.page_kit)).map((entry) => entry.page_kit.public_route))].sort();
+  const builtPagesChanged = canonicalJson(routesOf(previousPages)) !== canonicalJson(routesOf(nextPages));
+  // A moved page with no page-kit target (out of scope, not built) still
+  // moves a URL QA reads, so it counts as a change to what is served.
+  const unprojectedMoved = scope.moved.some((id) => !afterKits.has(id));
+
+  const previousMap = Array.isArray(context.page_map) ? context.page_map : [];
+  const nextMap = [];
+  for (const entry of previousMap) {
+    if (!isObject(entry) || removed.has(entry.page_id)) continue;
+    if (isObject(entry.page_kit) && projections.has(entry.page_id)) {
+      const kit = projections.get(entry.page_id);
+      nextMap.push({ ...entry, output_path: relFromDir(targetRepo, resolve(targetRepo, kit.output_path)), page_kit: kit });
+    } else nextMap.push(entry);
+  }
+  for (const id of scope.added) {
+    const kit = projections.get(id);
+    nextMap.push({ page_id: id, source_path: null, skip_reason: null, output_path: relFromDir(targetRepo, resolve(targetRepo, kit.output_path)), page_kit: kit, origin: "repo" });
+  }
+
+  let designSource = null;
+  const reference = packet.design_source_package;
+  if (isObject(reference)) {
+    const packagePath = resolveFromFile(packetPath, reference.path);
+    let bytes;
+    let value;
+    try {
+      bytes = readFileSync(packagePath);
+      value = JSON.parse(bytes.toString("utf8"));
+    } catch (error) {
+      return refuse("design_source_package_unreadable", `the Design Source Package at ${packagePath} could not be read (${error.message}); restore it, or re-run intake (${cmd("prepare-build")}).`);
+    }
+    const onDisk = hashSerializedDesignSourcePackage(bytes);
+    let rebound;
+    let serialized;
+    try {
+      rebound = rebindDesignSourcePackagePages(value, { activePages, projections });
+      serialized = serializeDesignSourcePackage(rebound);
+    } catch (error) {
+      return refuse("design_source_package_unbindable", `the Design Source Package at ${packagePath} is not a package record spec can re-bind (${error.message}); re-run intake (${cmd("prepare-build")}).`);
+    }
+    // Only a rebind that changes the package writes it, so only then do the
+    // checks on who may rewrite it apply.
+    if (serialized !== serializeDesignSourcePackage(value)) {
+      const origin = report.design_source_package?.origin ?? null;
+      if (origin !== "synthesized") {
+        return refuse("design_source_package_operator_supplied", `the Design Source Package at ${packagePath} ${origin === "adopted" ? "was adopted by prepare-build from a package it did not write" : origin ? `has origin ${JSON.stringify(origin)}` : "has no recorded origin (an Assembly Report older than the origin field)"}, so record spec does not rewrite its page routes, which the new pages would change; reconcile it with the new pages and re-run intake (${cmd("prepare-build")}).`);
+      }
+      const provenance = readPriorDesignSourceProvenance(reportPath, packagePath);
+      if (onDisk !== reference.sha256 && !(provenance?.synthesized || []).includes(onDisk)) {
+        return refuse("design_source_package_edited", `the Design Source Package at ${packagePath} no longer matches the sha256 the packet records (it was edited since prepare-build wrote it), so record spec does not rewrite it; restore it, or re-run intake (${cmd("prepare-build")} --force regenerates a package it synthesized).`);
+      }
+      const validation = validateDesignSourcePackage(rebound);
+      if (!validation.ok) {
+        return refuse("design_source_package_unbindable", `the Design Source Package with the new page routes does not validate (${validation.errors.slice(0, 3).map((error) => `[${error.code}] ${error.message}`).join("; ")}); re-run intake (${cmd("prepare-build")}).`);
+      }
+      const identity = createDesignSourcePackageArtifactReference(rebound, { serialized });
+      designSource = { path: packagePath, serialized, sha256: identity.sha256, material_fingerprint: identity.material_fingerprint };
+    }
+  }
+
+  // Routes alone: no page added or removed, and nothing but page_url differs
+  // from the material the Build Context recorded at the last bind.
+  const recordedMasked = optionalString(context.spec?.route_masked_material_hash);
+  const routesOnly = !scope.added.length && !scope.removed.length && Boolean(recordedMasked) && recordedMasked === routeMaskedSpecMaterialHash(spec);
+  return {
+    refusal: null,
+    scope,
+    nextPages,
+    nextMap,
+    designSource,
+    projectionChanged,
+    builtPagesChanged,
+    // Nothing the build wrote changes: the same targets, links and routing
+    // meta, the same Design Source Package, and only routes moved.
+    builtUnchanged: routesOnly && !projectionChanged && !unprojectedMoved && !designSource,
+  };
+}
+
+/**
+ * The Design Source Package reference a record spec run that stopped part
+ * way left behind (#531). The rewritten package is published first and the
+ * report last, so a run that dies between them leaves the packet, the Build
+ * Context or the Assembly Report naming the old sha256 while the package on
+ * disk is the new one. When prepare-build's provenance (the report's
+ * synthesized reference or the pending record beside the package) vouches
+ * for the bytes on disk, and any of the three references names other bytes,
+ * this returns the identity to move them to; otherwise null, and doctor
+ * reports a mismatch it cannot vouch for.
+ */
+function designSourceReferenceRepair({ packet, packetPath, context, report, reportPath }) {
+  const reference = packet.design_source_package;
+  if (!isObject(reference) || report.design_source_package?.origin !== "synthesized") return null;
+  const packagePath = resolveFromFile(packetPath, reference.path);
+  let bytes;
+  let value;
+  try {
+    bytes = readFileSync(packagePath);
+    value = JSON.parse(bytes.toString("utf8"));
+  } catch {
+    return null;
+  }
+  const onDisk = hashSerializedDesignSourcePackage(bytes);
+  const references = [reference, context.design_source_package, report.design_source_package].filter(isObject);
+  if (references.every((ref) => ref.sha256 === onDisk)) return null;
+  if (!(readPriorDesignSourceProvenance(reportPath, packagePath)?.synthesized || []).includes(onDisk)) return null;
+  const identity = createDesignSourcePackageArtifactReference(value, { serialized: bytes });
+  return { path: packagePath, sha256: identity.sha256, material_fingerprint: identity.material_fingerprint };
 }
 
 // The currency reasons that mean a stage's stamp differs from the current
@@ -580,7 +806,7 @@ function refreshSpecUnderLock({ packetPath, sidecars, lockedTarget, dryRun, time
   const normalizedPath = optionalString(packet.build_brief?.normalized_path) ? resolveFromFile(packetPath, packet.build_brief.normalized_path) : null;
   const previousNormalizedBrief = readJsonOrNull(normalizedPath);
   const briefFile = normalizedPath ? recordedBriefFile(context, { targetRepo, previousNormalizedBrief }) : null;
-  const refusal = specRefusal({ read, specPath, packet, report, context, briefFile, packageArtifacts: packageArtifactPaths(workspace, normalizedPath) });
+  const { refusal, rebind } = specRefusal({ read, specPath, packet, packetPath, report, reportPath, context, targetRepo, briefFile, packageArtifacts: packageArtifactPaths(workspace, normalizedPath) });
   if (refusal) throw refuseRecord("spec", [`${refusal[0]}: ${refusal[1]}`]);
 
   const { spec, rawHash } = read;
@@ -593,7 +819,14 @@ function refreshSpecUnderLock({ packetPath, sidecars, lockedTarget, dryRun, time
   const owedOnStamp = STAMPED_STAGES.filter((key) => STAMP_OWED_REASONS.includes(currency.reasons[key]));
   const notices = bindingUnknownNotices(currency);
   const specChanged = !specHashesMatch(boundMaterial, material);
-  const unchanged = !specChanged && !owedOnStamp.length;
+  // A package reference an earlier, interrupted run left behind is moved
+  // with whatever else this run binds (a rewrite this run makes moves them
+  // itself).
+  const repair = rebind?.designSource ? null : designSourceReferenceRepair({ packet, packetPath, context, report, reportPath });
+  // A recovery run never keeps the build: what the interrupted run changed
+  // cannot be told from what this one sees, so the stages are owed again.
+  const builtUnchanged = Boolean(rebind?.builtUnchanged) && !repair;
+  const unchanged = !specChanged && !owedOnStamp.length && !rebind && !repair;
 
   const writes = [];
   let demoted = [];
@@ -605,12 +838,15 @@ function refreshSpecUnderLock({ packetPath, sidecars, lockedTarget, dryRun, time
     // normalized brief and its bindings, and a material change also makes
     // the stages its partitions name owed.
     let brief = null;
+    // The context the brief is re-derived from carries the rebound pages, so
+    // a page added after handoff is evaluated as the repo page it is.
+    const pageContext = rebind ? { ...context, page_map: rebind.nextMap } : context;
     if (normalizedPath) {
       // Checked only when the brief is re-derived: an unchanged result reads
       // nothing the missing intake products would give.
       const missing = briefInputsMissing(context);
       if (missing.length) throw refuseRecord("spec", [`brief_inputs_unavailable: the Build Context lacks ${missing.join(", ")}, which re-deriving the brief needs; re-run intake to restore it.`]);
-      brief = rederiveBrief({ briefFile, spec, context, packet, report, normalizedPath });
+      brief = rederiveBrief({ briefFile, spec, context: pageContext, packet, report, normalizedPath });
       briefOutcome = briefSaveOutcome(report, brief.buildBrief, brief.bindings);
     }
     const briefSaved = briefOutcome && briefOutcome.outcome !== "unchanged";
@@ -620,8 +856,8 @@ function refreshSpecUnderLock({ packetPath, sidecars, lockedTarget, dryRun, time
     const briefWritten = Boolean(brief) && (briefSaved || !sameBriefMaterial(brief.bindings.material, currentBrief));
     const newBrief = brief ? brief.bindings.material : currentBrief;
     const saved = briefSaved
-      ? briefSaveArtifacts({ context, report, buildBrief: brief.buildBrief, bindings: brief.bindings, targetRepo })
-      : { nextContext: context, nextReport: report };
+      ? briefSaveArtifacts({ context: pageContext, report, buildBrief: brief.buildBrief, bindings: brief.bindings, targetRepo })
+      : { nextContext: pageContext, nextReport: report };
     const labels = new Map(activeSpecPages(spec).map((page) => [page.id, page.label || null]));
     const nextContext = {
       ...saved.nextContext,
@@ -629,10 +865,25 @@ function refreshSpecUnderLock({ packetPath, sidecars, lockedTarget, dryRun, time
         ...saved.nextContext.spec,
         hash: rawHash,
         material_hash: material,
-        active_pages: saved.nextContext.spec.active_pages.map((page) => ({ ...page, label: labels.has(page.id) ? labels.get(page.id) : page.label ?? null })),
+        route_masked_material_hash: routeMaskedSpecMaterialHash(spec),
+        active_pages: rebind
+          ? rebind.scope.current
+          : saved.nextContext.spec.active_pages.map((page) => ({ ...page, label: labels.has(page.id) ? labels.get(page.id) : page.label ?? null })),
       },
     };
     let nextReport = { ...saved.nextReport, identity: { ...saved.nextReport.identity, spec_hash: rawHash, spec_material_hash: material } };
+    // The rebound pages' Design Source Package: the same path, new bytes, and
+    // each of the three references to it moved together (#531).
+    let nextPacket = null;
+    if (rebind) nextPacket = { ...packet, source_html: { ...packet.source_html, pages: rebind.nextPages } };
+    const movedTo = rebind?.designSource || repair;
+    if (movedTo) {
+      const moved = { sha256: movedTo.sha256, material_fingerprint: movedTo.material_fingerprint };
+      const at = (ref) => ref.sha256 !== moved.sha256 || ref.material_fingerprint !== moved.material_fingerprint;
+      if (at(packet.design_source_package)) nextPacket = { ...(nextPacket || packet), design_source_package: { ...packet.design_source_package, ...moved } };
+      if (isObject(nextContext.design_source_package) && at(nextContext.design_source_package)) nextContext.design_source_package = { ...nextContext.design_source_package, ...moved };
+      if (isObject(nextReport.design_source_package) && at(nextReport.design_source_package)) nextReport.design_source_package = { ...nextReport.design_source_package, ...moved };
+    }
     // A stage is owed on the spec unless its spec stamp already equals the
     // new material (a build recorded after the edit has recorded the change
     // itself); a completed stage with no spec stamp is owed on it too. It is
@@ -640,6 +891,22 @@ function refreshSpecUnderLock({ packetPath, sidecars, lockedTarget, dryRun, time
     // that partition, or when its stamp of that partition differs from the
     // re-derived brief. The spec reason wins where both apply.
     const briefCauses = briefOutcome?.outcome === "saved_with_invalidation" ? briefOutcome.causes : [];
+    // Routes that moved without moving anything the build wrote (the same
+    // targets, links and routing meta, #531): a stage made against the bound
+    // spec is restamped with the new material instead of made owed again.
+    const keptStages = [];
+    if (builtUnchanged && specChanged) {
+      for (const key of STAMPED_STAGES) {
+        const record = nextReport.stages[key];
+        if (!COMPLETED_STATUSES.includes(record?.status) || !specHashesMatch(record.source_spec_material_hash, boundMaterial)) continue;
+        const restamped = { ...record, source_spec_material_hash: material };
+        if (isObject(record.unchanged_output_reason?.for_inputs) && specHashesMatch(record.unchanged_output_reason.for_inputs.spec_material_hash, boundMaterial)) {
+          restamped.unchanged_output_reason = { ...record.unchanged_output_reason, for_inputs: { ...record.unchanged_output_reason.for_inputs, spec_material_hash: material } };
+        }
+        nextReport = { ...nextReport, stages: { ...nextReport.stages, [key]: restamped } };
+        keptStages.push(key);
+      }
+    }
     const causesFor = (key) => {
       const record = nextReport.stages[key];
       const stamp = record?.source_brief_material;
@@ -662,24 +929,52 @@ function refreshSpecUnderLock({ packetPath, sidecars, lockedTarget, dryRun, time
       demoted = [...demoted, ...applied.demoted];
       allCauses.push(...causes);
     }
+    // Deploy evidence is the list of URLs that answered; when the set of
+    // built pages changes, the probe is owed again (#531). A deploy bound to
+    // the build fingerprint it probed (#619) is demoted by record build when
+    // the rebuilt site differs, so only a deploy recorded before that stamp
+    // existed is demoted here.
+    if (rebind?.builtPagesChanged) {
+      const previousDeploy = nextReport.stages.deploy;
+      if (isObject(previousDeploy) && COMPLETED_STATUSES.includes(previousDeploy.status) && !optionalString(previousDeploy.source_build_fingerprint)) {
+        const demotedDeploy = { ...previousDeploy, stage: "deploy", status: "required", required_by: "spec", required_for: ["qa"] };
+        for (const field of ["source_build_fingerprint", "evidence", "outputs", "completed_at", "recorded_by", "performed_by"]) delete demotedDeploy[field];
+        nextReport = { ...nextReport, stages: { ...nextReport.stages, deploy: archiveSupersededRecord(demotedDeploy, previousDeploy, { by: "record spec", reason: "spec_material_changed", at: timestamp }) } };
+        demoted = [...demoted, "deploy"];
+      }
+    }
     reason = changeReason(allCauses);
     const briefNote = briefSaved
       ? `; brief re-derived (${briefOutcome.outcome})`
       : briefWritten ? "; normalized brief re-derived from its source" : "";
+    const pageNote = rebind
+      ? `; pages ${[rebind.scope.added.length ? `added ${rebind.scope.added.join(", ")}` : null, rebind.scope.removed.length ? `removed ${rebind.scope.removed.join(", ")}` : null, rebind.scope.moved.length ? `moved ${rebind.scope.moved.join(", ")}` : null].filter(Boolean).join("; ")}, page-kit projection ${rebind.projectionChanged ? "rewritten" : "unchanged"}${rebind.designSource ? ", Design Source Package page surfaces rewritten" : ""}${keptStages.length ? `, ${keptStages.join(", ")} kept (nothing built changed)` : ""}`
+      : "";
+    const repairNote = repair ? `; Design Source Package references moved to ${repair.sha256}, the package an interrupted record spec published` : "";
     nextReport.evidence = [
       ...(Array.isArray(report.evidence) ? report.evidence : []),
-      `${timestamp} record spec: CampaignSpec material ${specChanged ? `${boundMaterial || "(none bound)"} -> ${material}` : `${material} already bound`}${briefNote}; ${demoted.length ? `${demoted.join(", ")} owed again` : "no recorded stage was demoted"}${reason ? ` (${reason})` : ""}.`,
+      `${timestamp} record spec: CampaignSpec material ${specChanged ? `${boundMaterial || "(none bound)"} -> ${material}` : `${material} already bound`}${briefNote}${pageNote}${repairNote}; ${demoted.length ? `${demoted.join(", ")} owed again` : "no recorded stage was demoted"}${reason ? ` (${reason})` : ""}.`,
     ];
-    writes.push(...(briefWritten ? [normalizedPath] : []), contextPath, reportPath);
+    writes.push(...(rebind?.designSource ? [rebind.designSource.path] : []), ...(nextPacket ? [packetPath] : []), ...(briefWritten ? [normalizedPath] : []), contextPath, reportPath);
     if (!dryRun) {
       // Intake's publication order, the report last: a failure between files
       // leaves the report bound to the old spec material, which reads as owed.
+      // The rewritten Design Source Package goes first, vouched for by the
+      // pending provenance record until the report records its new sha256,
+      // so a run that stops between the two leaves a package the next
+      // record spec or prepare-build still knows as its own.
+      if (rebind?.designSource) {
+        recordPendingDesignSourceProvenance(rebind.designSource.path, [rebind.designSource.sha256, packet.design_source_package.sha256]);
+        writeTextAtomic(rebind.designSource.path, rebind.designSource.serialized);
+      }
+      if (nextPacket) writeJsonAtomic(packetPath, portableArtifactPaths(nextPacket, targetRepo, { artifactPath: packetPath }));
       if (briefWritten) writeJsonAtomic(normalizedPath, portableArtifactPaths(brief.buildBrief.artifact, targetRepo, { artifactPath: normalizedPath }));
       writeJsonAtomic(contextPath, portableArtifactPaths(nextContext, targetRepo, { artifactPath: contextPath }));
       commitAssemblyReport(workspace, () => nextReport, {
         command: "record spec",
         staleReason: "The CampaignSpec was bound with record spec after this doctor snapshot. Re-run doctor (or next) for current state.",
       });
+      if (movedTo) recordPendingDesignSourceProvenance(movedTo.path, []);
     }
   }
 
@@ -697,6 +992,18 @@ function refreshSpecUnderLock({ packetPath, sidecars, lockedTarget, dryRun, time
     ...(dryRun ? { would_write: writes } : { written: writes }),
     demoted,
     ...(briefOutcome ? { brief: { outcome: briefOutcome.outcome, brief_path: briefFile?.path || null } } : {}),
+    ...(rebind ? {
+      pages: {
+        added: rebind.scope.added,
+        removed: rebind.scope.removed,
+        moved: rebind.scope.moved,
+        projection_changed: rebind.projectionChanged,
+        design_source_package_rewritten: Boolean(rebind.designSource),
+        built_pages_changed: rebind.builtPagesChanged,
+        built_unchanged: builtUnchanged,
+      },
+    } : {}),
+    ...(repair ? { design_source_references_repaired: { sha256: repair.sha256 } } : {}),
     ...(reason ? { input_change: { reason, at: timestamp } } : {}),
     notices,
     note: outcome === "unchanged"

package/src/invocation.mjs

@@ -111,6 +111,12 @@ export const commandNames = () => Object.keys(COMMANDS);
 
 export const subcommandNames = (command) => (Object.hasOwn(COMMANDS, command) && COMMANDS[command].subcommands) || frozen([]);
 
+// The flag names parseArgs met spelled `--flag=value` (in argv order), kept off
+// the enumerable keys. The invocation is refused at dispatch, and it does
+// nothing first: its values were dropped, so the root the stale sweep would
+// act on, and the --no-remit / --proxy-base it would inherit, are unknown.
+export const JOINED_FLAGS = Symbol("campaigns-os.joined-flags");
+
 // A run opted out of sessions altogether: no stale sweep, and no intake
 // auto-start (which reads this predicate from here).
 export const optsOutOfRunSession = (args) => args["no-run-session"] === true;
@@ -133,7 +139,7 @@ export function resolveInvocationPolicy(command, args) {
   const noWrite = args["no-write"] === true;
   const implementsDryRun = rule.dryRun === true;
   const help = Boolean(args.help);
-  const sweepSuppressed = help || optsOutOfRunSession(args) || noWrite || (Object.hasOwn(args, "dry-run") && implementsDryRun);
+  const sweepSuppressed = help || optsOutOfRunSession(args) || noWrite || (Object.hasOwn(args, "dry-run") && implementsDryRun) || Boolean(args[JOINED_FLAGS]?.length);
   const inspection = Boolean(rule.journalExemptWhen && args[rule.journalExemptWhen.given] && args[rule.journalExemptWhen.unlessBare] !== true);
   return Object.freeze({
     class: rule.class,

package/src/live-campaign-refs.mjs

@@ -209,6 +209,7 @@ export async function readLiveCampaign({
   timeoutMs = LIVE_CAMPAIGN_TIMEOUT_MS,
   maxBytes = LIVE_CAMPAIGN_MAX_BYTES,
   warn = undefined,
+  includeCampaign = false,
 } = {}) {
   if (typeof apiKey !== "string" || !apiKey.trim()) {
     return notRun("no_key", "No public Campaigns API key resolved, so the live campaign was not read.");
@@ -307,7 +308,10 @@ export async function readLiveCampaign({
   if (picked.notRun) return { ...picked.notRun, ...requested };
   const refs = liveCampaignRefs(picked.campaign);
   if (!refs) return notRun("unexpected_body", "The live campaign did not carry package and shipping-method lists with a ref on every entry.", requested);
-  return { status: "read", ...requested, ...refs };
+  // `spec derive` refreshes the spec's mirrored offer and package fields from
+  // the same read (#721), so it asks for the campaign body as well; doctor and
+  // QA compare refs only and never carry the body in their results.
+  return { status: "read", ...requested, ...refs, ...(includeCampaign ? { campaign: picked.campaign } : {}) };
 }
 
 // The `--no-live-refs` opt-out on `doctor` and `qa run`: no request, and the
@@ -357,7 +361,7 @@ function readPacketLocalSpec(packet, packetPath) {
 // and env-name gates apply, plus the stricter env-name gate above), then one
 // read, for the campaign the CampaignSpec's `campaign.ref_id` names when it
 // names one.
-export async function readLiveCampaignForPacket({ packet, packetPath = null, spec = undefined, env = process.env, fetchImpl = null, proxyBase = null, timeoutMs, warn } = {}) {
+export async function readLiveCampaignForPacket({ packet, packetPath = null, spec = undefined, env = process.env, fetchImpl = null, proxyBase = null, timeoutMs, warn, includeCampaign = false } = {}) {
   const localSpec = spec !== undefined ? spec : readPacketLocalSpec(packet, packetPath);
   const resolved = resolveCampaignsApiKeySource(packet, packetPath, env, localSpec === undefined ? {} : { spec: localSpec });
   const refusedEnv = refusedEnvKeySource(packet, resolved);
@@ -377,6 +381,7 @@ export async function readLiveCampaignForPacket({ packet, packetPath = null, spe
     fetchImpl,
     proxyBase,
     campaignRefId: campaignRefIdFromSpec(localSpec),
+    includeCampaign,
     ...(timeoutMs ? { timeoutMs } : {}),
     ...(warn ? { warn } : {}),
   });