@nextcommerce/campaigns-os 1.52.0 → 1.54.0

package/src/design-source-publication.mjs

@@ -7,7 +7,11 @@ import { writeThemeArtifacts } from "./brand-theme.mjs";
 import { cloneJson, filesystemPathsMatch, isObject, isNonEmptyString, optionalString, readJson, resolveFromFile, sha256File } from "./cli-helpers.mjs";
 import { DESIGN_SOURCE_PACKAGE_REL_PATH, createDesignSourcePackageArtifactReference, hashSerializedDesignSourcePackage, serializeDesignSourcePackage, synthesizeHtmlFunnelDesignSourcePackage, validateDesignSourcePackage } from "./design-source-package.mjs";
 import { stampDoctorProducer } from "./doctor-sidecar.mjs";
+import { stageWriteInputs } from "./input-currency.mjs";
+import { cmd } from "./install-invocation.mjs";
 import { ASSEMBLY_REPORT_STAGE_KEYS } from "./orchestration-stage-contract.mjs";
+import { HOST_STRIPPED_CODE } from "./source-html-intake.mjs";
+import { archiveForForceReset, stageHistoryPresent } from "./stage-ledger.mjs";
 import { targetLockPath, withTargetLock } from "./target-lock.mjs";
 import { resolveTemplateFamilyDesignSource } from "./template-reference.mjs";
 
