@nextcommerce/campaigns-os 1.53.0 → 1.55.0

package/src/brand-theme.mjs

@@ -256,8 +256,11 @@ function inferDesignIntentTokens(content, rootTokens = {}) {
     const lower = name.toLowerCase();
     if (isTargetContractToken(lower)) continue;
     const parts = tokenNameParts(lower);
+    const decorativeName = hasTokenPart(parts, DECORATIVE_NAME_PARTS);
+    const namedRole = hasTokenPart(parts, EXPLICIT_BRAND_PARTS);
     const ctaName = hasTokenPart(parts, ["cta", "button", "btn"]);
-    if (!ctaName && (hasTokenSequence(parts, ["brand"], ["primary", "main"]) || (hasTokenPart(parts, ["primary"]) && !hasTokenPart(parts, ["text", "foreground", "surface", "background", "bg", "border", "outline"])))) {
+    if (!ctaName && (!decorativeName || namedRole)
+      && (hasTokenSequence(parts, ["brand"], ["primary", "main"]) || (hasTokenPart(parts, ["primary"]) && !hasTokenPart(parts, ["text", "foreground", "surface", "background", "bg", "border", "outline"])))) {
       addToken("--brand-primary", color);
     }
     if (ctaName) {
@@ -281,7 +284,7 @@ function inferDesignIntentTokens(content, rootTokens = {}) {
     if (hasTokenPart(parts, ["rating", "star", "review"])) addToken("--rating-star", color);
   }
 
-  const rulePattern = /([^{}]+)\{([^{}]+)\}/g;
+  const rulePattern = /([^{};]+)\{([^{}]+)\}/g;
   for (const match of stripCssComments(content).matchAll(rulePattern)) {
     const selector = match[1] || "";
     for (const declaration of match[2].split(";")) {
@@ -291,9 +294,11 @@ function inferDesignIntentTokens(content, rootTokens = {}) {
       const color = resolveDeclarationColor(rawValue, rootTokens);
       if (!color) continue;
       if (["background", "background-color"].includes(name)) {
-        if (/(header|nav|announcement|brand|hero)/i.test(selector) && isStrongBrandColor(color)) {
+        if (hasPrimarySelectorRole(selector)
+          && isStrongBrandColor(color)) {
           addToken("--brand-primary", color);
-        } else if (isCtaLikeSelector(selector) && isStrongBrandColor(color)) {
+        }
+        if (isCtaLikeSelector(eligibleSelectorText(selector)) && isStrongBrandColor(color)) {
           addToken("--button-primary-bg", color);
           addToken("--brand-cta", color);
           addToken("--brand-accent", color);
@@ -319,6 +324,32 @@ function inferDesignIntentTokens(content, rootTokens = {}) {
   return tokens;
 }
 
+const DECORATIVE_NAME_PARTS = ["sale", "discount", "badge", "rating", "star", "strike", "border", "announcement"];
+const EXPLICIT_BRAND_PARTS = ["brand", "primary", "cta", "button", "btn"];
+
+function selectorSubjectParts(compound) {
+  return [...compound.classes, ...compound.ids].flatMap(tokenNameParts);
+}
+
+function subjectHasDecorativeRole(compound) {
+  // A button or submit input is a control whatever its classes say.
+  if (compound.type === "button") return false;
+  if (compound.type === "input" && compound.attributes.some((attribute) => /^\s*type\s*=\s*(["']?)submit\1\s*(?:i\s*)?$/i.test(attribute))) return false;
+  const parts = selectorSubjectParts(compound);
+  return hasTokenPart(parts, DECORATIVE_NAME_PARTS) && !hasTokenPart(parts, EXPLICIT_BRAND_PARTS);
+}
+
+function eligibleSelectorText(selector) {
+  const compounds = rightmostCompounds(selector);
+  if (!compounds) return selector;
+  return compounds.filter((compound) => !subjectHasDecorativeRole(compound))
+    .map((compound) => compound.selectorText).join(", ");
+}
+
+function hasPrimarySelectorRole(selector) {
+  return /(header|nav|announcement|brand|hero)/i.test(eligibleSelectorText(selector));
+}
+
 function isCtaLikeSelector(selector) {
   return /(?:^|[.#\s:_-])(?:cta|button|btn|submit|cart|buy|order)(?:$|[.#\s:_-])/i.test(String(selector || ""));
 }
@@ -337,11 +368,12 @@ const SELECTOR_ARGUMENT_PSEUDOS = new Set(["not", "is", "where", "has"]);
 function rightmostCompounds(selectorList) {
   const text = String(selectorList || "");
   const compounds = [];
-  const fresh = () => ({ type: null, classes: [], attributes: [], pseudos: [] });
-  const isEmpty = (compound) => !compound.type && !compound.classes.length && !compound.attributes.length && !compound.pseudos.length;
+  const fresh = () => ({ type: null, classes: [], ids: [], attributes: [], pseudos: [] });
+  const isEmpty = (compound) => !compound.type && !compound.classes.length && !compound.ids.length && !compound.attributes.length && !compound.pseudos.length;
   let current = fresh();
   let afterCombinator = false;
   let i = 0;
+  let selectorStart = 0;
   const readName = () => {
     const start = i;
     while (i < text.length && (/[A-Za-z0-9_\- -￿]/.test(text[i]) || text[i] === "\\")) i += text[i] === "\\" ? 2 : 1;
@@ -371,10 +403,12 @@ function rightmostCompounds(selectorList) {
     if (/[\s>+~]/.test(ch)) { afterCombinator = true; i += 1; continue; }
     if (ch === ",") {
       if (isEmpty(current)) return null;
+      current.selectorText = text.slice(selectorStart, i);
       compounds.push(current);
       current = fresh();
       afterCombinator = false;
       i += 1;
+      selectorStart = i;
       continue;
     }
     if (afterCombinator) { current = fresh(); afterCombinator = false; }
@@ -383,6 +417,7 @@ function rightmostCompounds(selectorList) {
       const name = readName();
       if (!name) return null;
       if (ch === ".") current.classes.push(name);
+      else current.ids.push(name);
     } else if (ch === "[") {
       const attribute = readGroup("[", "]");
       if (attribute === null) return null;
@@ -404,6 +439,7 @@ function rightmostCompounds(selectorList) {
     }
   }
   if (isEmpty(current)) return null;
+  current.selectorText = text.slice(selectorStart);
   compounds.push(current);
   return compounds;
 }
@@ -469,7 +505,7 @@ function splitDeclarations(body) {
 // declaredCtaForegroundValue.
 function collectCtaLabelRules(content, rootTokens = {}) {
   const rules = [];
-  for (const match of stripCssComments(content).matchAll(/([^{}]+)\{([^{}]+)\}/g)) {
+  for (const match of stripCssComments(content).matchAll(/([^{};]+)\{([^{}]+)\}/g)) {
     if (!isButtonSelector(match[1])) continue;
     let color = null;
     let background = null;
@@ -975,7 +1011,7 @@ function mapTokens(tokens, targetTokens, { rootTokens = {}, ctaLabelRules = [] }
   const hasCta = mappings.some((mapping) => mapping.target === "--brand--color--cta-primary");
   if (!hasCta && isNonEmptyString(tokens["--brand-accent"])) {
     addMapping("--brand-accent", "--brand--color--cta-primary", tokens["--brand-accent"].trim(), "medium", { method: "cta-fallback-from-brand-accent" });
-    warnings.push(issue("theme.cta.fallback", "No explicit CTA token was found; using --brand-accent as --brand--color--cta-primary."));
+    warnings.push(issue("theme.cta.fallback", "No explicit CTA token or button background was found; using --brand-accent as --brand--color--cta-primary. This may be a rating or decorative accent; confirm the CTA colour against the design."));
   } else if (!hasCta && isNonEmptyString(tokens["--brand-primary"])) {
     addMapping("--brand-primary", "--brand--color--cta-primary", tokens["--brand-primary"].trim(), "medium", { method: "cta-fallback-from-brand-primary" });
     warnings.push(issue("theme.cta.fallback", "No explicit CTA token was found; using --brand-primary as --brand--color--cta-primary."));

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/campaign-identity.mjs

@@ -45,6 +45,7 @@ export const CAMPAIGN_IDENTITY = "built_output.campaign_identity";
 // Finding kinds, each with its own issue code under the gate id.
 export const CAMPAIGN_IDENTITY_KINDS = Object.freeze({
   api_key_drift: `${CAMPAIGN_IDENTITY}.api_key_drift`,
+  api_key_mismatch: `${CAMPAIGN_IDENTITY}.api_key_mismatch`,
   funnel_drift: `${CAMPAIGN_IDENTITY}.funnel_drift`,
   funnel_missing: `${CAMPAIGN_IDENTITY}.funnel_missing`,
   attribution_drift: `${CAMPAIGN_IDENTITY}.attribution_drift`,
@@ -270,7 +271,7 @@ function gateBase(subject) {
  *   file?: string|null, content: string, spec_page?: boolean,
  *   scripts?: Array<{ src: string, file?: string|null, content: string }> }> }} input
  */
-export function evaluateCampaignIdentity({ subject, pages = [] } = {}) {
+export function evaluateCampaignIdentity({ subject, pages = [], expectedApiKey = null } = {}) {
   const all = Array.isArray(pages) ? pages : [];
   const skipped = all
     .filter((page) => isParkedPage(page.route ?? page.file ?? page.page_id))
@@ -298,7 +299,7 @@ export function evaluateCampaignIdentity({ subject, pages = [] } = {}) {
   //    value. Meta and config are compared together on purpose: a page whose
   //    meta names one campaign while its config.js names another is drift
   //    inside a single page, and the SDK's precedence rule only hides it.
-  const keyObservations = identities.flatMap((identity) => identity.api_keys.map((key) => ({ page_id: identity.page_id, ...key })));
+  const keyObservations = identities.flatMap((identity) => identity.api_keys.map((key) => ({ page_id: identity.page_id, page_file: identity.file || identity.page_id, ...key })));
   const firstKey = keyObservations[0] || null;
   for (const observation of keyObservations.slice(1)) {
     if (observation.value === firstKey.value) continue;
@@ -312,6 +313,32 @@ export function evaluateCampaignIdentity({ subject, pages = [] } = {}) {
     });
     break; // one finding per kind names the first pair; the rest follow from the same edit
   }
+  const wrongKeys = new Map();
+  if (expectedApiKey?.key) {
+    for (const observation of keyObservations) {
+      if (observation.value === expectedApiKey.key) continue;
+      if (!wrongKeys.has(observation.value)) wrongKeys.set(observation.value, new Map());
+      const sources = wrongKeys.get(observation.value);
+      const sourceId = `${observation.where}\u0000${observation.source}`;
+      if (!sources.has(sourceId)) sources.set(sourceId, { file: observation.where, source: observation.source, pages: new Set() });
+      sources.get(sourceId).pages.add(observation.page_file);
+    }
+  }
+  const wrongSourceFiles = [...new Set([...wrongKeys.values()].flatMap((sources) => [...sources.values()].map((source) => source.file)))];
+  if (wrongKeys.size) {
+    const firstWrong = keyObservations.find((observation) => observation.value !== expectedApiKey.key);
+    const wrongDetails = [...wrongKeys].map(([value, sources]) =>
+      `${[...sources.values()].map(({ file, source, pages }) => `${file} (${source}; used by ${[...pages].join(", ")})`).join(" and ")} has ${quote(value)}`,
+    ).join("; ");
+    findings.push({
+      kind: "api_key_mismatch",
+      code: CAMPAIGN_IDENTITY_KINDS.api_key_mismatch,
+      a: { page_id: null, file: expectedApiKey.source, value: expectedApiKey.key },
+      b: { page_id: firstWrong.page_id, file: firstWrong.where, source: firstWrong.source, value: firstWrong.value },
+      evidence: `Built API key in ${wrongDetails} differs from the Campaigns API key in ${expectedApiKey.source}.`,
+      message: `Built API key in ${wrongDetails} differs from the Campaigns API key ${quote(expectedApiKey.key)} in ${expectedApiKey.source}. Replace the built key in the named source with the campaign's own key, then rebuild.`,
+    });
+  }
 
   // 2. next-funnel: one value across pages, and present wherever the SDK is
   //    bootstrapped (a page that declares next-page-type is SDK-bound).
@@ -422,7 +449,7 @@ export function evaluateCampaignIdentity({ subject, pages = [] } = {}) {
     // Short on purpose; the per-edit prose is findings[].message, which is
     // what each doctor error carries. A reason that concatenates them is
     // truncated by every single-line renderer.
-    reason: `${findings.length} campaign identity drift finding(s) across ${scanned.length} built page(s) (${[...new Set(findings.map((finding) => finding.kind))].join(", ")}); see findings[] for the two files and two values of each.`,
+    reason: `${findings.length} campaign identity ${findings.every((finding) => finding.kind === "api_key_mismatch") ? "API key mismatch" : "drift"} finding(s) across ${scanned.length} built page(s) (${[...new Set(findings.map((finding) => finding.kind))].join(", ")}); see findings[] for the sources and values to repair.`,
     findings,
     pages_scanned: scanned.length,
     pages_skipped: skipped,
@@ -432,7 +459,9 @@ export function evaluateCampaignIdentity({ subject, pages = [] } = {}) {
         id: "repair_identity",
         kind: "edit",
         command: null,
-        description: `Make every page name the same campaign: ${findings.map((finding) => `${finding.b?.file || finding.a.file} (${finding.kind.replace(/_/g, " ")})`).join("; ")}. Not waivable: two campaign identities on one funnel cannot both be intended.`,
+        description: findings.map((finding) => finding.kind === "api_key_mismatch"
+          ? `Replace the built key in ${wrongSourceFiles.join(", ")} with the campaign's key, then rebuild.`
+          : `Make every page name the same campaign: ${finding.b?.file || finding.a.file} (${finding.kind.replace(/_/g, " ")}).`).join(" "),
       },
     ],
   };