@nextcommerce/campaigns-os 1.53.0 → 1.54.0

package/src/campaign-ecosystem.mjs

@@ -2,6 +2,8 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { isReleasedSdkVersion } from "../campaign-spec/dist/index.js";
+import { sdkVersionAtLeast } from "./sdk-attribute-index.mjs";
 import { shellToken } from "./shell-token.mjs";
 import {
   compareVersions,
@@ -40,6 +42,7 @@ const MAX_SAMPLE_COUNT = 8;
 // are still discovered — they just can't be evaluated against version policy.
 const LOADER_URL_PATTERN = /https?:\/\/[^"'\s]*campaign-cart@([^"'\s/]+)[^"'\s]*/g;
 const LOADER_ARTIFACT_PATTERN = /\/loader(?:\.min)?\.js\b|\/dist\//;
+const LOADER_URL_INDEXED_PATTERN = new RegExp(LOADER_URL_PATTERN.source, "gd");
 const CAMPAIGN_ID_META_PATTERN = /<meta\s+[^>]*name=["']next-campaign-id["'][^>]*>/gi;
 const NEXT_CONFIG_PATTERN = /window\.nextConfig\s*=/;
 const DATA_NEXT_PATTERN = /\bdata-next-[a-zA-Z0-9_-]+/g;
@@ -180,18 +183,19 @@ export function scanCampaignCartAppRoot({
   const loader = collectLoaderReferences(root, [...htmlFiles, ...scriptFiles]);
   // Delivery can be a hosted loader URL OR a bundled npm dependency. When the
   // SDK ships as a dependency there is no loader ref to discover, but the pin
-  // is still a real version signal — record it and feed a resolved semver into
-  // version policy like a discovered version (source-distinguishable below).
+  // is still a real version signal — record it and feed its floor (the lowest
+  // version the spec lets npm install) into version policy like a discovered
+  // version (source-distinguishable below).
   const bundled = detectBundledSdkDependency(root);
   loader.bundled_dependency = bundled
-    ? { name: bundled.name, version: bundled.version, resolved_version: bundled.resolved_version }
-    : null;
-  // A prerelease pin sorts strictly before its GA release, so it is never fed
-  // into version policy as a clean semver — the numeric triple would wrongly
-  // pass the release gate. It is recorded on sdk_loader and flagged instead.
-  const bundledPolicyVersion = bundled?.resolved_version && !bundled.prerelease
-    ? bundled.resolved_version
+    ? { name: bundled.name, version: bundled.version, resolved_version: bundled.resolved_version, floor_version: bundled.floor_version }
     : null;
+  // Policy asks whether every install meets the minimum, so only a floor the
+  // spec makes certain is evaluated. A prerelease pin sorts strictly before
+  // its GA release and has no released floor; nor does a range like <0.4.39
+  // or 0.4.41 || 0.4.18, whose extracted triple is not a version every
+  // install meets. Each is recorded on sdk_loader and flagged instead.
+  const bundledPolicyVersion = bundled?.floor_version || null;
   const versionEntries = [
     ...loader.versions.map((version) => ({ version, source: "loader" })),
     ...(bundledPolicyVersion && !loader.versions.includes(bundledPolicyVersion)
@@ -209,8 +213,20 @@ export function scanCampaignCartAppRoot({
       evidence: { name: bundled.name, version: bundled.version, resolved_version: bundled.resolved_version },
       next_action: "Pin the bundled campaign-cart dependency to a released version so version policy can be evaluated.",
     }));
+  } else if (bundled && !bundled.floor_version) {
+    findings.push(finding({
+      severity: "warning",
+      category: "standardization_warning",
+      code: "version.sdk_dependency_floor_unknown",
+      message: `Bundled Campaign Cart dependency ${bundled.name}@${bundled.version} does not fix a lowest version (an exact pin, or one ^, ~ or >= range on a released version); version policy cannot be evaluated against it.`,
+      confidence: "static_contract",
+      evidence: { name: bundled.name, version: bundled.version, resolved_version: bundled.resolved_version },
+      next_action: "Pin the bundled campaign-cart dependency exactly, or to a ^, ~ or >= range on a supported release, so version policy can be evaluated.",
+    }));
   }
-  const checkoutFields = inspectCheckoutFields(root, htmlFiles, contract, findings);
+  const checkoutFields = inspectCheckoutFields(root, htmlFiles, contract, findings, {
+    sdkVersionForFile: loaderSdkVersionResolver(loader, bundled),
+  });
   const payment = inspectPaymentSurfaces(root, htmlFiles, scriptFiles, findings);
   const dataNext = inspectDataNext(root, htmlFiles);
   const runtime = inspectRuntimeArtifacts(root, target, findings);
@@ -280,6 +296,8 @@ export function scanCampaignCartAppRoot({
 // when no such dependency is declared. A prerelease pin sorts strictly BEFORE
 // its GA release in semver, so `prerelease: true` tells the caller the pin
 // must NOT be evaluated against the release policy as if it were the release.
+// `floor_version` is the lowest version the spec allows when that is certain
+// (bundledSdkFloor), else null; it is the version policy evaluates.
 function detectBundledSdkDependency(root) {
   const pkg = readJson(join(root, "package.json"));
   const deps = { ...(pkg?.dependencies || {}), ...(pkg?.devDependencies || {}) };
@@ -291,12 +309,23 @@ function detectBundledSdkDependency(root) {
       name,
       version: spec,
       resolved_version: semver ? `${semver[1]}${semver[2] || ""}` : null,
+      floor_version: bundledSdkFloor(spec),
       prerelease: Boolean(semver && semver[2]),
     };
   }
   return null;
 }
 
+// The lowest SDK version a bundled dependency spec allows, when the spec makes
+// it certain: an exact pin (0.4.39, =0.4.39, v0.4.39) or one lower-bounded
+// comparator (^0.4.39, ~0.4.39, >=0.4.39), each on a released version. Any
+// other spec (<0.4.39, a ||, hyphen or x-range, a tag, a prerelease) gives
+// null: the version extracted from it is not a version every install meets.
+function bundledSdkFloor(spec) {
+  const match = /^\s*(?:\^|~|>=|=)?\s*v?(\S+)\s*$/.exec(String(spec ?? ""));
+  return match && isReleasedSdkVersion(match[1]) ? match[1] : null;
+}
+
 export function detectFrameworks(root) {
   const pkg = readJson(join(root, "package.json"));
   const deps = { ...(pkg?.dependencies || {}), ...(pkg?.devDependencies || {}) };
@@ -309,16 +338,13 @@ function collectLoaderReferences(root, files) {
   for (const file of files) {
     const raw = safeReadText(file);
     if (raw === null) continue;
-    const content = HTML_EXTENSIONS.has(extname(file).toLowerCase()) ? maskHtmlComments(raw) : raw;
-    for (const match of content.matchAll(withGlobal(LOADER_URL_PATTERN))) {
-      if (!LOADER_ARTIFACT_PATTERN.test(match[0])) continue;
-      const semver = match[1].match(/^v?(\d+\.\d+\.\d+)$/);
+    for (const entry of campaignCartArtifactReferences(raw, { isHtml: HTML_EXTENSIONS.has(extname(file).toLowerCase()) })) {
       references.push({
         path: relPath(root, file),
-        line: lineOf(content, match.index || 0),
-        url: match[0],
-        ref: match[1],
-        version: semver ? semver[1] : null,
+        line: entry.line,
+        url: entry.url,
+        ref: entry.ref,
+        version: entry.version,
       });
     }
   }
@@ -328,6 +354,73 @@ function collectLoaderReferences(root, files) {
   };
 }
 
+// Every file the scan walks under `root`: its own skipped directories (.git,
+// .campaign-runtime, _site, node_modules, qa-output, dist, build) left out.
+export const listCampaignCartScanFiles = (root) => listFiles(root);
+
+// The HTML and script files among them, the ones the scan reads.
+export function listCampaignCartSourceFiles(root) {
+  return listFiles(root).filter((file) => {
+    const ext = extname(file).toLowerCase();
+    return HTML_EXTENSIONS.has(ext) || SCRIPT_EXTENSIONS.has(ext);
+  });
+}
+
+export const isCampaignCartHtmlFile = (file) => HTML_EXTENSIONS.has(extname(file).toLowerCase());
+
+// Every Campaign Cart loader/dist reference in one file's text, in order, read
+// exactly as the scan reads it: HTML comments masked in an HTML file, and only
+// URLs that point at a loader or dist artifact. `ref` is the segment after
+// `campaign-cart@` and `version` its x.y.z when the ref is a plain semver pin
+// (with or without a leading v), else null. `url_start` is the URL's offset
+// and `ref_start`/`ref_end` the offsets of that segment in the file text; masking preserves offsets, so they
+// index the unmasked text too. `sdk repin` rewrites only that span.
+export function campaignCartArtifactReferences(text, { isHtml = false } = {}) {
+  const content = isHtml ? maskHtmlComments(text) : String(text ?? "");
+  const references = [];
+  for (const match of content.matchAll(LOADER_URL_INDEXED_PATTERN)) {
+    if (!LOADER_ARTIFACT_PATTERN.test(match[0])) continue;
+    const semver = match[1].match(/^v?(\d+\.\d+\.\d+)$/);
+    references.push({
+      line: lineOf(content, match.index || 0),
+      url: match[0],
+      ref: match[1],
+      version: semver ? semver[1] : null,
+      url_start: match.index,
+      ref_start: match.indices[1][0],
+      ref_end: match.indices[1][1],
+    });
+  }
+  return references;
+}
+
+// The SDK version each HTML file's checkout bindings run against, for the
+// version-gated field aliases. A file that loads the SDK itself uses its own
+// loader pin: one exact version, or unknown when its refs are unpinned or
+// disagree. Any other file (a partial, a page whose loader is injected) uses
+// the campaign's version: the lowest of the loader pins and the bundled
+// dependency's floor, or unknown when any loader ref is unpinned, the bundled
+// dependency has no certain floor, or nothing is discovered. Unknown is judged
+// as an earlier SDK (see inspectCheckoutFields).
+function loaderSdkVersionResolver(loader, bundled) {
+  const byFile = new Map();
+  for (const ref of loader.references) {
+    if (!byFile.has(ref.path)) byFile.set(ref.path, []);
+    byFile.get(ref.path).push(ref.version);
+  }
+  const floor = bundled?.floor_version || null;
+  const versions = [...loader.versions, ...(floor ? [floor] : [])];
+  const campaign = loader.references.some((ref) => !ref.version) || (bundled && !floor) || !versions.length
+    ? null
+    : { version: [...versions].sort(compareVersions)[0], source: "campaign" };
+  return (path) => {
+    const own = byFile.get(path);
+    if (!own) return campaign;
+    const versions = unique(own);
+    return own.every(Boolean) && versions.length === 1 ? { version: versions[0], source: "loader" } : null;
+  };
+}
+
 export function evaluateVersionPolicy(versionEntries, policy, findings) {
   const evaluations = versionEntries.map(({ version, source }) => ({
     version,
@@ -364,7 +457,15 @@ export function evaluateVersionPolicy(versionEntries, policy, findings) {
   };
 }
 
-export function inspectCheckoutFields(root, htmlFiles, contract, findings) {
+// `sdkVersionForFile(relativePath)` returns the { version, source } a file's
+// bindings run against, or null when it is unknown. A version-gated alias
+// (contract version_gated_aliases) is supported only on an exact SDK release
+// at or after its since-version; on an earlier or unknown version it is
+// classified as the contract classifies it without the gate (a stale alias,
+// or unknown). Unknown is the conservative side: the canonical name works on
+// every version, and accepting the alias there could pass a field that never
+// reaches the order.
+export function inspectCheckoutFields(root, htmlFiles, contract, findings, { sdkVersionForFile = null } = {}) {
   const bindings = [];
   const attributes = contract?.binding_attributes || ["data-next-checkout-field", "os-checkout-field"];
   const attributePattern = new RegExp(`\\b(${attributes.map(escapeRegExp).join("|")})\\s*=\\s*(["'])([^"']*)\\2`, "g");
@@ -372,17 +473,22 @@ export function inspectCheckoutFields(root, htmlFiles, contract, findings) {
     const raw = safeReadText(file);
     if (raw === null) continue;
     const content = maskHtmlComments(raw);
+    const path = relPath(root, file);
+    const sdk = (typeof sdkVersionForFile === "function" ? sdkVersionForFile(path) : null) || { version: null, source: null };
     for (const match of content.matchAll(attributePattern)) {
       const value = match[3].trim();
-      const verdict = classifyFieldBinding(value, contract);
+      const verdict = classifyFieldBinding(value, contract, sdk.version);
       bindings.push({
         attribute: match[1],
         value,
-        path: relPath(root, file),
+        path,
         line: lineOf(content, match.index || 0),
         supported: verdict.classification === "supported",
         classification: verdict.classification,
         canonical: verdict.canonical,
+        since: verdict.since,
+        sdk_version: sdk.version,
+        sdk_version_source: sdk.source,
       });
     }
   }
@@ -391,16 +497,28 @@ export function inspectCheckoutFields(root, htmlFiles, contract, findings) {
   const unknown = bindings.filter((entry) => entry.classification === "unknown");
 
   if (unsupported.length) {
+    const gated = unsupported.filter((entry) => entry.since);
+    const gatedNote = gated.length
+      ? ` The SDK consumes ${unique(gated.map((entry) => `${entry.value} only from ${entry.since}`)).join(", ")}; these bindings run on SDK ${unique(gated.map((entry) => entry.sdk_version || "of unknown version (judged as an earlier SDK)")).join(", ")}.`
+      : "";
     findings.push(finding({
       severity: "blocker",
       category: "standardization_blocker",
       code: "checkout.unsupported_field_binding",
-      message: `${unsupported.length} checkout field binding(s) use stale aliases the Campaign Cart SDK does not consume (contract: ${contract?.schema_version || "unknown"}).`,
+      message: `${unsupported.length} checkout field binding(s) use stale aliases the Campaign Cart SDK does not consume (contract: ${contract?.schema_version || "unknown"}).${gatedNote}`,
       confidence: "static_contract",
       evidence: dedupeBy(unsupported, (entry) => entry.value)
-        .map((entry) => ({ value: entry.value, canonical: entry.canonical, path: entry.path, line: entry.line }))
+        .map((entry) => ({
+          value: entry.value,
+          canonical: entry.canonical,
+          path: entry.path,
+          line: entry.line,
+          ...(entry.since ? { since: entry.since, sdk_version: entry.sdk_version } : {}),
+        }))
         .slice(0, MAX_SAMPLE_COUNT),
-      next_action: "Rewrite each stale alias to its canonical Campaign Cart field name, then prove checkout binding in browser QA.",
+      next_action: gated.length
+        ? "Rewrite each stale alias to its canonical Campaign Cart field name (for an alias with a since-version in the evidence, pinning the SDK at or after that version also works), then prove checkout binding in browser QA."
+        : "Rewrite each stale alias to its canonical Campaign Cart field name, then prove checkout binding in browser QA.",
     }));
   }
   if (unknown.length) {
@@ -411,7 +529,7 @@ export function inspectCheckoutFields(root, htmlFiles, contract, findings) {
       message: `${unknown.length} checkout field binding(s) are outside the known Campaign Cart field contract.`,
       confidence: "static_inference",
       evidence: dedupeBy(unknown, (entry) => entry.value)
-        .map((entry) => ({ value: entry.value, path: entry.path, line: entry.line }))
+        .map((entry) => ({ value: entry.value, path: entry.path, line: entry.line, ...(entry.since ? { since: entry.since, sdk_version: entry.sdk_version } : {}) }))
         .slice(0, MAX_SAMPLE_COUNT),
       next_action: "Confirm the field against the Campaign Cart SDK before treating it as supported or repairing it.",
     }));
@@ -425,10 +543,11 @@ export function inspectCheckoutFields(root, htmlFiles, contract, findings) {
   };
 }
 
-function classifyFieldBinding(value, contract) {
-  if (!value) return { classification: "unknown", canonical: null };
+function classifyFieldBinding(value, contract, sdkVersion = null) {
+  if (!value) return { classification: "unknown", canonical: null, since: null };
   const canonicalFields = new Set(contract?.canonical_fields || []);
   const acceptedAliases = contract?.accepted_aliases || {};
+  const gatedAliases = contract?.version_gated_aliases || {};
   const staleAliases = contract?.stale_aliases || {};
   const prefixes = contract?.prefixes || [];
 
@@ -441,12 +560,15 @@ function classifyFieldBinding(value, contract) {
       break;
     }
   }
-  if (canonicalFields.has(base)) return { classification: "supported", canonical: null };
-  if (typeof acceptedAliases[base] === "string") return { classification: "supported", canonical: null };
+  if (canonicalFields.has(base)) return { classification: "supported", canonical: null, since: null };
+  if (typeof acceptedAliases[base] === "string") return { classification: "supported", canonical: null, since: null };
+  const gated = Object.hasOwn(gatedAliases, base) ? gatedAliases[base] : null;
+  const since = typeof gated?.since === "string" ? gated.since : null;
+  if (since && sdkVersionAtLeast(sdkVersion, since)) return { classification: "supported", canonical: null, since };
   if (typeof staleAliases[base] === "string") {
-    return { classification: "stale_alias", canonical: `${prefix}${staleAliases[base]}` };
+    return { classification: "stale_alias", canonical: `${prefix}${staleAliases[base]}`, since };
   }
-  return { classification: "unknown", canonical: null };
+  return { classification: "unknown", canonical: null, since };
 }
 
 function inspectPaymentSurfaces(root, htmlFiles, scriptFiles, findings) {

package/src/cli.mjs

@@ -318,9 +318,10 @@ Usage:
                      [--allow-uncertified-template "<reason>"] [--order-path-depth <off|common|full>]
                      [--deploy-target <target>] [--preview-url <url>] [--production-url <url>] [--no-run-session] [--force]   # intake alias for prepare-build + doctor
   campaigns-os doctor --packet <campaign-runtime.build.json> [--context <json>] [--report <json>] [--strip-paths] [--write] [--no-write] [--doctor-out <path>] [--proxy-base <url>] [--no-live-refs] [--json]   # inspection by default; --doctor-out requires --write; --no-write wins. When the packet's built _site/<route>/ exists and a public Campaigns API key resolves (packet, its local CampaignSpec, or the declared campaign-key env var), doctor makes one read-only GET of {proxy-base}/api/campaign under X-Campaign-Key to check each built page's shipping and package refs against the live campaign; --proxy-base overrides the canonical proxy (https, or a loopback host over http). --no-live-refs skips the read and records not_run with reason disabled. No key, no built page, or a failed read records derived.live_campaign_refs as not_run with its reason. Only doctor and qa run make this read; other commands that run doctor record not_read
-  campaigns-os doctor --built <page-kit-target-repo> --family <family> [--slug <slug>] [--base-url <url>] [--emit-packet [path]] [--json]   # L7: doctor a built _site/ with no Build Packet
+  campaigns-os doctor --built <page-kit-target-repo> --family <family> [--slug <slug>] [--base-url <url>] [--emit-packet [path]] [--json]   # L7: doctor a built _site/ with no Build Packet. Reads the local files only: --base-url is not fetched, it fills deploy.preview_url in the minimal packet (check served pages with qa run --site)
   campaigns-os bundle check --packet <campaign-runtime.build.json> [--require-qa] [--json]   # validate the canonical migration/readback JSON bundle; never substitutes markdown
   campaigns-os sdk storage-check --target <git-root> --target-sdk <x.y.z> --manifest <SDK-manifest.json> --scope <dir,file> [--exclude <dir,file>] [--json]
+  campaigns-os sdk repin --target <static-campaign-repo> [--target-sdk <x.y.z>] [--apply] [--json]   # rewrite the version segment of each semver-pinned Campaign Cart loader.js / campaign-cart.css URL (the references standardize's scan finds, @vX.Y.Z or @X.Y.Z) below the target, default the SDK support policy's preferred_minimum; @latest, @main, commit and prerelease refs, and pins at or above the target, are reported and left alone. Preview by default (path:line, old -> new URL, nothing written); --apply writes the files and a change record at .campaign-runtime/sdk-repin.json (campaigns-os-sdk-repin/v0: files touched, reference count, from/to versions) a Run Record can cite. A repo with _data/campaigns.json is refused (exit 2): page-kit sync owns that pin
   campaigns-os standardize --target <campaign-repo> [--family <family>] [--slug <slug>] [--sdk-support-policy <path.json>] [--field-contract <path.json>] [--no-doctor] [--json]
   campaigns-os theme inspect --packet <campaign-runtime.build.json> [--context <json>] [--theme-policy <inspect_only|auto|off>] [--json]
   campaigns-os theme generate --packet <campaign-runtime.build.json> [--context <json>] [--out-dir <dir>] [--force] [--json]
@@ -337,7 +338,7 @@ Usage:
   campaigns-os record build --packet <campaign-runtime.build.json> [--build-environment <development|production>] [--context <json>] [--report <json>] [--dry-run] [--json]   # after page-kit build (--build-environment records stages.assembly.evidence.build_environment; local proof mode records development): stages.assembly completed with build_fingerprint = doctor's derived.build_output_fingerprint.value (and the Design Source Package material fingerprint when the report has one); stages.polish becomes required unless its evidence is bound to this exact output
   campaigns-os record polish --packet <campaign-runtime.build.json> --evidence <polish-evidence.json> [--context <json>] [--report <json>] [--dry-run] [--json]   # after polish capture: stages.polish from the file's status (completed, completed_with_warnings, blocked with blockers, or skipped with skip_reason), evidence and optional repair_loop_defect, bound to doctor's current fingerprint; a completed status is refused, writing nothing, unless the polish gate doctor evaluates would pass. --dry-run runs every check and writes nothing
   campaigns-os record theme --packet <campaign-runtime.build.json> [--context <json>] [--report <json>] [--dry-run] [--json]   # after the brand layer is linked and build is recorded: report.theme becomes applied with load_order after-next-core, css_path, commerce_pages and per-page evidence, only when each built commerce page that loads next-core.css loads brand-theme.css (or checkout-brand.css) after it and at least one does; a page loading neither is left out as the design's own markup; refused, writing nothing, otherwise. --dry-run runs every check and writes nothing
-  campaigns-os record deploy --packet <campaign-runtime.build.json> --base-url <served url> [--context <json>] [--report <json>] [--dry-run] [--json]   # a local preview (deploy.target local-serve) after polish is recorded: GETs every built page under the loopback URL (the campaign route root), then records deploy.preview_url on the packet and stages.deploy completed with the URL in outputs; refused, writing nothing, when the URL is not loopback or not the route root, a page does not answer 2xx, the build changed since it was recorded, or the theme gate is blocked. --dry-run runs every check, the requests included, and writes nothing
+  campaigns-os record deploy --packet <campaign-runtime.build.json> --base-url <served url> [--context <json>] [--report <json>] [--dry-run] [--json]   # a local preview (deploy.target local-serve) after polish is recorded: GETs every built page under the loopback URL (the campaign route root), then records deploy.preview_url on the packet and stages.deploy completed with the URL in outputs and the build fingerprint it probed (a later record build of other output makes deploy required again); refused, writing nothing, when the URL is not loopback or not the route root, a page does not answer 2xx, the build changed since it was recorded, or the theme gate is blocked. --dry-run runs every check, the requests included, and writes nothing
   campaigns-os readback <target-repo-root> [--json] [--packet <path>] [--doctor <path>] [--context <path>] [--report <path>] [--qa-verdict <path>] [--findings <path>]   # read-only projection of one run's emitted artifacts (packet, doctor output, build context, assembly report, QA verdict, findings export): artifact states, per-artifact freshness against the checkout's HEAD reflog, doctor warning grouping, skip cascades and cross-artifact divergences. Writes nothing, starts no process, touches no network, and records no lifecycle entry; --json emits one campaigns-os-readback/v2 object (docs/readback.md). Exit 2 for a missing target root or a Build Packet set freshness cannot single out.
   campaigns-os readback --example [--json]                                # project the bundled synthetic sample; freshness is not computable for it by design
   campaigns-os validate-assembly-report --report <json> [--json]
@@ -1052,7 +1053,25 @@ async function dispatch(command, args, { recorder = NOOP_RECORDER, ambient = nul
   }
 
   if (command === "sdk") {
-    if (args._[1] !== "storage-check" || args._.length !== 2) throw refused("Use: campaigns-os sdk storage-check --target <git-root> --target-sdk <x.y.z> --manifest <SDK-manifest.json> --scope <dir,file> [--exclude <dir,file>] [--json].");
+    if (args._[1] === "repin" && args._.length === 2) {
+      const known = new Set(["_", "target", "target-sdk", "apply", "json"]);
+      for (const key of Object.keys(args)) if (!known.has(key)) throw refused(`Unknown SDK repin flag: --${key}`);
+      for (const flag of ["apply", "json"]) {
+        if (args[flag] !== undefined && args[flag] !== true) throw refused(`--${flag} is a boolean flag and takes no value.`);
+      }
+      const { runSdkRepin, formatSdkRepinReport, isRepinTargetVersion } = await import("./sdk-repin.mjs");
+      const targetSdk = args["target-sdk"] === undefined ? null : requireArg(args, "target-sdk");
+      if (targetSdk !== null && !isRepinTargetVersion(targetSdk)) throw refused(`--target-sdk ${targetSdk} is not a released SDK version (x.y.z).`);
+      const result = runSdkRepin({
+        targetRepo: requireArg(args, "target"),
+        targetSdk,
+        apply: args.apply === true,
+      });
+      console.log(args.json ? JSON.stringify(result, null, 2) : formatSdkRepinReport(result));
+      process.exitCode = result.ok ? 0 : 2;
+      return;
+    }
+    if (args._[1] !== "storage-check" || args._.length !== 2) throw refused("Use: campaigns-os sdk storage-check --target <git-root> --target-sdk <x.y.z> --manifest <SDK-manifest.json> --scope <dir,file> [--exclude <dir,file>] [--json], or campaigns-os sdk repin --target <static-campaign-repo> [--target-sdk <x.y.z>] [--apply] [--json].");
     const known = new Set(["_", "target", "target-sdk", "manifest", "scope", "exclude", "json"]);
     if (args.json !== undefined && args.json !== true) throw refused("--json is a boolean flag and takes no value.");
     for (const key of Object.keys(args)) if (!known.has(key)) throw refused(`Unknown SDK storage-check flag: --${key}`);

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

@@ -108,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 {
@@ -2522,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") {
@@ -2553,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

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/invocation.mjs

@@ -54,7 +54,7 @@ const COMMANDS = frozen({
   logout: { class: "auth" },
   demo: { class: "inline" },
   tooling: { subcommands: ["diagnose", "setup", "status"] },
-  sdk: { subcommands: ["storage-check"] },
+  sdk: { subcommands: ["repin", "storage-check"] },
   readback: { class: "projection" },
   start: { sweepRoot: "target" },
   "prepare-build": { sweepRoot: "target" },
@@ -86,6 +86,8 @@ const SUBCOMMAND_OVERRIDES = frozen({
   "tooling diagnose": { class: "inline" },
   "tooling setup": { class: "inline" },
   "sdk storage-check": { class: "inspection" },
+  // Preview by default: only --apply writes, so only --apply journals.
+  "sdk repin": { journalExemptWhen: { given: "target", unlessBare: "apply" } },
   "theme waive": { dryRun: true },
   "checkpoint accept": { dryRun: true },
   "checkpoint waive": { dryRun: true },

package/src/progress-node.mjs

@@ -96,7 +96,7 @@ export function projectProgressObservation({workspace,context,report,doctor,cont
 }
 function lock(dir,fn,{budgetMs=1500}={}) {
   const lockPath=join(dir,'.allocation-lock');
-  return withDirectoryLock(lockPath,fn,{budgetMs,unavailable:()=>Object.assign(new Error('progress.lock_unavailable'),{lockPath})});
+  return withDirectoryLock(lockPath,fn,{budgetMs,unavailable:(error)=>Object.assign(new Error('progress.lock_unavailable'),{lockPath,code:error?.code,obstruction:error?.obstruction})});
 }
 export async function persistProgressObservation(observation,{dir,now=()=>new Date(),historyLimit=32}={}) {
   mkdirSync(dir,{recursive:true,mode:0o700});
@@ -164,7 +164,8 @@ export async function observeProgress(args,continuation,{qaResult=null,packageVe
     if(remit.state==='failed')warn('[campaigns-os] Progress delivery pending; the local observation is retained. Lifecycle result is unchanged.');
     return {...remit,snapshot_id:snapshot.snapshot_id,reused};
   } catch(error) {
-    if(error?.message==='progress.lock_unavailable')warn(`[campaigns-os] Progress allocation lock occupied${error.lockPath?` at ${error.lockPath}`:''}; wait for the current writer. If it stays occupied (an abandoned, ownerless or interrupted lock), stop all campaigns-os writers for this target, then remove that lock directory (docs/progress-snapshots.md). Lifecycle result is unchanged.`);
+    if(error?.message==='progress.lock_unavailable'&&error.obstruction)warn(`[campaigns-os] Progress allocation lock path ${error.lockPath} is occupied by ${error.obstruction}; it is never removed automatically. Move it out of the way. Lifecycle result is unchanged.`);
+    else if(error?.message==='progress.lock_unavailable')warn(`[campaigns-os] Progress allocation lock occupied${error.lockPath?` at ${error.lockPath}`:''}; wait for the current writer. If it stays occupied (an abandoned, ownerless or interrupted lock), stop all campaigns-os writers for this target, then remove that lock directory (docs/progress-snapshots.md). Lifecycle result is unchanged.`);
     else warn('[campaigns-os] Progress observation unavailable; lifecycle result is unchanged.');
     return {state:'failed',reason:'capture_unavailable'};
   }