@@ -71,12 +75,93 @@ function guardAssemblyReportOverwrite(reportPath, args, { announced = null } = {
   const unannounced = announced ? stageKeys.filter((key) => !announced.includes(key)) : stageKeys;
   if (unannounced.length > 0) {
     console.warn(
-      `[campaigns-os prepare-build] --force: overwriting assembly report at ${reportPath}; clearing stage evidence for: ${unannounced.join(", ")}.`,
+      `[campaigns-os prepare-build] --force: overwriting assembly report at ${reportPath}; clearing stage evidence for: ${unannounced.join(", ")}. Completed build, Polish and QA records are archived into their stage history, which is kept.`,
     );
   }
   return stageKeys;
 }
 
+// Operator state on the report an intake would replace, one line per item:
+// recorded waivers and warning accepts, stage history, an applied theme, and
+// report evidence other than intake's own host-strip lines.
+function assemblyReportOperatorState(existingReport) {
+  if (!isObject(existingReport)) return [];
+  const items = [];
+  const count = (value) => (Array.isArray(value) ? value.length : 0);
+  if (count(existingReport.waivers)) items.push(`waivers (${count(existingReport.waivers)} recorded waiver${count(existingReport.waivers) === 1 ? "" : "s"})`);
+  if (count(existingReport.qc_accepts)) items.push(`qc_accepts (${count(existingReport.qc_accepts)} recorded warning accept${count(existingReport.qc_accepts) === 1 ? "" : "s"})`);
+  if (stageHistoryPresent(existingReport)) items.push("stage history (superseded build, Polish or QA records)");
+  if (existingReport.theme?.status === "applied") items.push("theme (status applied)");
+  const evidence = Array.isArray(existingReport.evidence) ? existingReport.evidence.filter((entry) => !(isObject(entry) && entry.code === HOST_STRIPPED_CODE)) : [];
+  if (evidence.length) items.push(`evidence (${evidence.length} recorded line${evidence.length === 1 ? "" : "s"})`);
+  return items;
+}
+
+// Packet settings recorded since the last intake that this run would
+// overwrite (every setting `qa policy set` records): each named with the
+// value on disk and the value this run writes.
+const INTAKE_PACKET_SETTINGS = Object.freeze([
+  ["deploy.target", (packet) => packet?.deploy?.target],
+  ["deploy.preview_url", (packet) => packet?.deploy?.preview_url],
+  ["deploy.production_url", (packet) => packet?.deploy?.production_url],
+  ["qa.proof_policy.order_path_depth", (packet) => packet?.qa?.proof_policy?.order_path_depth],
+  ["campaign.allowed_domains_confirmed", (packet) => packet?.campaign?.allowed_domains_confirmed],
+]);
+
+function packetSettingChanges(packetPath, planned) {
+  if (!isObject(planned) || !existsSync(packetPath)) return [];
+  let existing;
+  try {
+    existing = readJson(packetPath);
+  } catch {
+    return [];
+  }
+  const items = [];
+  for (const [field, read] of INTAKE_PACKET_SETTINGS) {
+    const onDisk = read(existing) ?? null;
+    const written = read(planned) ?? null;
+    if (onDisk !== written) items.push(`${field} (recorded ${JSON.stringify(onDisk)}; this run would write ${JSON.stringify(written)})`);
+  }
+  return items;
+}
+
+// Intake replaces the report and packet whole, so recorded operator state
+// would be lost silently. Without --force it refuses and names each item;
+// with --force it names each item as cleared (once).
+function guardIntakeOperatorState(reportPath, packetPath, { force, planned = null, announced = [] }) {
+  let existingReport = null;
+  try {
+    existingReport = existsSync(reportPath) ? readJson(reportPath) : null;
+  } catch {
+    existingReport = null;
+  }
+  const items = [...assemblyReportOperatorState(existingReport), ...packetSettingChanges(packetPath, planned)];
+  if (!items.length) return announced;
+  if (force !== true) {
+    throw new Error(
+      `Rerunning prepare-build/start/build would discard recorded operator state: ${items.join("; ")}. `
+      + `To save brief answers or a CampaignSpec change without discarding anything, run ${cmd("record")} brief or ${cmd("record")} spec instead. `
+      + "To rerun intake anyway, pass the original deploy and order-path flags, or --force to clear the listed state (destructive; completed build, Polish and QA records are archived into stage history). "
+      + `After --force, record a cleared packet setting again with ${cmd("qa")} policy set.`,
+    );
+  }
+  const unannounced = items.filter((item) => !announced.includes(item));
+  if (unannounced.length) {
+    console.warn(`[campaigns-os prepare-build] --force: clearing recorded operator state: ${unannounced.join("; ")}.`);
+  }
+  return [...announced, ...unannounced];
+}
+
+// The report this run replaces, read for the --force archive; null when there
+// is none or it cannot be read.
+function readReplacedReport(reportPath) {
+  try {
+    return existsSync(reportPath) ? readJson(reportPath) : null;
+  } catch {
+    return null;
+  }
+}
+
 function artifactRelativePath(artifactPath, targetPath) {
   const rel = relative(dirname(resolve(artifactPath)), resolve(targetPath)).replaceAll("\\", "/");
   return rel || ".";
@@ -806,12 +891,20 @@ export async function withDesignSourcePublication({ targetRepo, outputs, force =
     // fetched, and a run waiting here cannot replace it meanwhile.
     publishSpec?.();
     let announcedStageEvidence = guardAssemblyReportOverwrite(reportPath, { force });
+    // Operator state is checked once the run knows the packet settings it
+    // would write, before the package.
+    let plannedPacketSettings = null;
+    let announcedOperatorState = null;
+    const checkOperatorState = () => {
+      announcedOperatorState = guardIntakeOperatorState(reportPath, packetPath, { force, planned: plannedPacketSettings, announced: announcedOperatorState || [] });
+    };
     // Stage producers commit the report without this lock, so evidence can land
     // while the run works. Re-check before each write that is not rolled back:
     // the theme artifacts, then the JSON outputs. --force names a stage once.
     const recheckStageEvidence = () => {
       const found = guardAssemblyReportOverwrite(reportPath, { force }, { announced: announcedStageEvidence });
       announcedStageEvidence = [...new Set([...announcedStageEvidence, ...found])];
+      checkOperatorState();
     };
     let completed = 0;
     const enter = (index, { once = false } = {}) => {
@@ -821,8 +914,13 @@ export async function withDesignSourcePublication({ targetRepo, outputs, force =
     let designSourcePackage = null;
     return fn(Object.freeze({
       paths,
-      package(inputs) {
+      // `plannedPacket`: the part of the packet this run would write that
+      // carries the settings INTAKE_PACKET_SETTINGS names, checked against
+      // the packet on disk.
+      package({ plannedPacket = null, ...inputs }) {
         enter(0, { once: true });
+        plannedPacketSettings = plannedPacket;
+        checkOperatorState();
         // Reject deterministic destination failures before publishing the fixed
         // DSP. The DSP intentionally precedes the theme and JSON artifacts that
         // reference it; a later I/O race may therefore leave a valid DSP for a
@@ -858,8 +956,17 @@ export async function withDesignSourcePublication({ targetRepo, outputs, force =
         completed = Math.max(completed, 2);
         return written;
       },
-      publish({ packet, brief, context, report }) {
+      publish({ packet, brief, context, report: reseeded }) {
         enter(2, { once: true });
+        // The records this run replaces stay visible: completed build, Polish
+        // and QA records go to their stage history (only --force reaches here
+        // with any), and each stage's history and input change carry over.
+        const now = new Date().toISOString();
+        const bound = { briefMaterial: reseeded?.build_brief?.material ?? null, specMaterial: reseeded?.identity?.spec_material_hash ?? null };
+        const report = archiveForForceReset(readReplacedReport(reportPath), reseeded, {
+          now,
+          detectChange: (key, record) => stageWriteInputs(key, bound).detectChange(record),
+        });
         // Before the report goes out, narrow the pending record to exactly what the
         // report will say: the package's own hash when it is synthesized, nothing
         // when it is adopted. A candidate this run or an earlier failed one never

package/src/directory-lock.mjs

@@ -18,7 +18,13 @@
 // to an older writer that may still be alive between its mkdir and its owner
 // write (#501). A waiter refuses it after a short grace, leaving it for the
 // documented offline procedure. (See publishStagedDirectory for the one
-// mixed-version race this cannot close, tracked in #514.)
+// mixed-version race this cannot close, tracked in #514.) Anything else at the
+// lock path, a file or a directory holding other entries, is not a lock at
+// all: it is refused by name and never removed (#514).
+//
+// Staging and released siblings a dead process left beside the lock are swept
+// by the next holder, under the lock; a sibling whose owner is alive or
+// unreadable is left alone (#514).
 //
 // The lock is reentrant for its holder: code running inside `fn` (in the
 // same async context) that asks for the same lock enters directly instead of
@@ -26,7 +32,7 @@
 // stage writers that take it too.
 import { AsyncLocalStorage } from "node:async_hooks";
 import { randomBytes } from "node:crypto";
-import { lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 
 const heldLocks = new AsyncLocalStorage();
@@ -39,6 +45,47 @@ const exists = (path) => {
   try { lstatSync(path); return true; } catch { return false; }
 };
 
+// True only when the owner record names a process that no longer exists. An
+// unreadable record, or a pid this process may not signal, is not dead.
+const ownerIsDead = (owner) => {
+  if (!(Number.isInteger(owner?.pid) && owner.pid > 0 && typeof owner.token === "string")) return false;
+  try { process.kill(owner.pid, 0); return false; } catch (error) { return error.code === "ESRCH"; }
+};
+
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+// The siblings this module creates beside a lock and normally removes itself:
+// a crash leaves staging and recovery-staging ones, a release whose tomb could
+// not be put back leaves a released one. Each carries an owner.json.
+function siblingPattern(path) {
+  return new RegExp(`^${escapeRegExp(basename(path))}\\.(?:staging|recovery-staging|released)-[0-9a-f]{32}$`);
+}
+
+// Called only by the holder of the lock, so no two sweeps race, and a
+// sibling is removed only when its owner is a dead process: a live owner may
+// still be staging or releasing, and an unreadable one may be between its
+// mkdir and its owner write. Best effort; a failure leaves the sibling.
+function sweepDeadSiblings(path) {
+  const parent = dirname(path);
+  const pattern = siblingPattern(path);
+  let entries;
+  try { entries = readdirSync(parent); } catch { return; }
+  for (const entry of entries) {
+    if (!pattern.test(entry)) continue;
+    const sibling = join(parent, entry);
+    try {
+      const stat = lstatSync(sibling);
+      if (!stat.isDirectory() || stat.isSymbolicLink()) continue;
+      if (!ownerIsDead(readOwner(join(sibling, "owner.json")))) continue;
+      rmSync(sibling, { recursive: true, force: true });
+    } catch {}
+  }
+}
+
+// What a lock directory may hold besides its owner record: the recovery
+// claim. A directory without owner.json that holds anything else is not a lock.
+const LOCK_ENTRIES = new Set(["owner.json", ".recovery"]);
+
 // The reentrancy key names the lock directory through its real parent, so a
 // holder that reached the target through a symlink still recognizes itself.
 function lockKey(path) {
@@ -106,9 +153,7 @@ function createLock(path, { budgetMs, unavailable, now = Date.now, ownerlessGrac
     try {
       const stat = lstatSync(path);
       if (!stat.isDirectory() || stat.isSymbolicLink()) return false;
-      const current = readOwner(ownerPath);
-      if (!(Number.isInteger(current?.pid) && current.pid > 0 && typeof current.token === "string")) return false;
-      try { process.kill(current.pid, 0); return false; } catch (error) { return error.code === "ESRCH"; }
+      return ownerIsDead(readOwner(ownerPath));
     } catch {
       return false;
     }
@@ -179,7 +224,32 @@ function createLock(path, { budgetMs, unavailable, now = Date.now, ownerlessGrac
     return current - start >= budgetMs;
   };
   const fail = (error) => unavailable(error);
-  const contended = () => Object.assign(new Error(`Lock is held: ${path}`), { code: "EEXIST" });
+  // Names what occupies the lock path when it is not a lock, else null. A
+  // file there, or a directory with no owner record that holds entries a lock
+  // never has, will not clear by waiting and is never removed here.
+  const obstruction = () => {
+    let stat;
+    try { stat = lstatSync(path); } catch { return null; }
+    if (stat.isSymbolicLink()) return "a symbolic link, not a lock";
+    if (!stat.isDirectory()) return stat.isFile() ? "a regular file, not a lock" : "a special file, not a lock";
+    if (exists(ownerPath)) return null;
+    let foreign;
+    try { foreign = readdirSync(path).filter((entry) => !LOCK_ENTRIES.has(entry)).sort(); } catch { return null; }
+    if (foreign.length === 0) return null;
+    const shown = foreign.slice(0, 3).join(", ") + (foreign.length > 3 ? `, and ${foreign.length - 3} more` : "");
+    return `a directory that is not a lock (no owner.json; it holds ${shown})`;
+  };
+  // The refusal once waiting ends, telling a held lock, an ownerless lock and
+  // a non-lock obstruction apart.
+  const contended = () => {
+    const found = obstruction();
+    if (found) {
+      return Object.assign(new Error(`Lock path is occupied by ${found}: ${path}`), { code: "ENOTLOCK", obstruction: found });
+    }
+    if (ownerless()) return Object.assign(new Error(`Lock has no owner record: ${path}`), { code: "EEXIST" });
+    return Object.assign(new Error(`Lock is held: ${path}`), { code: "EEXIST" });
+  };
+  const sweep = () => sweepDeadSiblings(path);
 
   const release = () => {
     if (readOwner(ownerPath)?.token !== token) return;
@@ -193,7 +263,7 @@ function createLock(path, { budgetMs, unavailable, now = Date.now, ownerlessGrac
     }
   };
 
-  return { token, stage, publish, recover, heldBySelfProcess, expired, fail, contended, release };
+  return { token, stage, publish, recover, heldBySelfProcess, expired, fail, contended, sweep, release };
 }
 
 function reentrantKey(path) {
@@ -232,6 +302,7 @@ export async function withDirectoryLock(path, fn, options) {
     await sleep(20);
   }
   try {
+    lock.sweep();
     return await runHolding(key, lock.token, fn);
   } finally {
     lock.release();
@@ -263,6 +334,7 @@ export function withDirectoryLockSync(path, fn, options) {
     (options.sleep ?? sleepSync)(20);
   }
   try {
+    lock.sweep();
     return runHolding(key, lock.token, fn);
   } finally {
     lock.release();

package/src/doctor/checks.mjs

@@ -1,6 +1,7 @@
 // Doctor checks: the check registries, validatePacket and the validators they run.
 import { campaignSpecIdentity, resolveCampaignIdentity, campaignIdentitiesMatch } from "../spec-source-identity.mjs";
 import { withHtmlScanSnapshot, readHtmlScanText } from "../html-scan.mjs";
+import { createHash } from "node:crypto";
 import { accessSync, constants as fsConstants, existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
 import { describeSdkIgnoredMetaTags, isSdkIgnoredMetaTag } from "../sdk-meta-tags.mjs";
@@ -90,6 +91,7 @@ import { SMOKE_QC, SMOKE_QC_LIMITS, builtFileOf, evaluateSmokeQc, insideRoot, is
 import { recordQcResults } from "../qc-results.mjs";
 import { FIGMA_EXPORT_FILE_CODES, SOURCE_PROVENANCE_SCOPE, evaluateSourceProvenanceGates, generatorClaimsFigmaExport, isSourceProvenanceCode } from "./source-provenance.mjs";
 import { validateCampaignBuildBriefArtifact } from "../build-brief.mjs";
+import { briefFileUnusable, deriveInputCurrency, wellFormedBriefMaterial } from "../input-currency.mjs";
 import { ASSEMBLY_REPORT_STAGE_KEYS, stageIsTerminal } from "../orchestration-stage-contract.mjs";
 import {
   assemblySourcePackageFingerprintMissing,
@@ -106,7 +108,7 @@ import { evaluatePageKitSdkVersion, PAGE_KIT_SDK_VERSION_SCOPE } from "../page-k
 // `npm run build:spec` (tsc -> campaign-spec/dist) so the package runs on the
 // node engine in package.json without type-stripping. build runs on `prepare`,
 // so a fresh install (including the git-ref consumer) always has dist.
-import { normalize as normalizeCampaignSpec, runRules, specOnlyRules } from "../../campaign-spec/dist/index.js";
+import { isReleasedSdkVersion, normalize as normalizeCampaignSpec, runRules, specOnlyRules } from "../../campaign-spec/dist/index.js";
 import { cmd, asInvocation } from "../install-invocation.mjs";
 import { specHashesMatch, specMaterialHash } from "../spec-identity.mjs";
 import {
@@ -511,7 +513,10 @@ const PACKET_DOCTOR_CHECKS = createDoctorCheckRegistry([
   {
     id: "build_brief.artifact",
     phase: "brief",
-    run: ({ packet, packetPath, spec, context, errors, warnings, ready }) => validateBuildBrief(packet, packetPath, spec, context, errors, warnings, ready),
+    run: ({ packet, packetPath, spec, context, report, errors, warnings, ready, derived }) => {
+      validateBuildBrief(packet, packetPath, spec, context, errors, warnings, ready);
+      validateInputCurrency({ packet, packetPath, spec, report, warnings, derived });
+    },
   },
 ], { registryId: "packet.always" });
 
@@ -731,22 +736,20 @@ function validatePacket(packet, packetPath, errors, warnings, ready, derived, bu
     }
     buildState.specStatus = specStatus;
     if (specStatus === "ok") {
-      const specMapId = spec.spec_identity?.map_id || spec.map_id;
-      if ((specMapId && specMapId !== packet.spec.map_id)
-        || ((spec.spec_identity?.local_spec_id != null || packet.spec?.local_spec_id != null)
-          && !campaignIdentitiesMatch(campaignSpecIdentity(spec), packet.spec))) {
-        const localIdentity = spec.spec_identity?.local_spec_id != null || packet.spec?.local_spec_id != null;
-        addIssue(errors, localIdentity ? "spec.local_identity" : "spec.map_id", "Packet identity does not match the CampaignSpec map_id/local_spec_id.", { kind: localIdentity ? "local_spec" : "saved_map" });
+      const identityKind = specIdentityMismatch(spec, packet.spec);
+      if (identityKind) {
+        addIssue(errors, identityKind === "local_spec" ? "spec.local_identity" : "spec.map_id", "Packet identity does not match the CampaignSpec map_id/local_spec_id.", { kind: identityKind });
       }
       ready.push("Local CampaignSpec parsed");
-      // QA refuses a local-spec run whose spec no longer has the material hash
-      // prepare-build bound on the Assembly Report; doctor (and next, which
-      // prints doctor's warnings) name it at the first read instead.
+      // The spec no longer has the material hash the Assembly Report binds:
+      // a local spec, or the copy a saved-Map or gateway packet fetched.
+      // Doctor (and next, which prints doctor's warnings) name it at the
+      // first read.
       const boundMaterialHash = buildState.report?.identity?.spec_material_hash;
-      if (packet.spec?.local_spec_id != null && isNonEmptyString(boundMaterialHash)) {
+      if (isNonEmptyString(boundMaterialHash)) {
         const currentMaterialHash = specMaterialHash(spec);
         if (!specHashesMatch(boundMaterialHash, currentMaterialHash)) {
-          addIssue(warnings, "spec.material_stale", `The CampaignSpec at ${localSpecPath} changed materially since prepare-build bound it (Assembly Report identity.spec_material_hash ${boundMaterialHash}; the spec now hashes to ${currentMaterialHash}). The build and its recorded evidence predate the edit, and QA refuses a stale spec. Re-run ${cmd("prepare-build")} from the edited spec before building on it further.`, { spec_path: localSpecPath, bound_material_hash: boundMaterialHash, current_material_hash: currentMaterialHash });
+          addIssue(warnings, "spec.material_stale", SPEC_MATERIAL_STALE_MESSAGE, { spec_path: localSpecPath, bound_material_hash: boundMaterialHash, current_material_hash: currentMaterialHash });
         }
       }
       runDoctorChecks(SPEC_DOCTOR_CHECKS, { packet, packetPath, spec, targetRepo, errors, warnings, ready, derived, buildState });
@@ -762,6 +765,9 @@ function validatePacket(packet, packetPath, errors, warnings, ready, derived, bu
   if (synthesizedBuiltSite) {
     ready.push("Packet source/proof checks skipped for synthesized built-site packet");
   } else {
+    // Computed once, before the checks that read it (the QA gate pass the
+    // built-output residue scan defers to) and the input warnings below.
+    derived.input_currency = deriveInputCurrency({ packet, packetPath, report: buildState.report, spec: isObject(spec) ? spec : null });
     runDoctorChecks(PACKET_DOCTOR_CHECKS, { packet, packetPath, spec, context: buildState.context, report: buildState.report, errors, warnings, ready, derived, buildState });
   }
 
@@ -781,6 +787,25 @@ function validatePacket(packet, packetPath, errors, warnings, ready, derived, bu
   // stage progression.
 }
 
+// A stage's spec stamp, as record build, record polish and the QA write store it.
+const SPEC_STAMP = /^sha256:[0-9a-f]{64}$/;
+const SPEC_MATERIAL_STALE_MESSAGE = "CampaignSpec material changed since it was bound; run `record spec` (keeps history). `prepare-build --force` resets every stage and archives their records.";
+
+/**
+ * Whether a parsed CampaignSpec names another campaign than `bound` (the
+ * packet's spec block, or an Assembly Report identity): null when they
+ * agree, otherwise the kind of identity that differs ("local_spec" when
+ * either side carries a local spec id, else "saved_map").
+ */
+export function specIdentityMismatch(spec, bound) {
+  const specMapId = spec?.spec_identity?.map_id || spec?.map_id;
+  const localIdentity = spec?.spec_identity?.local_spec_id != null || bound?.local_spec_id != null;
+  if ((specMapId && specMapId !== bound?.map_id) || (localIdentity && !campaignIdentitiesMatch(campaignSpecIdentity(spec), bound))) {
+    return localIdentity ? "local_spec" : "saved_map";
+  }
+  return null;
+}
+
 function validateCampaignSpecRuleRegistry(spec, errors, warnings) {
   // ADR-003: run the shared campaign-spec rule registry — the single public
   // source of CampaignSpec validation. specOnlyRules is the right preset here:
@@ -876,7 +901,17 @@ function validateBuildBrief(packet, packetPath, spec, context, errors, warnings,
     return;
   }
 
-  const brief = readJson(resolvedPath);
+  let brief;
+  try {
+    brief = readJson(resolvedPath);
+  } catch {
+    addIssue(errors, "build_brief.normalized_path", `Campaign Build Brief normalized artifact is not valid JSON: ${normalizedPath}. Restore it, or save the brief again with ${cmd("record")} brief --packet <packet>.`);
+    return;
+  }
+  if (!isObject(brief)) {
+    addIssue(errors, "build_brief.normalized_path", `Campaign Build Brief normalized artifact is not a valid brief object: ${normalizedPath}. Restore it, or save the brief again with ${cmd("record")} brief --packet <packet>.`);
+    return;
+  }
   const result = validateCampaignBuildBriefArtifact(brief, { spec, normalizedPath });
   for (const issue of result.errors) errors.push(issue);
   for (const issue of result.warnings) warnings.push(issue);
@@ -887,6 +922,86 @@ function validateBuildBrief(packet, packetPath, spec, context, errors, warnings,
   }
 }
 
+// derived.input_currency, computed once per doctor read, and the warnings it
+// gives: a stage owed on the brief or on the CampaignSpec, a completed stage
+// with no valid brief or spec stamp, or read against a brief or CampaignSpec
+// that cannot be read, a brief file edited (or unreadable) since it was saved,
+// and the build replay after an input change (owed, or kept by the
+// operator's recorded decision). None is an error; `next` routes to the owed
+// stage itself.
+function validateInputCurrency({ packet, packetPath, spec, report, warnings, derived }) {
+  const currency = derived.input_currency || deriveInputCurrency({ packet, packetPath, report, spec: isObject(spec) ? spec : null });
+  derived.input_currency = currency;
+  if (!isObject(report?.stages)) return;
+  // A stage stamped with other spec content than the file holds now, while
+  // the report identity already names the file's content (an identity edited
+  // by hand): the same warning the identity comparison gives.
+  const owedOnSpec = Object.keys(currency.reasons).filter((key) => currency.reasons[key] === "spec_material_changed");
+  if (owedOnSpec.length && !warnings.some((issue) => issue.code === "spec.material_stale")) {
+    addIssue(warnings, "spec.material_stale", SPEC_MATERIAL_STALE_MESSAGE, { stages: owedOnSpec, bound_material_hash: currency.spec.bound, current_material_hash: currency.spec.current });
+  }
+  const specUnstamped = Object.keys(currency.stages).filter((key) => currency.reasons[key] === "input_binding_unknown" && !SPEC_STAMP.test(String(report.stages[key]?.source_spec_material_hash ?? "")));
+  if (specUnstamped.length) {
+    addIssue(warnings, "spec.binding_unknown", `Recorded ${specUnstamped.join(", ")} ${specUnstamped.length === 1 ? "does" : "do"} not say which CampaignSpec content ${specUnstamped.length === 1 ? "it was" : "they were"} made against, so ${specUnstamped.length === 1 ? "it reads" : "they read"} unconfirmed, not current. Record ${specUnstamped.join(", ")} again (${specUnstamped.map((key) => (key === "assembly" ? "record build" : key === "polish" ? "record polish" : "qa run")).join(", ")}).`, { stages: specUnstamped });
+  }
+  const owedOnBrief = Object.keys(currency.reasons).filter((key) => currency.reasons[key] === "brief_material_changed");
+  if (owedOnBrief.length) {
+    addIssue(warnings, "build_brief.material_changed", `The Campaign Build Brief's content changed since ${owedOnBrief.join(", ")} ${owedOnBrief.length === 1 ? "was" : "were"} recorded, so ${owedOnBrief.length === 1 ? "it is" : "they are"} owed again. Save the brief with ${cmd("record")} brief --packet <packet> (it keeps stage history), then record ${owedOnBrief.join(", ")} again.`, { stages: owedOnBrief });
+  }
+  const unstamped = Object.keys(currency.stages).filter((key) => {
+    const stage = report.stages[key];
+    if (currency.reasons[key] !== "input_binding_unknown") return false;
+    const stamp = stage?.source_brief_material;
+    return !wellFormedBriefMaterial(stamp);
+  });
+  if (unstamped.length) {
+    addIssue(warnings, "build_brief.binding_unknown", `Recorded ${unstamped.join(", ")} ${unstamped.length === 1 ? "does" : "do"} not say which Campaign Build Brief content ${unstamped.length === 1 ? "it was" : "they were"} made against, so ${unstamped.length === 1 ? "it reads" : "they read"} unconfirmed, not current. Record ${unstamped.join(", ")} again (${unstamped.map((key) => (key === "assembly" ? "record build" : key === "polish" ? "record polish" : "qa run")).join(", ")}).`, { stages: unstamped });
+  }
+  // A completed stage with a well-formed stamp also reads unknown when the
+  // current brief or CampaignSpec cannot be read: there is nothing to compare
+  // that stamp with. The warning names the file to restore; a stage whose
+  // stamp is missing or malformed is named by the stamp warning above only.
+  const unknownStages = Object.keys(currency.stages).filter((key) => currency.reasons[key] === "input_binding_unknown");
+  const unconfirmed = (stages) => `recorded ${stages.join(", ")} ${stages.length === 1 ? "reads" : "read"} unconfirmed, not current`;
+  const briefUnreadable = unknownStages.filter((key) => !unstamped.includes(key));
+  if (briefUnreadable.length && currency.brief.current === null) {
+    const normalizedPath = optionalString(packet?.build_brief?.normalized_path);
+    addIssue(warnings, "build_brief.binding_unknown", `${normalizedPath ? `The normalized Campaign Build Brief ${normalizedPath} cannot be read as a brief object` : "The Build Packet names no build_brief.normalized_path, so the current Campaign Build Brief cannot be read"}, so ${unconfirmed(briefUnreadable)}. Restore it, or save the brief again with ${cmd("record")} brief --packet <packet>.`, { stages: briefUnreadable, ...(normalizedPath ? { normalized_path: normalizedPath } : {}) });
+  }
+  const specPath = optionalString(packet?.spec?.local_path);
+  const specUnreadable = unknownStages.filter((key) => !specUnstamped.includes(key));
+  if (specUnreadable.length && currency.spec.current === null && specPath) {
+    addIssue(warnings, "spec.binding_unknown", `The CampaignSpec ${specPath} cannot be read as a JSON object, so ${unconfirmed(specUnreadable)}. Restore it, then run doctor again.`, { stages: specUnreadable, spec_path: specPath });
+  }
+  const inputPath = optionalString(packet?.build_brief?.input_path);
+  const savedSha = optionalString(report.build_brief?.input_sha256);
+  const briefFile = inputPath ? resolveFromFile(packetPath, inputPath) : null;
+  if (briefFile && savedSha && existsSync(briefFile)) {
+    // Read only a readable regular file: a pipe would block, a directory throws.
+    const unusable = briefFileUnusable(briefFile);
+    let bytes = null;
+    if (!unusable) {
+      try {
+        bytes = `sha256:${createHash("sha256").update(readFileSync(briefFile)).digest("hex")}`;
+      } catch {
+        bytes = null;
+      }
+    }
+    if (bytes === null) {
+      addIssue(warnings, "build_brief.input_unsaved", `The brief file ${inputPath} ${unusable || "cannot be read"}, so doctor cannot tell whether it changed since it was saved; the build reads the saved brief. Restore it, or save a readable brief file with ${cmd("record")} brief --packet <packet> --brief <file>.`, { input_path: inputPath });
+    } else if (bytes !== savedSha) {
+      addIssue(warnings, "build_brief.input_unsaved", `The brief file ${inputPath} changed since it was saved. Save it with ${cmd("record")} brief --packet <packet>; until then the build reads the saved brief.`, { input_path: inputPath });
+    }
+  }
+  if (currency.reasons.assembly === "output_unchanged_after_input_change") {
+    addIssue(warnings, "assembly.output_unchanged_after_input_change", `The build output is unchanged since the brief or CampaignSpec change was recorded, so the change has not reached the pages and build is owed again. Rebuild, or, only on the operator's explicit decision that the change needs no output change, record build with --deviation-reason "<the operator's reason>".`);
+  }
+  const keptReason = report.stages.assembly?.unchanged_output_reason;
+  if (currency.stages.assembly === "current" && isObject(keptReason) && typeof keptReason.text === "string") {
+    addIssue(warnings, "assembly.output_unchanged_by_operator_decision", `The build output was kept unchanged after an input change by the operator's recorded decision: "${keptReason.text}".`, { reason: keptReason.text });
+  }
+}
+
 function validateProofPolicyObject(policy, location, warnings, ready, { requireBrowserQa = false } = {}) {
   if (!isObject(policy)) {
     addIssue(warnings, location, `${location} must be an object when present.`);
@@ -2407,7 +2522,7 @@ function recordSmokeQc({ subject, targetRepo, pages, environment, deployBase, wa
 }
 
 function recordSdkMarkupGate({ subject, pages, errors, warnings, ready, derived }) {
-  const gate = evaluateSdkMarkup({ subject, pages });
+  const gate = evaluateSdkMarkup({ subject, pages, sdkVersion: campaignSdkPin(derived?.target_repo, subject?.public_route_slug) });
   if (Array.isArray(derived?.checkpoint_gates)) derived.checkpoint_gates.push(gate);
 
   if (gate.status === "not_applicable") {
@@ -2438,6 +2553,16 @@ function recordSdkMarkupGate({ subject, pages, errors, warnings, ready, derived
   return gate;
 }
 
+// The campaign's SDK pin from the target's campaigns.json entry, when it is an
+// exact released version; else null. The SDK markup check reads a page's own
+// loader pin first and falls back to this one.
+function campaignSdkPin(targetRepo, publicRouteSlug) {
+  if (!targetRepo || !publicRouteSlug) return null;
+  const load = loadPageKitCampaignEntry({ targetRepo, publicRouteSlug });
+  const version = load.status === "ok" ? load.entry?.sdk_version : null;
+  return isReleasedSdkVersion(version) ? version : null;
+}
+
 // Route drift: a CampaignSpec page whose declared route has no built page at
 // that path. page-kit derives the public route from the source FILENAME, so a
 // file named presell-running.html builds at /presell-running/ even if the spec
@@ -4257,7 +4382,7 @@ export function validateBuiltPlaceholderTextResidue(brandContract, warnings, rea
     return;
   }
   const terms = [...new Set(hits.map((hit) => hit.label))].join(", ");
-  if (report && qaGatePassedForCurrentBuild(report, QA_GATE_PLACEHOLDER_TEXT_RESIDUE, { buildFingerprint: currentBuildFingerprint(report) })) {
+  if (report && qaGatePassedForCurrentBuild(report, QA_GATE_PLACEHOLDER_TEXT_RESIDUE, { buildFingerprint: currentBuildFingerprint(report), qaCurrency: derived.input_currency?.stages?.qa ?? "unknown" })) {
     ready.push(`Static scan still sees placeholder-term text (${terms}: ${summarizeCopyMatches(hits)}), but the browser residue gate passed on this build; QA's rendered-text verdict stands.`);
     return;
   }

package/src/doctor/inspect.mjs

@@ -5,6 +5,7 @@ import { withHtmlScanSnapshot } from "../html-scan.mjs";
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { shellToken } from "../shell-token.mjs";
+import { cmd } from "../install-invocation.mjs";
 import { commitAssemblyReport, recordProducerStageOutcome } from "../stage-ledger.mjs";
 import { annotateDoctorIssueCauses } from "../finding-cause.mjs";
 import { DOCTOR_SIDECAR_SCHEMA } from "../doctor-sidecar.mjs";
@@ -244,6 +245,18 @@ export function doctorBuiltOutput(args) {
     qc_results: [],
   };
   ready.push(`Resolved ${scope.html_count} built page(s) from ${relFromDir(targetRepo, scope.campaign_dir)} (slug "${scope.slug || "(site root)"}")`);
+  // #583: --base-url reads like a check of the deployed site, but these checks
+  // read only the local built files. Say so wherever the URL is given, and
+  // name the command that does load the served pages.
+  if (baseUrl) {
+    derived.base_url = { value: baseUrl, fetched: false, recorded_as: "deploy.preview_url" };
+    // Without --family there is no value to print that the CLI would accept,
+    // so the command is printed only when it is runnable as shown.
+    const servedCheck = family
+      ? `To check the served pages, run ${cmd("qa", `run --site ${shellToken(String(args.built || args.site))} --base-url ${shellToken(baseUrl)} --family ${shellToken(family)} --browser`)}.`
+      : `To check the served pages, run ${cmd("qa")} run --site with this --base-url and the campaign's --family, plus --browser.`;
+    ready.push(`Checked the local built files only: --base-url ${baseUrl} was not fetched; it only fills deploy.preview_url in the minimal Build Packet. ${servedCheck}`);
+  }
 
   const resolution = resolveBrandContractOnce(derived, family);
   let brandContract = null;

package/src/doctor/next-step.mjs

@@ -12,12 +12,12 @@ import {
 import {
   NEXT_STAGE_ORDER,
   NEXT_STAGE_OWNERS,
-  STAGE_TERMINAL_STATUS_PREFIXES,
   reportKeyForCliStage,
   stageIsBlocked,
   stageIsTerminal,
 } from "../orchestration-stage-contract.mjs";
 import { evaluatePolishGate } from "../polish-gate.mjs";
+import { effectiveStageStatus, effectiveStatusIsTerminal } from "../input-currency.mjs";
 import { cmd } from "../install-invocation.mjs";
 import { isObject, isNonEmptyString, optionalString, resolveFromFile, addIssue, filesystemPathsMatch } from "../cli-helpers.mjs";
 import { orderPathDepthDrift } from "./checks.mjs";
@@ -440,6 +440,16 @@ function pickNextStage(report, { errors = [], derived = null }, prepareBuildGate
     };
   }
 
+  // A build made against earlier brief or CampaignSpec content, or one whose
+  // inputs cannot be confirmed, is owed before anything downstream of it.
+  const inputCurrency = derived?.input_currency || null;
+  if (["owed", "unknown"].includes(inputCurrency?.stages?.assembly)) {
+    return {
+      stage: "build",
+      reason: inputCurrency.reasons?.assembly || "input_binding_unknown",
+    };
+  }
+
   if (polishGate.status === "blocked") {
     if (polishGateRequiresBuild(polishGate)) {
       return {
@@ -474,7 +484,9 @@ function pickNextStage(report, { errors = [], derived = null }, prepareBuildGate
         reason: `Stage "${reportKey}" is not recorded in the assembly report; run "${cliStage}" next.`,
       };
     }
-    const status = String(stage.status || "");
+    // The effective status: a stage owed again by an input change reads
+    // required, and one whose inputs or raw status cannot be read, unknown.
+    const status = effectiveStageStatus(reportKey, stage, inputCurrency);
     if (stageIsBlocked(status)) {
       return {
         stage: cliStage,
@@ -482,10 +494,7 @@ function pickNextStage(report, { errors = [], derived = null }, prepareBuildGate
         blocked: true,
       };
     }
-    // Match by prefix so "completed_with_warnings" and future suffixes
-    // (e.g. "completed_partial") count as terminal.
-    const isTerminal = STAGE_TERMINAL_STATUS_PREFIXES.some((t) => status.startsWith(t));
-    if (!isTerminal) {
+    if (!effectiveStatusIsTerminal(status)) {
       return {
         stage: cliStage,
         reason: `Stage "${reportKey}" has status "${status || "(unset)"}"; run "${cliStage}" next.`,