@nextcommerce/campaigns-os 1.53.0 → 1.55.0

package/src/sdk-repin.mjs

@@ -0,0 +1,282 @@
+// `sdk repin`: rewrite the hardcoded Campaign Cart SDK pins of a static
+// campaign repo (one with no page-kit `_data/campaigns.json`).
+//
+// The references are the ones the campaign-ecosystem scan already finds: every
+// http(s) Campaign Cart URL that points at a loader or dist artifact
+// (loader.js, campaign-cart.css), in HTML and script files, HTML comments
+// masked. Only a semver pin (`@vX.Y.Z` or `@X.Y.Z`) below the target version is
+// rewritten, and only its version segment changes; the leading `v` is kept as
+// written. `@latest`, `@main`, commit refs and prerelease refs are reported and
+// left alone, as is a pin already at or above the target (never a downgrade).
+//
+// Preview is the default and writes nothing. `--apply` writes the files and a
+// change record at .campaign-runtime/sdk-repin.json (schema
+// campaigns-os-sdk-repin/v0) that a Run Record can cite by path and sha256.
+// A repo with `_data/campaigns.json` is refused: page-kit owns that pin.
+
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { isReleasedSdkVersion } from "../campaign-spec/dist/index.js";
+import {
+  campaignCartArtifactReferences,
+  isCampaignCartHtmlFile,
+  listCampaignCartScanFiles,
+  listCampaignCartSourceFiles,
+  loadSdkSupportPolicy,
+} from "./campaign-ecosystem.mjs";
+import { refused } from "./lifecycle.mjs";
+import { compareVersions, relPath, unique } from "./repo-scan.mjs";
+
+export const SDK_REPIN_SCHEMA = "campaigns-os-sdk-repin/v0";
+export const SDK_REPIN_RECORD_REL_PATH = ".campaign-runtime/sdk-repin.json";
+const PAGE_KIT_CAMPAIGNS_SUFFIX = "_data/campaigns.json";
+
+const PACKAGE_VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")).version || null;
+  } catch {
+    return null;
+  }
+})();
+
+/** A --target-sdk value repin accepts: a released x.y.z, with or without a leading v. */
+export const isRepinTargetVersion = (value) => isReleasedSdkVersion(String(value ?? "").trim().replace(/^v/, ""));
+
+/**
+ * Plan the rewrite without touching the target. `targetSdk` is an x.y.z (a
+ * leading v is accepted); when absent the policy's preferred_minimum is the
+ * target, the same policy the ecosystem scan evaluates pins against. A target
+ * that is not a directory, or a target version that is not a released SDK
+ * version, is refused (a tagged refusal: one line, nothing journaled).
+ */
+export function planSdkRepin(options = {}) {
+  return planWithSpans(options).plan;
+}
+
+// The plan plus the internal rewrite spans (file offsets) runSdkRepin needs;
+// the spans never leave this module.
+function planWithSpans({ targetRepo, targetSdk = null, sdkSupportPolicy = null } = {}) {
+  const target = resolve(targetRepo);
+  if (!existsSync(target)) throw refused(`sdk repin: --target ${targetRepo} does not exist.`);
+  if (!statSync(target).isDirectory()) throw refused(`sdk repin: --target ${targetRepo} is not a directory.`);
+  const policy = loadSdkSupportPolicy(sdkSupportPolicy);
+  const explicit = targetSdk !== null && targetSdk !== undefined;
+  const toVersion = explicit ? String(targetSdk).trim().replace(/^v/, "") : policy.preferred_minimum;
+  if (!isReleasedSdkVersion(toVersion)) {
+    throw refused(explicit
+      ? `sdk repin: --target-sdk ${targetSdk} is not a released SDK version (x.y.z).`
+      : `sdk repin: the SDK support policy (${policy.source}) names no usable preferred_minimum; pass --target-sdk <x.y.z>.`);
+  }
+  const base = {
+    schema_version: SDK_REPIN_SCHEMA,
+    target_repo: target,
+    to_version: toVersion,
+    to_version_source: explicit ? "argument" : "policy.preferred_minimum",
+    policy,
+  };
+
+  const pageKitData = findPageKitCampaignData(target);
+  if (pageKitData.length) {
+    return { spans: [], plan: {
+      ...base,
+      ok: false,
+      status: "refused_page_kit",
+      message: `${pageKitData.join(", ")} exists: this is a page-kit repo, whose Campaign Cart pin lives in _data/campaigns.json and is owned by page-kit. Use \`campaigns-os page-kit sync --packet <campaign-runtime.build.json>\` to set it from the CampaignSpec; sdk repin rewrites hardcoded pins in static repos only. Nothing was changed.`,
+      page_kit_data: pageKitData,
+      references: [],
+      rewrites: [],
+      left_alone: { not_semver: [], at_target: [], newer_than_target: [] },
+      files: [],
+    } };
+  }
+
+  const references = [];
+  for (const file of listCampaignCartSourceFiles(target)) {
+    const raw = readText(file);
+    if (raw === null) continue;
+    for (const entry of campaignCartArtifactReferences(raw, { isHtml: isCampaignCartHtmlFile(file) })) {
+      // Masking keeps offsets, so the span is the ref in the raw text; a
+      // mismatch would mean the two disagree, and nothing is rewritten then.
+      if (raw.slice(entry.ref_start, entry.ref_end) !== entry.ref) continue;
+      const artifact = /\.css(?:[?#]|$)/i.test(entry.url) ? "css" : "loader";
+      const action = !entry.version
+        ? "not_semver"
+        : compareVersions(entry.version, toVersion) < 0
+          ? "rewrite"
+          : compareVersions(entry.version, toVersion) === 0 ? "at_target" : "newer_than_target";
+      const newRef = action === "rewrite" ? `${entry.ref.startsWith("v") ? "v" : ""}${toVersion}` : null;
+      const urlRefStart = entry.ref_start - entry.url_start;
+      references.push({
+        path: relPath(target, file),
+        line: entry.line,
+        artifact,
+        url: entry.url,
+        ref: entry.ref,
+        version: entry.version,
+        action,
+        new_ref: newRef,
+        new_url: newRef ? `${entry.url.slice(0, urlRefStart)}${newRef}${entry.url.slice(urlRefStart + entry.ref.length)}` : null,
+        ref_start: entry.ref_start,
+        ref_end: entry.ref_end,
+      });
+    }
+  }
+
+  const rewrites = references.filter((entry) => entry.action === "rewrite");
+  const status = !references.length
+    ? "no_references"
+    : rewrites.length ? "changes" : "nothing_to_change";
+  const spans = rewrites.map(({ path, ref_start, ref_end, ref, new_ref }) => ({ path, ref_start, ref_end, ref, new_ref }));
+  return { spans, plan: {
+    ...base,
+    ok: true,
+    status,
+    message: statusMessage(status, toVersion),
+    references: references.map(publicReference),
+    rewrites: rewrites.map(publicReference),
+    left_alone: {
+      not_semver: references.filter((entry) => entry.action === "not_semver").map(publicReference),
+      at_target: references.filter((entry) => entry.action === "at_target").map(publicReference),
+      newer_than_target: references.filter((entry) => entry.action === "newer_than_target").map(publicReference),
+    },
+    files: unique(rewrites.map((entry) => entry.path)),
+  } };
+}
+
+/**
+ * Plan, and with `apply` write. Returns the plan plus `mode`, `applied`,
+ * `change_record` and (after a write) `verified`, the re-scan confirming no
+ * reference below the target is left.
+ */
+export function runSdkRepin({ targetRepo, targetSdk = null, apply = false, sdkSupportPolicy = null, now = () => new Date() } = {}) {
+  const { plan, spans } = planWithSpans({ targetRepo, targetSdk, sdkSupportPolicy });
+  const result = { ...plan };
+  result.mode = apply ? "apply" : "preview";
+  result.applied = false;
+  result.change_record = { path: SDK_REPIN_RECORD_REL_PATH, written: false, sha256: null, record: null };
+  if (plan.status !== "changes") return result;
+
+  const record = buildChangeRecord(plan, now());
+  result.change_record.record = record;
+  if (!apply) return result;
+
+  const byFile = new Map();
+  for (const span of spans) {
+    if (!byFile.has(span.path)) byFile.set(span.path, []);
+    byFile.get(span.path).push(span);
+  }
+  // Every file is re-read and every span checked BEFORE any file is written,
+  // so a file that changed since the plan aborts the run with nothing written.
+  const updates = [];
+  for (const [path, fileSpans] of byFile) {
+    const file = join(plan.target_repo, path);
+    let text = readFileSync(file, "utf8");
+    // Right to left, so earlier offsets stay valid.
+    for (const span of [...fileSpans].sort((a, b) => b.ref_start - a.ref_start)) {
+      if (text.slice(span.ref_start, span.ref_end) !== span.ref) {
+        throw refused(`sdk repin: ${path} changed between the scan and the write (a pinned reference is no longer where the scan found it); no file was written and no change record was made. Re-run sdk repin to plan against the current files.`);
+      }
+      text = `${text.slice(0, span.ref_start)}${span.new_ref}${text.slice(span.ref_end)}`;
+    }
+    updates.push({ file, text });
+  }
+  for (const { file, text } of updates) writeFileSync(file, text);
+  const recordPath = join(plan.target_repo, SDK_REPIN_RECORD_REL_PATH);
+  mkdirSync(dirname(recordPath), { recursive: true });
+  const body = `${JSON.stringify(record, null, 2)}\n`;
+  writeFileSync(recordPath, body);
+  result.applied = true;
+  result.change_record.written = true;
+  result.change_record.sha256 = createHash("sha256").update(body).digest("hex");
+
+  const after = planSdkRepin({ targetRepo: plan.target_repo, targetSdk: plan.to_version, sdkSupportPolicy });
+  result.verified = after.ok && after.rewrites.length === 0;
+  result.message = `Rewrote ${plan.rewrites.length} reference(s) in ${plan.files.length} file(s) to ${plan.to_version}.`;
+  return result;
+}
+
+// The change record: what moved, with repo-relative paths only, so it can be
+// committed and cited (path + sha256) by a Run Record.
+function buildChangeRecord(plan, generatedAt) {
+  return {
+    schema_version: SDK_REPIN_SCHEMA,
+    generated_at: generatedAt.toISOString(),
+    campaigns_os_version: PACKAGE_VERSION,
+    command: "sdk repin",
+    to_version: plan.to_version,
+    to_version_source: plan.to_version_source,
+    from_versions: unique(plan.rewrites.map((entry) => entry.version)).sort(compareVersions),
+    files_touched: plan.files,
+    reference_count: plan.rewrites.length,
+    rewrites: plan.rewrites.map(({ path, line, artifact, ref, new_ref }) => ({ path, line, artifact, from: ref, to: new_ref })),
+    left_alone: {
+      not_semver: plan.left_alone.not_semver.map(({ path, line, ref }) => ({ path, line, ref })),
+      at_target: plan.left_alone.at_target.length,
+      newer_than_target: plan.left_alone.newer_than_target.map(({ path, line, ref }) => ({ path, line, ref })),
+    },
+  };
+}
+
+export function formatSdkRepinReport(result) {
+  const lines = [];
+  const header = result.mode === "apply" ? "sdk repin: apply" : "sdk repin: preview (nothing written; re-run with --apply to write)";
+  lines.push(header);
+  lines.push(`Target: ${result.target_repo}`);
+  lines.push(`Target SDK: ${result.to_version} (${result.to_version_source === "argument" ? "--target-sdk" : `policy preferred_minimum, ${result.policy.source}`})`);
+  if (result.status === "refused_page_kit") {
+    lines.push(`Refused: ${result.message}`);
+    return lines.join("\n");
+  }
+  if (result.rewrites.length) {
+    lines.push(`${result.applied ? "Rewrote" : "Would rewrite"} ${result.rewrites.length} reference(s) in ${result.files.length} file(s):`);
+    for (const entry of result.rewrites) {
+      lines.push(`  ${entry.path}:${entry.line}  ${entry.url}`);
+      lines.push(`    -> ${entry.new_url}`);
+    }
+  }
+  if (result.left_alone.not_semver.length) {
+    lines.push(`Left alone, not semver-pinned (${result.left_alone.not_semver.length}):`);
+    for (const entry of result.left_alone.not_semver) lines.push(`  ${entry.path}:${entry.line}  @${entry.ref}  ${entry.url}`);
+  }
+  if (result.left_alone.newer_than_target.length) {
+    lines.push(`Left alone, newer than ${result.to_version} (${result.left_alone.newer_than_target.length}):`);
+    for (const entry of result.left_alone.newer_than_target) lines.push(`  ${entry.path}:${entry.line}  @${entry.ref}`);
+  }
+  if (result.left_alone.at_target.length) lines.push(`Already at ${result.to_version}: ${result.left_alone.at_target.length} reference(s).`);
+  if (result.status !== "changes") lines.push(result.message);
+  if (result.change_record.written) {
+    lines.push(`Change record: ${result.change_record.path} (sha256 ${result.change_record.sha256})`);
+    lines.push(`Re-scan: ${result.verified ? "no pinned reference below the target remains" : "references below the target remain; inspect the files"}`);
+  }
+  return lines.join("\n");
+}
+
+function statusMessage(status, toVersion) {
+  if (status === "no_references") return "No Campaign Cart loader or stylesheet reference was found; nothing to change.";
+  if (status === "nothing_to_change") return `No semver-pinned reference is below ${toVersion}; nothing to change.`;
+  return `Semver-pinned references below ${toVersion} can be rewritten.`;
+}
+
+function publicReference({ path, line, artifact, url, ref, version, action, new_ref, new_url }) {
+  return { path, line, artifact, url, ref, version, action, new_ref, new_url };
+}
+
+// `_data/campaigns.json` at the target or under any directory the scan walks
+// (a page-kit project nested in a larger repo is still page-kit's pin).
+function findPageKitCampaignData(target) {
+  return listCampaignCartScanFiles(target)
+    .map((file) => relPath(target, file))
+    .filter((path) => path === PAGE_KIT_CAMPAIGNS_SUFFIX || path.endsWith(`/${PAGE_KIT_CAMPAIGNS_SUFFIX}`))
+    .sort();
+}
+
+function readText(path) {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+}

package/src/stage-ledger.mjs

@@ -115,7 +115,7 @@ const HISTORY_IDENTITY_FIELDS = Object.freeze([
   "source_brief_material", "source_spec_material_hash", "verdict_run_id", "purchase_proof", "outputs", "evidence",
 ]);
 export const HISTORY_ARCHIVED_BY = Object.freeze(["record brief", "record spec", "record build", "record polish", "qa run", "prepare-build --force"]);
-export const HISTORY_REASON_CODES = Object.freeze(["brief_presentation_changed", "brief_qa_policy_changed", "spec_material_changed", "rerecorded", "force_reset"]);
+export const HISTORY_REASON_CODES = Object.freeze(["brief_presentation_changed", "brief_qa_policy_changed", "spec_material_changed", "rerecorded", "force_reset", "build_output_changed"]);
 const ARCHIVED_STAGE_KEYS = Object.freeze(["assembly", "polish", "qa"]);
 
 const isCompletedStatus = (status) => typeof status === "string" && status.startsWith("completed");
@@ -541,14 +541,26 @@ export function qaGateEvidence(report, gate) {
   };
 }
 
+export function qaRecordedBuildFingerprint(report) {
+  return optionalString(report?.stages?.qa?.evidence?.qc_build_fingerprint)
+    || optionalString(report?.stages?.qa?.evidence?.source_build_fingerprint);
+}
+
+export function qaRecordedForCurrentBuild(report, buildFingerprint) {
+  const recorded = qaRecordedBuildFingerprint(report);
+  const current = optionalString(buildFingerprint);
+  return Boolean(recorded && current && recorded === current);
+}
+
 // `qaCurrency` is QA's read-time input currency
 // (derived.input_currency.stages.qa): while QA is owed again or its inputs
 // cannot be confirmed, no QA gate pass counts.
 export function qaGatePassedForCurrentBuild(report, gate, { buildFingerprint, qaCurrency = null }) {
   if (qaCurrency === "owed" || qaCurrency === "unknown") return false;
   const outcome = qaGateEvidence(report, gate);
-  const current = optionalString(buildFingerprint);
-  return Boolean(outcome && outcome.status === QA_STATUS.PASS && current && outcome.source_build_fingerprint === current);
+  return Boolean(outcome && outcome.status === QA_STATUS.PASS
+    && outcome.source_build_fingerprint === optionalString(buildFingerprint)
+    && qaRecordedForCurrentBuild(report, buildFingerprint));
 }
 
 /**

package/src/stage-record.mjs

@@ -26,11 +26,12 @@ import { fileURLToPath } from "node:url";
 import Ajv2020 from "ajv/dist/2020.js";
 
 import { BRAND_LAYER_FILENAMES } from "./brand-theme.mjs";
+import { ADAPTER_DECISION_SCALAR_VALUES } from "./adapter-decision-contract.mjs";
 import { computeBuildFingerprint, resolveBuiltSiteScope } from "./built-site-scope.mjs";
 import { resolveCampaignWorkspace, targetRepoFor } from "./campaign-workspace.mjs";
 import { isObject, optionalString, readJsonIfExists, requireArg } from "./cli-helpers.mjs";
 import { LOCAL_PROOF_BUILD_ENVIRONMENT, LOCAL_PROOF_PRODUCTION_ENVIRONMENT, isLocalServePacket } from "./local-proof.mjs";
-import { CARRIED_FORWARD } from "./local-preview-policy.mjs";
+import { polishCarriedForwardForLadder } from "./local-preview-policy.mjs";
 import { isLoopbackHostname } from "./remit.mjs";
 import { campaignRouteRoot } from "./route-identity.mjs";
 import { writeJsonAtomic } from "./doctor-sidecar.mjs";
@@ -48,7 +49,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, assemblyReportMatchesPacket, commitAssemblyReport, inputChangeFor } from "./stage-ledger.mjs";
+import { applyDerivedAssemblyReportSummary, archiveStageRecord, archiveSupersededRecord, assemblyReportMatchesPacket, commitAssemblyReport, inputChangeFor } from "./stage-ledger.mjs";
 import { withTargetLockSync } from "./target-lock.mjs";
 import { commerceScopeFromScope } from "./theme-gate.mjs";
 
@@ -60,7 +61,7 @@ export const RECORD_STAGES = Object.freeze(["setup", "build", "polish", "theme",
 const RECORD_FLAGS = Object.freeze(["packet", "context", "report", "dry-run", "json", "run-id", "lifecycle-journal", "deviation-reason"]);
 const POLISH_RECORD_FLAGS = Object.freeze(["evidence"]);
 const DEPLOY_RECORD_FLAGS = Object.freeze(["base-url"]);
-const BUILD_RECORD_FLAGS = Object.freeze(["build-environment"]);
+const BUILD_RECORD_FLAGS = Object.freeze(["build-environment", "adapter-decision"]);
 // `record brief` saves a brief file: --brief names it (otherwise intake's
 // discovery finds it).
 const BRIEF_RECORD_FLAGS = Object.freeze(["brief"]);
@@ -130,10 +131,43 @@ export function refuseRecord(stage, problems) {
   return new Error(`record ${stage} refused; nothing was written:\n${problems.map((problem) => `- ${problem}`).join("\n")}`);
 }
 
+function parseAdapterDecisions(value) {
+  const allowedKeys = Object.keys(ADAPTER_DECISION_SCALAR_VALUES).join(", ");
+  const reject = (reason, key = null) => {
+    const allowedValues = key && Object.hasOwn(ADAPTER_DECISION_SCALAR_VALUES, key)
+      ? ` Allowed values for ${key}: ${ADAPTER_DECISION_SCALAR_VALUES[key].join(", ")}.`
+      : "";
+    throw refused(`${reason} Allowed keys: ${allowedKeys}.${allowedValues}`);
+  };
+  if (typeof value !== "string" || !value) reject("--adapter-decision requires a comma-separated list of key=value pairs.");
+  const decisions = {};
+  for (const pair of value.split(",")) {
+    if (!pair) reject("--adapter-decision has an empty pair; use key=value pairs separated by commas.");
+    const equal = pair.indexOf("=");
+    if (equal < 0) reject(`--adapter-decision pair ${JSON.stringify(pair)} must be key=value.`);
+    const key = pair.slice(0, equal);
+    const choice = pair.slice(equal + 1);
+    if (!key || /\s/.test(key)) reject(`--adapter-decision key ${JSON.stringify(key)} must be a nonempty key without whitespace.`);
+    if (key === "wrapper_policy") reject("wrapper_policy is selected at intake with prepare-build --wrapper-policy or the source-html manifest's wrapper_policy option; record build cannot change it.");
+    if (!Object.hasOwn(ADAPTER_DECISION_SCALAR_VALUES, key)) reject(`Unknown --adapter-decision key ${JSON.stringify(key)}.`);
+    if (Object.hasOwn(decisions, key)) reject(`Duplicate --adapter-decision key ${JSON.stringify(key)} in one list.`);
+    const allowed = ADAPTER_DECISION_SCALAR_VALUES[key];
+    if (!choice || /\s/.test(choice) || choice.includes("=") || !allowed.includes(choice)) {
+      reject(`--adapter-decision ${key} must be one of: ${allowed.join(", ")} (got ${JSON.stringify(choice)}).`, key);
+    }
+    decisions[key] = choice;
+  }
+  return decisions;
+}
+
 export function parseRecordArgs(args) {
   const stage = args._[1];
+  // The shared argv parser leaves an explicit empty value in positional args.
+  if (stage === "build" && args["adapter-decision"] === true && args._.length === 3 && args._[2] === "") {
+    parseAdapterDecisions("");
+  }
   if (!RECORD_SUBCOMMANDS.includes(stage) || args._.length !== 2) {
-    throw refused(`Use: ${cmd("record")} <${RECORD_SUBCOMMANDS.join("|")}> --packet <campaign-runtime.build.json> [--context <json>] [--report <json>] [--dry-run] [--json]; record polish also takes --evidence <polish-evidence.json>, record deploy --base-url <served url>, record build [--build-environment <${BUILD_ENVIRONMENTS.join("|")}>], and record brief [--brief <yaml|json>].`);
+    throw refused(`Use: ${cmd("record")} <${RECORD_SUBCOMMANDS.join("|")}> --packet <campaign-runtime.build.json> [--context <json>] [--report <json>] [--dry-run] [--json]; record polish also takes --evidence <polish-evidence.json>, record deploy --base-url <served url>, record build [--build-environment <${BUILD_ENVIRONMENTS.join("|")}>] [--adapter-decision <key=value[,key=value...]>], and record brief [--brief <yaml|json>].`);
   }
   const known = new Set([...RECORD_FLAGS, ...(stage === "polish" ? POLISH_RECORD_FLAGS : []), ...(stage === "deploy" ? DEPLOY_RECORD_FLAGS : []), ...(stage === "build" ? BUILD_RECORD_FLAGS : []), ...(stage === "brief" ? BRIEF_RECORD_FLAGS : [])]);
   const unknown = Object.keys(args).filter((key) => key !== "_" && !known.has(key));
@@ -151,6 +185,7 @@ export function parseRecordArgs(args) {
   if (buildEnvironment !== null && !BUILD_ENVIRONMENTS.includes(buildEnvironment)) {
     throw refused(`--build-environment must be one of: ${BUILD_ENVIRONMENTS.join(", ")} (got ${JSON.stringify(buildEnvironment)}).`);
   }
+  const adapterDecisions = Object.hasOwn(args, "adapter-decision") ? parseAdapterDecisions(args["adapter-decision"]) : null;
   return {
     stage,
     packetPath: resolve(requireArg(args, "packet")),
@@ -158,6 +193,7 @@ export function parseRecordArgs(args) {
     baseUrl: stage === "deploy" ? requireArg(args, "base-url") : null,
     dryRun: args["dry-run"] === true,
     buildEnvironment,
+    adapterDecisions,
     briefPath: stage === "brief" && Object.hasOwn(args, "brief") ? resolve(args.brief) : null,
     deviationReason: optionalString(args["deviation-reason"]),
   };
@@ -291,7 +327,8 @@ function currentStamps(inputs) {
   return Object.fromEntries(Object.entries(stamps).filter(([, value]) => value !== null));
 }
 
-function composeBuild(report, { now, recordedBy, fingerprint, buildEnvironment = null, inputs = {}, deviationReason = null }) {
+function composeBuild(report, { now, recordedBy, fingerprint, buildEnvironment = null, adapterDecisions = null, fallbackAdapterDecisions = null, inputs = {}, deviationReason = null }) {
+  const nextReport = adapterDecisions ? { ...report, adapter_decisions: { ...(report.adapter_decisions || fallbackAdapterDecisions || {}), ...adapterDecisions } } : report;
   const sourcePackageFingerprint = currentSourcePackageMaterialFingerprint(report);
   const previousAssembly = stageObject(report, "assembly");
   const stamps = currentStamps(inputs);
@@ -331,9 +368,13 @@ function composeBuild(report, { now, recordedBy, fingerprint, buildEnvironment =
   // Otherwise Polish evidence bound to this exact output stays and anything
   // else is owed again; the evidence object is kept so `polish capture` has
   // somewhere to attach page_load, and its stale identity fields are removed.
+  // A deploy that stamped the build it probed is owed again once the output
+  // differs; one with no stamp (recorded before deploy stamped it) is kept.
+  const deployOwed = deployAfterBuild(stageObject(report, "deploy"), fingerprint, now);
+  const deploy = deployOwed ? { deploy: deployOwed } : {};
   if (detected) {
     const cause = detected === "spec_material_changed" ? "spec" : "presentation";
-    const demoted = demoteStages({ ...report, stages: { ...report.stages, assembly } }, { causes: [cause], now, by: "record build", only: ["polish", "qa"] });
+    const demoted = demoteStages({ ...nextReport, stages: { ...nextReport.stages, assembly, ...deploy } }, { causes: [cause], now, by: "record build", only: ["polish", "qa"] });
     return { report: demoted.report, context: null };
   }
   const previousPolish = stageObject(report, "polish");
@@ -348,7 +389,29 @@ function composeBuild(report, { now, recordedBy, fingerprint, buildEnvironment =
         required_by: "build",
         required_for: ["qa"],
       };
-  return { report: { ...report, stages: { ...report.stages, assembly, polish } }, context: null };
+  return { report: { ...nextReport, stages: { ...nextReport.stages, assembly, polish, ...deploy } }, context: null };
+}
+
+// stages.deploy after a build of `fingerprint`, or null when it is kept: a
+// completed deploy whose source_build_fingerprint names other output goes
+// whole into history (archived_by "record build", reason_code
+// "build_output_changed") and reads required (required_by "build",
+// required_for ["qa"]) until record deploy probes this build. As a demotion
+// does, the live record loses what was written by the completion (completed_at,
+// recorded_by, performed_by) and what describes the old output's probe
+// (source_build_fingerprint, evidence, outputs); blockers, warnings, inputs
+// and commands are kept.
+function deployAfterBuild(previousDeploy, fingerprint, now) {
+  const stamped = optionalString(previousDeploy.source_build_fingerprint);
+  if (!stamped || stamped === fingerprint || !REPLACED_COMPLETED_STATUSES.includes(previousDeploy.status)) return null;
+  const demoted = {
+    ...withoutKeys(previousDeploy, ["source_build_fingerprint", "evidence", "outputs", "completed_at", "recorded_by", "performed_by"]),
+    stage: "deploy",
+    status: "required",
+    required_by: "build",
+    required_for: ["qa"],
+  };
+  return archiveSupersededRecord(demoted, previousDeploy, { by: "record build", reason: "build_output_changed", at: now });
 }
 
 function composePolish(report, { now, recordedBy, fingerprint, input, inputs = {} }) {
@@ -604,12 +667,16 @@ export async function probeLocalPreview({ packetPath, baseUrl, fetchImpl = globa
 }
 
 // A recorded local preview: the packet's deploy.preview_url, and stages.deploy
-// completed with the URL in outputs (what next reads) and the probe as evidence.
-function composeDeploy(report, packet, { now, recordedBy, probe }) {
+// completed with the URL in outputs (what next reads), the probe as evidence,
+// and the build it probed as source_build_fingerprint (doctorFacts has checked
+// it equals stages.assembly.build_fingerprint), so a later record build of
+// different output makes deploy required again, as it does Polish.
+function composeDeploy(report, packet, { now, recordedBy, probe, fingerprint }) {
   const deploy = {
     ...stageObject(report, "deploy"),
     stage: "deploy",
     status: "completed",
+    source_build_fingerprint: fingerprint,
     outputs: [probe.url],
     evidence: probe.routes.map((route) => `${route.url} answered HTTP ${route.status}`),
     completed_at: now,
@@ -681,9 +748,8 @@ function ladderProblems(stage, doctor, report) {
   if (gate) return [`next answers prepare-build: ${gate.reason}`];
   const problems = [];
   for (const earlier of NEXT_STAGE_ORDER.slice(0, NEXT_STAGE_ORDER.indexOf(stage))) {
-    // The rule next's stage picker reads: on the local preview a missing polish
-    // is carried forward (local-preview-policy), and next moves on to deploy.
-    if (earlier === "polish" && doctor.derived?.polish_gate?.status === CARRIED_FORWARD) continue;
+    // The same carried-forward rule next's stage picker reads.
+    if (earlier === "polish" && polishCarriedForwardForLadder(report, doctor.derived?.polish_gate)) continue;
     // The effective status: a stage owed again by an input change reads
     // required, and one whose inputs cannot be confirmed reads unknown.
     const key = reportKeyForCliStage(earlier);
@@ -822,7 +888,7 @@ function readPacketFile(stage, packetPath) {
  * composed or written.
  */
 export function recordStageCommand(args, { now = () => new Date(), beforeLock = null, afterDoctorRead = null, probe = null } = {}) {
-  const { stage, packetPath, evidencePath, dryRun, buildEnvironment, deviationReason } = parseRecordArgs(args);
+  const { stage, packetPath, evidencePath, dryRun, buildEnvironment, adapterDecisions, deviationReason } = parseRecordArgs(args);
   if (!existsSync(packetPath)) throw new Error(`record ${stage}: Build Packet not found at ${packetPath}; run ${cmd("start")} or ${cmd("prepare-build")} first.`);
   if (stage === "deploy" && !probe) throw new Error("record deploy needs the served-route probe; run it through recordCommand.");
   // Operator input, not target state: no campaigns-os writer produces it.
@@ -843,7 +909,7 @@ export function recordStageCommand(args, { now = () => new Date(), beforeLock =
   // A dry run writes nothing, so it takes no lock and creates no lock files
   // (the commitAssemblyReport preview convention); it reads in the same order.
   const run = () => recordUnderLock({
-    stage, packetPath, sidecars, lockedTarget, input, dryRun, timestamp, recordedBy, afterDoctorRead, buildEnvironment, deviationReason,
+    stage, packetPath, sidecars, lockedTarget, input, dryRun, timestamp, recordedBy, afterDoctorRead, buildEnvironment, adapterDecisions, deviationReason,
   });
   const recorded = dryRun ? run() : withTargetLockSync(lockedTarget, run, { command: `record ${stage}` });
   const { composed, facts, layer, reportPath, contextPath, after } = recorded;
@@ -861,7 +927,9 @@ export function recordStageCommand(args, { now = () => new Date(), beforeLock =
     `stages.${stageKey}.status = ${composed.report.stages[stageKey].status}`,
     ...(facts.fingerprint ? [`build output fingerprint ${facts.fingerprint} (doctor derived.build_output_fingerprint.value)`] : []),
     ...(stage === "build" && buildEnvironment ? [`stages.assembly.evidence.build_environment = ${buildEnvironment}`] : []),
+    ...(stage === "build" && adapterDecisions ? Object.entries(adapterDecisions).map(([key, value]) => `report.adapter_decisions.${key} = ${value}`) : []),
     ...(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"] : []),
   ];
   return {
@@ -899,7 +967,7 @@ function recordInputs(doctor) {
   return { briefMaterial: currency?.brief?.current ?? null, specMaterial: currency?.spec?.current ?? null };
 }
 
-function recordUnderLock({ stage, packetPath, sidecars, lockedTarget, input, dryRun, timestamp, recordedBy, afterDoctorRead, buildEnvironment = null, deviationReason = null }) {
+function recordUnderLock({ stage, packetPath, sidecars, lockedTarget, input, dryRun, timestamp, recordedBy, afterDoctorRead, buildEnvironment = null, adapterDecisions = null, deviationReason = null }) {
   // The same workspace `next` resolves, so the record lands in the report
   // `next` reads now, not the one it read before the lock was free.
   const workspace = resolveCampaignWorkspace(packetPath, { ...sidecars, followContextPointer: true });
@@ -934,11 +1002,11 @@ function recordUnderLock({ stage, packetPath, sidecars, lockedTarget, input, dry
     const next = stage === "setup"
       ? composeSetup(report, context, { now: timestamp, recordedBy })
       : stage === "build"
-        ? composeBuild(report, { now: timestamp, recordedBy, fingerprint: facts.fingerprint, buildEnvironment, inputs: recordInputs(doctor), deviationReason })
+        ? composeBuild(report, { now: timestamp, recordedBy, fingerprint: facts.fingerprint, buildEnvironment, adapterDecisions, fallbackAdapterDecisions: adapterDecisions && !report.adapter_decisions ? readJsonIfExists(contextPath)?.adapter_decisions || packet.source_html?.adapter_contract : null, inputs: recordInputs(doctor), deviationReason })
         : stage === "theme"
           ? composeTheme(report, { now: timestamp, recordedBy, layer })
           : stage === "deploy"
-            ? composeDeploy(report, packet, { now: timestamp, recordedBy, probe: input })
+            ? composeDeploy(report, packet, { now: timestamp, recordedBy, probe: input, fingerprint: facts.fingerprint })
             : composePolish(report, { now: timestamp, recordedBy, fingerprint: facts.fingerprint, input, inputs: recordInputs(doctor) });
     applyDerivedAssemblyReportSummary(next.report, recordInputs(doctor));
     // The packet's one new value, deploy.preview_url, is checked by

package/src/standardization-report.mjs

@@ -24,6 +24,7 @@ import {
   loadSdkSupportPolicy,
   scanCampaignCartAppRoot,
 } from "./campaign-ecosystem.mjs";
+import { isReleasedSdkVersion } from "../campaign-spec/dist/index.js";
 import { resolveCommerceCatalog } from "./private-template-source.mjs";
 import {
   assessTemplateFreshness,
@@ -375,7 +376,9 @@ function scanPageKitRoot({
   const bindingFiles = sourceScan.binding_files;
   let checkoutFields = null;
   if (bindingFiles.length) {
-    checkoutFields = inspectCheckoutFields(rootPath, bindingFiles, contract, contractFindings);
+    checkoutFields = inspectCheckoutFields(rootPath, bindingFiles, contract, contractFindings, {
+      sdkVersionForFile: campaignsSdkVersionResolver(campaigns.slugs),
+    });
     capabilities.push("checkout_field_contract");
   }
   const root = {
@@ -504,6 +507,28 @@ function isPageKitRoot(dir) {
   return Boolean(findPageKitDependency(pkg.value));
 }
 
+// The SDK version a Page Kit source file's checkout bindings run against: its
+// campaign's campaigns.json sdk_version (src/<slug>/...), else, for a file no
+// one campaign owns, the lowest pin across campaigns. Unknown (null) when that
+// pin is missing or not an exact release (isReleasedSdkVersion, as doctor
+// reads the same pin), or when any campaign lacks one; the field contract
+// judges unknown as an earlier SDK.
+function campaignsSdkVersionResolver(slugs) {
+  const exact = new Map(slugs.map((entry) => [entry.slug, isReleasedSdkVersion(entry.sdk_version) ? entry.sdk_version : null]));
+  const pins = [...exact.values()];
+  const lowest = pins.length && pins.every(Boolean)
+    ? { version: [...pins].sort(compareVersions)[0], source: "campaigns_json" }
+    : null;
+  return (path) => {
+    const [top, slug] = String(path).split("/");
+    if (top === "src" && exact.has(slug)) {
+      const version = exact.get(slug);
+      return version ? { version, source: "campaigns_json" } : null;
+    }
+    return lowest;
+  };
+}
+
 function readCampaigns(rootPath) {
   const campaignsPath = join(rootPath, "_data", "campaigns.json");
   if (!existsSync(campaignsPath)) {

package/src/target-lock.mjs

@@ -21,9 +21,17 @@ export function targetLockPath(targetRepo) {
 // `command` names the waiting command. The lock does not record which command
 // 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.
+// 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).
 function unavailable(targetRepo, lockPath, command) {
   return (error) => {
+    if (error?.code === "ENOTLOCK") {
+      return Object.assign(new Error(
+        `${command}: the target lock path ${lockPath} is occupied by ${error.obstruction}. `
+        + "It is never removed automatically. Move it out of the way, then retry.",
+        { cause: error },
+      ), { code: error.code, obstruction: error.obstruction });
+    }
     if (error?.code !== "EEXIST") {
       return new Error(`${command} could not take the target lock at ${lockPath}${error?.code ? ` (${error.code})` : ""}: ${error?.message}`, { cause: error });
     }