@nextcommerce/campaigns-os 1.61.0 → 1.62.0

package/src/commercial-journey.mjs

@@ -109,7 +109,11 @@ function selectedShipping(page) {
 // `is_upsell: true` on a non-upsell page. Every consumer that must
 // tell a bump from a main selector row (parity scenarios, bump deltas, the QA
 // selector-tier planner, `next`'s order-bump QA command) reads this, so a
-// marker change lands in one place.
+// marker change lands in one place. The page-type half of the contract
+// (campaigns-os#710, stated on the schema's pagePackage.is_upsell) sits with
+// the callers: on an upsell or downsell page every row is the page's offer,
+// so planScenarios puts all of them in mainRows, and the tier and bump readers
+// are only given the select, checkout_step and checkout pages of a path.
 export function isBumpRow(row) {
   return Boolean(row?.is_order_bump || row?.is_upsell);
 }
@@ -262,7 +266,9 @@ function descriptor(page, mapDoc, role, lines, options = {}) {
   const body = { lines: lines.map((line) => ({ ...line })) };
   if (array(options.vouchers).length) body.vouchers = [...options.vouchers];
 
-  const currency = mapDoc?.campaign?.currency ?? mapDoc?.currency;
+  // A run currency (`qa run --currency`) prices every scenario in that
+  // currency; otherwise the Map's campaign currency is asked for.
+  const currency = present(options.currency) ? options.currency : mapDoc?.campaign?.currency ?? mapDoc?.currency;
   if (present(currency)) body.currency = String(currency);
   if (present(options.shipping_method)) body.shipping_method = options.shipping_method;
   return { ...result, body };
@@ -270,6 +276,8 @@ function descriptor(page, mapDoc, role, lines, options = {}) {
 
 /**
  * Convert one authored page into deterministic calculate request descriptors.
+ * `options.currency`, when given, is the currency every request asks for in
+ * place of the Map's campaign currency.
  */
 export function planScenarios(page, mapDoc = {}, options = {}) {
   const rows = array(page?.packages);
@@ -310,7 +318,12 @@ export function planScenarios(page, mapDoc = {}, options = {}) {
     !pageIsUpsell || !carriedVouchers.includes(String(value.offer_code)),
   );
 
-  const shared = { attached_offers: attached, known_offer_codes: knownOfferCodes, page_rows: rows };
+  const shared = {
+    attached_offers: attached,
+    known_offer_codes: knownOfferCodes,
+    page_rows: rows,
+    ...(present(options.currency) ? { currency: String(options.currency) } : {}),
+  };
   const plan = [];
   const add = (value) => {
     if (plan.length >= maxScenarios) throw new CommercialJourneyLimitError("scenarios", maxScenarios);

package/src/commercial-parity.mjs

@@ -714,10 +714,14 @@ function findingPage(capture, page) {
 
 /**
  * Pure, Exact-only diff. Unresolved, Stale, unbound, and malformed facts are
- * deliberately silent.
+ * deliberately silent. `options.unresolvedMoneyClaims`, a reason code, skips
+ * the price and recurrence comparisons: the captured amounts are in another
+ * currency than the calculated totals, so neither a match nor a mismatch
+ * means anything.
  */
-export function diffCommercialParity(capturesValue, journey) {
+export function diffCommercialParity(capturesValue, journey, options = {}) {
   const captures = partitionCaptures(capturesValue).valid;
+  const compareMoney = !present(options.unresolvedMoneyClaims);
   const findings = [];
 
   captures.forEach((capture) => {
@@ -725,7 +729,7 @@ export function diffCommercialParity(capturesValue, journey) {
     if (!page) return;
     const pageId = findingPage(capture, page);
     const source = present(capture.url) ? { url: String(capture.url) } : {};
-    const representative = exactMoneyFact(page.representative_total);
+    const representative = compareMoney ? exactMoneyFact(page.representative_total) : null;
     if (representative) {
       priceComparisonClaims(capture, page).compared.forEach((claim) => {
         const claimed = normalizeMoney(claim?.value);
@@ -741,7 +745,7 @@ export function diffCommercialParity(capturesValue, journey) {
       });
     }
 
-    recurrenceComparisonClaims(capture, page).compared.forEach(({ claim, truth }) => {
+    (compareMoney ? recurrenceComparisonClaims(capture, page).compared : []).forEach(({ claim, truth }) => {
       const packageId = positiveInteger(claim?.package_id);
       const claimed = {
         amount: normalizeMoney(claim?.amount),
@@ -929,8 +933,9 @@ export function recurringClaimAbsentAssertions(absences, { maxAssertions = Numbe
  */
 export function createCommercialParityReport(capturesValue, journey, options = {}) {
   const countsOnly = options.countsOnly === true;
+  const moneyReason = present(options.unresolvedMoneyClaims) ? String(options.unresolvedMoneyClaims) : null;
   const { valid: captures, invalid: invalidCaptures } = partitionCaptures(capturesValue, { countsOnly });
-  const findings = countsOnly ? [] : diffCommercialParity(captures, journey);
+  const findings = countsOnly ? [] : diffCommercialParity(captures, journey, { unresolvedMoneyClaims: moneyReason });
   const { assertions, omittedFindingCount } = countsOnly
     ? { assertions: [], omittedFindingCount: 0 }
     : serializeCommercialFindings(findings, options);
@@ -958,7 +963,7 @@ export function createCommercialParityReport(capturesValue, journey, options = {
     (sum, { capture }) => sum + capture.vouchers.length,
     0,
   );
-  const priceComparisonCounts = countsOnly
+  const priceComparisonCounts = countsOnly || moneyReason
     ? { compared: 0, unresolved: extractedPriceClaims }
     : matched.reduce((counts, { capture, page }) => {
       const comparison = priceComparisonClaims(capture, page);
@@ -966,7 +971,7 @@ export function createCommercialParityReport(capturesValue, journey, options = {
       counts.unresolved += comparison.unresolved;
       return counts;
     }, { compared: 0, unresolved: 0 });
-  const recurrenceComparisonCounts = countsOnly
+  const recurrenceComparisonCounts = countsOnly || moneyReason
     ? { compared: 0, unresolved: extractedRecurrenceClaims }
     : matched.reduce((counts, { capture, page }) => {
       const comparison = recurrenceComparisonClaims(capture, page);
@@ -1008,6 +1013,9 @@ export function createCommercialParityReport(capturesValue, journey, options = {
     extracted_voucher_claims: extractedVoucherClaims,
     compared_voucher_claims: voucherComparisonCounts.compared,
     unresolved_voucher_claims: voucherComparisonCounts.unresolved,
+    ...(moneyReason && extractedPriceClaims + extractedRecurrenceClaims > 0
+      ? { unresolved_money_claims_reason: moneyReason }
+      : {}),
     serialized_assertion_count: assertions.length,
     omitted_assertion_count: omittedFindingCount,
     findings,

package/src/content-residue.mjs

@@ -189,9 +189,11 @@ export function scanBuiltOutputContentResidue(outputDir, { urgencyVerified = fal
 // seeds non-usable candidates to test exactly that.
 export const BRIEF_PAYLOAD_REL_PATH = ".campaign-runtime/input/brief-payload.json";
 
-export function loadBriefPayload(targetRepo) {
+// `runtimeRelPath` is the packet's runtime directory (packetRuntimeRelPath in
+// campaign-workspace.mjs), so a project's second funnel reads its own payload.
+export function loadBriefPayload(targetRepo, runtimeRelPath = ".campaign-runtime") {
   if (!targetRepo) return null;
-  const path = join(targetRepo, BRIEF_PAYLOAD_REL_PATH);
+  const path = join(targetRepo, runtimeRelPath, relative(".campaign-runtime", BRIEF_PAYLOAD_REL_PATH));
   if (!existsSync(path)) return null;
   try {
     return { path, payload: JSON.parse(readFileSync(path, "utf8")) };

package/src/design-source-package.mjs

@@ -930,6 +930,42 @@ export function designSourcePackageMaterialProjection(value) {
   };
 }
 
+/**
+ * The package with each kept page's Surface Identity re-stated from the
+ * current CampaignSpec page and its re-projected page-kit target (#531):
+ * label, aliases and mappings come out as intake would write them for that
+ * page now, the surface keeps its id, and the source fields intake recorded
+ * (source_path, producer_page_type) are carried over. Surfaces of pages no
+ * longer active, and contributions, gaps and the rest, are untouched; the
+ * material fingerprint is recomputed. `projections` maps a page id to its
+ * page-kit projection; a page with none keeps the page_kit it had.
+ */
+export function rebindDesignSourcePackagePages(value, { activePages = [], projections = new Map() } = {}) {
+  const next = JSON.parse(JSON.stringify(value));
+  const pageById = new Map(arrayOrEmpty(activePages).filter((page) => isObject(page) && isNonEmptyString(page.id)).map((page) => [page.id, page]));
+  for (const surface of arrayOrEmpty(next.surface_identity)) {
+    if (!isObject(surface) || surface.kind !== "page" || !isObject(surface.mappings)) continue;
+    const pageId = optionalString(surface.mappings.campaign_spec_page_id);
+    if (!pageId || !pageById.has(pageId)) continue;
+    const projection = projections instanceof Map ? projections.get(pageId) : null;
+    const mapping = optionalString(surface.mappings.source_page_id)
+      ? {
+          page_id: pageId,
+          path: surface.mappings.source_path ?? null,
+          page_type: surface.mappings.producer_page_type ?? null,
+          page_kit: isObject(surface.mappings.page_kit) && isObject(projection) ? projection : surface.mappings.page_kit ?? null,
+        }
+      : null;
+    const expected = createSurfaceCatalog(collectPageInputs([pageById.get(pageId)], mapping ? [mapping] : []), {}).surfaces.find((entry) => entry.kind === "page");
+    if (!expected) continue;
+    surface.label = expected.label;
+    surface.aliases = expected.aliases;
+    surface.mappings = expected.mappings;
+  }
+  next.material_fingerprint = computeDesignSourcePackageMaterialFingerprint(next);
+  return next;
+}
+
 export function computeDesignSourcePackageMaterialFingerprint(value) {
   const canonical = canonicalJson(designSourcePackageMaterialProjection(value));
   return `${MATERIAL_FINGERPRINT_PREFIX}${createHash("sha256").update(canonical).digest("hex")}`;

package/src/design-source-publication.mjs

@@ -413,7 +413,7 @@ function assertValidPreparedDesignSourcePackage(value, path, currentPageScope, c
 // hash if the run adopts another writer's package instead of publishing, and
 // is removed once a report has recorded the package. A retry that finds it
 // still accepts only bytes that hash to one of its entries.
-function readPriorDesignSourceProvenance(reportPath, packagePath) {
+export function readPriorDesignSourceProvenance(reportPath, packagePath) {
   const synthesized = [];
   const pending = readJsonIfExistsQuietly(pendingDesignSourceProvenancePath(packagePath));
   // All or nothing: a record with any entry that is not a digest (a torn or
@@ -452,7 +452,7 @@ function pendingDesignSourceProvenancePath(designSourcePackagePath) {
 // Written (staged, then renamed into place) before a synthesized package is
 // published, so the claim survives a crash between that publication and the
 // report's. An empty list removes the record.
-function recordPendingDesignSourceProvenance(designSourcePackagePath, sha256) {
+export function recordPendingDesignSourceProvenance(designSourcePackagePath, sha256) {
   const pendingPath = pendingDesignSourceProvenancePath(designSourcePackagePath);
   if (!sha256.length) {
     rmSync(pendingPath, { force: true });
@@ -852,9 +852,12 @@ const PUBLICATION_STEPS = ["package", "writeTheme", "publish", "publishDoctorOut
 
 // Runs `fn(publication)` inside the target lock; the handle's steps run in
 // PUBLICATION_STEPS order, and `package` and `publish` run once.
-export async function withDesignSourcePublication({ targetRepo, outputs, force = false, publishSpec = null }, fn) {
+// `runtimeDir` is the funnel's runtime directory (src/campaign-workspace.mjs):
+// the Design Source Package and the theme output go under it. The target lock
+// stays project-wide, so funnels of one project still take turns.
+export async function withDesignSourcePublication({ targetRepo, runtimeDir = resolve(targetRepo, ".campaign-runtime"), outputs, force = false, publishSpec = null }, fn) {
   const { packetPath, contextPath, reportPath, doctorOutPath, briefPath } = outputs;
-  const designSourcePackagePath = resolve(targetRepo, DESIGN_SOURCE_PACKAGE_REL_PATH);
+  const designSourcePackagePath = resolve(runtimeDir, relative(".campaign-runtime", DESIGN_SOURCE_PACKAGE_REL_PATH));
   const paths = Object.freeze({ packetPath, contextPath, reportPath, doctorOutPath, briefPath, designSourcePackagePath });
   const prepareBuildOutputPaths = [
     ["Build Packet", packetPath],
@@ -864,8 +867,8 @@ export async function withDesignSourcePublication({ targetRepo, outputs, force =
     ["Campaign Build Brief", briefPath],
   ];
   const prepareBuildThemeOutputPaths = [
-    ["Theme Report", resolve(targetRepo, ".campaign-runtime/theme/theme-report.json")],
-    ["Brand Theme CSS", resolve(targetRepo, ".campaign-runtime/theme/brand-theme.css")],
+    ["Theme Report", resolve(runtimeDir, "theme/theme-report.json")],
+    ["Brand Theme CSS", resolve(runtimeDir, "theme/brand-theme.css")],
   ];
   const prepareBuildCollisionPaths = [
     ...prepareBuildOutputPaths,

package/src/directory-lock.mjs

@@ -17,14 +17,19 @@
 // record is never taken over: this module cannot produce one, so it belongs
 // 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.) 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).
+// documented offline procedure. Anything else at the lock path, a file, a
+// directory this process cannot read 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).
+// Every owner record this module writes carries LOCK_FORMAT. A lock held by a
+// live process whose record has no lock format, or a different one, belongs
+// to another release, and a waiter refuses it at once instead of waiting to
+// race that release for the next acquisition. That narrows the mixed-version
+// race publishStagedDirectory describes; it cannot close it (#514).
+//
+// Staging, recovery, released and abandoned 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
@@ -37,6 +42,11 @@ import { basename, dirname, join, resolve } from "node:path";
 
 const heldLocks = new AsyncLocalStorage();
 
+// The lock format this release records in every owner record it writes.
+// Records without one come from earlier releases, including those before
+// 1.43.2 that acquired with mkdir and wrote their owner afterwards (#501).
+export const LOCK_FORMAT = 2;
+
 const readOwner = (path) => {
   try { return JSON.parse(readFileSync(path, "utf8")); } catch { return null; }
 };
@@ -56,9 +66,11 @@ 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.
+// not be put back leaves a released one, and a recovery whose removal of the
+// abandoned lock was cut short leaves an abandoned one. Each carries an
+// owner.json; an abandoned one carries the dead holder's.
 function siblingPattern(path) {
-  return new RegExp(`^${escapeRegExp(basename(path))}\\.(?:staging|recovery-staging|released)-[0-9a-f]{32}$`);
+  return new RegExp(`^${escapeRegExp(basename(path))}\\.(?:staging|recovery-staging|released|abandoned)-[0-9a-f]{32}$`);
 }
 
 // Called only by the holder of the lock, so no two sweeps race, and a
@@ -85,6 +97,9 @@ function sweepDeadSiblings(path) {
 // 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"]);
+// A directory at the lock path that answers these cannot be told apart from
+// a lock whose owner record is merely hidden from this process.
+const UNREADABLE_CODES = new Set(["EACCES", "EPERM"]);
 
 // The reentrancy key names the lock directory through its real parent, so a
 // holder that reached the target through a symlink still recognizes itself.
@@ -119,10 +134,13 @@ function publishStagedDirectory(stagingPath, dest) {
   try {
     // rename(2) replaces an EMPTY destination directory, so never rename over
     // an existing entry. This module never leaves an empty directory at a
-    // lock path; only an older release does, for the instant between its
-    // mkdir and its owner write. A new writer's check-then-rename can land in
-    // that instant and replace it, so running an older release and this one
-    // on the same target at the same moment is not safe (#501; tracked in #514).
+    // lock path; only a release before #501 does, for the instant between its
+    // mkdir and its owner write. A writer's check-then-rename can land in that
+    // instant and replace it, and Node has no rename that refuses to replace.
+    // The waiter's lock-format check (otherRelease) refuses such a release
+    // whenever it is seen holding the lock, but two first attempts that meet
+    // in that instant can still both enter, so running a release before #501
+    // and this one on the same target at the same moment stays unsafe (#514).
     if (exists(dest)) return false;
     try {
       renameSync(stagingPath, dest);
@@ -145,7 +163,7 @@ const OWNERLESS_GRACE_MS = 1000;
 function createLock(path, { budgetMs, unavailable, now = Date.now, ownerlessGraceMs = OWNERLESS_GRACE_MS }) {
   const token = randomBytes(16).toString("hex");
   const start = now();
-  const owner = { pid: process.pid, token };
+  const owner = { pid: process.pid, token, lock_format: LOCK_FORMAT };
   const ownerPath = join(path, "owner.json");
   const stagingPath = `${path}.staging-${token}`;
 
@@ -224,17 +242,49 @@ function createLock(path, { budgetMs, unavailable, now = Date.now, ownerlessGrac
     return current - start >= budgetMs;
   };
   const fail = (error) => unavailable(error);
+  // The refusal for a lock held by a live process of another release, else
+  // null. A record without this release's lock format was written by another
+  // release: waiting for it to release would put this waiter's rename in a
+  // race with that release's next mkdir. A dead holder is recovered as usual,
+  // and a record naming this process was written by this release.
+  const otherRelease = () => {
+    try {
+      const stat = lstatSync(path);
+      if (!stat.isDirectory() || stat.isSymbolicLink()) return null;
+    } catch {
+      return null;
+    }
+    const holder = readOwner(ownerPath);
+    if (!(Number.isInteger(holder?.pid) && holder.pid > 0 && typeof holder.token === "string")) return null;
+    if (holder.lock_format === LOCK_FORMAT || holder.pid === process.pid || ownerIsDead(holder)) return null;
+    const format = holder.lock_format === undefined ? "no lock format" : `lock format ${JSON.stringify(holder.lock_format)}`;
+    return Object.assign(
+      new Error(`Lock is held by process ${holder.pid} of another campaigns-os release (${format}; this release writes lock format ${LOCK_FORMAT}): ${path}`),
+      { code: "ELOCKFORMAT", holderPid: holder.pid, lockFormat: holder.lock_format ?? null },
+    );
+  };
   // 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.
+  // file there, a directory this process cannot read, 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;
+    const unreadable = (error) => `a directory this process cannot read (${error.code}), so it cannot be checked for an owner record`;
+    try {
+      lstatSync(ownerPath);
+      return null;
+    } catch (error) {
+      if (UNREADABLE_CODES.has(error?.code)) return unreadable(error);
+    }
     let foreign;
-    try { foreign = readdirSync(path).filter((entry) => !LOCK_ENTRIES.has(entry)).sort(); } catch { return null; }
+    try {
+      foreign = readdirSync(path).filter((entry) => !LOCK_ENTRIES.has(entry)).sort();
+    } catch (error) {
+      return UNREADABLE_CODES.has(error?.code) ? unreadable(error) : 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})`;
@@ -263,7 +313,7 @@ function createLock(path, { budgetMs, unavailable, now = Date.now, ownerlessGrac
     }
   };
 
-  return { token, stage, publish, recover, heldBySelfProcess, expired, fail, contended, sweep, release };
+  return { token, stage, publish, recover, heldBySelfProcess, otherRelease, expired, fail, contended, sweep, release };
 }
 
 function reentrantKey(path) {
@@ -297,6 +347,8 @@ export async function withDirectoryLock(path, fn, options) {
       throw lock.fail(error);
     }
     if (acquired) break;
+    const mixed = lock.otherRelease();
+    if (mixed) throw lock.fail(mixed);
     if (lock.expired()) throw lock.fail(lock.contended());
     lock.recover();
     await sleep(20);
@@ -329,6 +381,8 @@ export function withDirectoryLockSync(path, fn, options) {
       throw lock.fail(error);
     }
     if (acquired) break;
+    const mixed = lock.otherRelease();
+    if (mixed) throw lock.fail(mixed);
     if (lock.expired() || lock.heldBySelfProcess()) throw lock.fail(lock.contended());
     lock.recover();
     (options.sleep ?? sleepSync)(20);

package/src/doctor/checks.mjs

@@ -14,6 +14,7 @@ import {
 } from "../adapter-decision-contract.mjs";
 import { createDoctorCheckRegistry, runDoctorCheckRegistry } from "../doctor-check-registry.mjs";
 import { evaluateSourcePreparation } from "../source-prep.mjs";
+import { staleRoutingHints } from "../spec-derive.mjs";
 import { isLoopbackHostname } from "../remit.mjs";
 import {
   HOST_STRIPPED_CODE,
@@ -26,6 +27,7 @@ import {
   SOURCE_HTML_MANIFEST_SCHEMA,
 } from "../source-html-manifest.mjs";
 import { validateAssemblyReportThemeBlock, validateThemeContextBlock } from "../brand-theme.mjs";
+import { packetRuntimeRelPath } from "../campaign-workspace.mjs";
 import { singleLineDetail, singleLineField } from "../text-safety.mjs";
 import {
   campaignRouteRoot,
@@ -34,6 +36,7 @@ import {
   normalizePublicRouteSlug,
   packetRouteRoot,
   runtimeRelativeRouteForSpecValue,
+  specPublicRouteSlug,
   stripPublicRoutePrefix,
 } from "../route-identity.mjs";
 import { evaluatePageKitBuildSummary } from "../page-kit-build-summary.mjs";
@@ -102,6 +105,7 @@ import {
 import { loadPageKitCampaignEntry, pageKitIgnoresAssetsHtml, projectPageKitCampaignLoad } from "../page-kit-campaign-config.mjs";
 import { evaluatePageKitStoreProfile, PAGE_KIT_STORE_PROFILE_SCOPE, storeProfileIntentionallyEmptyNote } from "../page-kit-store-profile.mjs";
 import { evaluatePageKitSdkVersion, PAGE_KIT_SDK_VERSION_SCOPE } from "../page-kit-sdk-version.mjs";
+import { evaluatePageKitAnalyticsVendors, PAGE_KIT_ANALYTICS_VENDORS_SCOPE } from "../page-kit-analytics-vendors.mjs";
 // ADR-003: the public, canonical CampaignSpec rule registry. The doctor and any
 // campaign authoring UI (e.g. a Map Builder bundle) import the same rules, so a
 // spec check is authored once and reaches internal teams and agencies alike.
@@ -382,6 +386,11 @@ const SPEC_DOCTOR_CHECKS = createDoctorCheckRegistry([
     phase: "target",
     run: ({ spec, errors, warnings, ready, derived, buildState }) => validateTargetStoreProfile(spec, errors, warnings, ready, derived, buildState),
   },
+  {
+    id: PAGE_KIT_ANALYTICS_VENDORS_SCOPE,
+    phase: "target",
+    run: ({ spec, warnings, ready, buildState }) => validateTargetAnalyticsVendors(spec, warnings, ready, buildState),
+  },
   {
     id: "spec.shipping_countries",
     phase: "spec",
@@ -392,6 +401,11 @@ const SPEC_DOCTOR_CHECKS = createDoctorCheckRegistry([
     phase: "spec",
     run: ({ spec, packet, warnings, ready, derived, buildState }) => validateSpecRoutingMetaTags(spec, packet, warnings, ready, derived, buildState),
   },
+  {
+    id: "spec.routing_hint_stale",
+    phase: "spec",
+    run: ({ spec, packet, errors, ready }) => validateSpecRoutingHintsCurrent(spec, packet, errors, ready),
+  },
   {
     id: "spec.routing_host_prefix",
     phase: "spec",
@@ -1416,6 +1430,18 @@ function validateTargetStoreProfile(spec, errors, warnings, ready, derived, buil
     + storeProfileIntentionallyEmptyNote(intentionallyEmpty));
 }
 
+// The starter-template vendor keys against analytics.vendors: advisory only,
+// one warning per vendor the two sides disagree on (#689).
+function validateTargetAnalyticsVendors(spec, warnings, ready, buildState) {
+  const result = evaluatePageKitAnalyticsVendors({ spec, targetLoad: buildState?.pageKitCampaignConfig });
+  for (const finding of result.findings) {
+    addIssue(warnings, finding.code, finding.message, { vendor: finding.vendor, id_key: finding.id_key, repair: finding.repair });
+  }
+  if (result.status === "ok" && result.vendors.length) {
+    ready.push(`Target campaigns.json vendor keys match the CampaignSpec analytics.vendors (${result.vendors.join(", ")}).`);
+  }
+}
+
 function validateSpecShippingCountries(spec, warnings, ready) {
   const countries = spec?.campaign?.available_shipping_countries;
   if (countries === "all" || (Array.isArray(countries) && countries.length === 0)) {
@@ -1557,11 +1583,7 @@ export function validateRouteSlugIdentity(spec, packet, errors, ready) {
   const mapId = optionalString(spec?.spec_identity?.map_id)
     || optionalString(spec?.map_id)
     || optionalString(packet?.spec?.map_id);
-  const specSlug = normalizePublicRouteSlug(
-    optionalString(spec?.spec_identity?.public_route_slug)
-    || optionalString(spec?.campaign?.slug)
-    || optionalString(spec?.campaign?.id)
-  );
+  const specSlug = specPublicRouteSlug(spec);
   const specDeclaresMapIdSlug = Boolean(specSlug) && Boolean(mapId) && specSlug === mapId;
 
   if (mapId && packetSlug === mapId && !specDeclaresMapIdSlug) {
@@ -1692,6 +1714,31 @@ export function validateSpecRoutingMetaTags(spec, packet, warnings, ready, deriv
   );
 }
 
+// #531: a routing hint (`sdk_hints.meta_tags` next-success-url and the upsell
+// accept/decline urls) that does not match the route of the page its routing
+// field names. Nothing else catches it once the build exists: the built meta
+// check compares the built page against the hint, and QA derives its
+// expectation from the hint, so a moved upsell with checkout still pointing
+// at the old path passes both and sends shoppers to a 404 after payment. It
+// blocks on every read, before and after the build, and record spec refuses a
+// routes-only bind on the same function (spec-derive.mjs staleRoutingHints).
+export function validateSpecRoutingHintsCurrent(spec, packet, errors, ready) {
+  const publicRouteSlug = normalizePublicRouteSlug(packet?.campaign?.public_route_slug);
+  const stale = staleRoutingHints(spec, { publicRouteSlug });
+  if (!stale.length) {
+    if (activeSpecPages(spec).some((page) => isObject(page.sdk_hints?.meta_tags))) ready.push("CampaignSpec routing hints match the routes of the pages they name");
+    return;
+  }
+  const sample = stale.slice(0, 5).map((hint) => `${hint.page_id}:${hint.tag} ${JSON.stringify(hint.value)} but page "${hint.target_page_id}" routes to ${JSON.stringify(hint.derived_route)}`).join("; ");
+  const more = stale.length > 5 ? `; plus ${stale.length - 5} more` : "";
+  addIssue(
+    errors,
+    "spec.routing_hint_stale",
+    `CampaignSpec routing hint(s) name a route the page they point at no longer has: ${sample}${more}. The built meta tag follows the hint, so the SDK would send shoppers to the old path. Edit each hint to the route shown in the spec (or, while the Map is still the spec's source, re-save the Map, which regenerates them), then run record spec.`,
+    { hints: stale },
+  );
+}
+
 // #531: a route with a host in front of its path ("shop.example.com/route/x/")
 // is nested under the campaign root by every stage that composes a URL
 // (polish capture requested "/route/shop.example.com/route/x/"), so it blocks.
@@ -3264,6 +3311,12 @@ function scanMarketSensitiveCopy(spec, warnings, ready, derived) {
   }
 }
 
+// CampaignSpec owns `campaign.available_currencies`: every currency the
+// campaign sells in, the default included (the CampaignCurrencies rule checks
+// its codes). `additional_currencies` is the Campaigns App API's name for the
+// same list without the default and is not a spec field; both market scopes
+// still read it, and its camelCase spelling, so a spec copied from an API body
+// gets the copy review it needs.
 function deriveMarketScope(spec) {
   const campaign = spec?.campaign || {};
   const defaultCurrency = normalizeCurrency(campaign.currency);
@@ -3712,6 +3765,25 @@ function validateSourceCoverage(packet, packetPath, spec, errors, warnings, read
     if (!activeIds.has(page.page_id)) {
       addIssue(warnings, "source_html.pages.extra", `Source mapping "${page.page_id}" is not an active CampaignSpec page.`);
     }
+    // A page added from the repo's page tree after handoff (#721): its source
+    // is the target page file itself, so it is mapped and, once that file
+    // exists, a build candidate like any other.
+    if (page.origin === "repo") {
+      const repoFile = optionalString(page.page_kit?.output_path) && derived.target_repo ? resolve(derived.target_repo, page.page_kit.output_path) : null;
+      if (!repoFile || !existsSync(repoFile) || !statSync(repoFile).isFile()) {
+        addIssue(errors, "source_html.pages.repo_page_missing", `Page "${page.page_id}" was added from the repo's page tree, but its page file ${page.page_kit?.output_path || "(no page_kit.output_path)"} is not in the target repo. Restore the file, or run spec derive and record spec to remove the page.`, { page_id: page.page_id, output_path: page.page_kit?.output_path || null });
+      } else if (specPage) {
+        builtPages.push({
+          page_id: specPage.id,
+          type: specPage.type || "page",
+          role: pageRole(specPage.type),
+          route: builtRoute,
+          source_path: null,
+          repo_source: page.page_kit.output_path,
+        });
+      }
+      continue;
+    }
     if (page.path) {
       const fullPath = resolve(sourceRoot, page.path);
       if (!existsSync(fullPath) || !statSync(fullPath).isFile()) {
@@ -4625,7 +4697,7 @@ export function validateBuiltContentResidue(packet, errors, warnings, ready, der
   const publicRouteSlug = normalizePublicRouteSlug(packet?.campaign?.public_route_slug);
   const siteRoot = derived.target_repo && publicRouteSlug ? join(derived.target_repo, "_site", publicRouteSlug) : null;
   if (!siteRoot || !existsSync(siteRoot) || !statSync(siteRoot).isDirectory()) return;
-  const brief = loadBriefPayload(derived.target_repo);
+  const brief = loadBriefPayload(derived.target_repo, packetRuntimeRelPath(packet));
   const urgencyVerified = briefUrgencyVerified(brief?.payload);
   const findings = scanBuiltOutputContentResidue(siteRoot, { urgencyVerified });
   if (!findings.length) {
@@ -4694,7 +4766,7 @@ export function validateBuiltContentResidue(packet, errors, warnings, ready, der
 // non-shipped, non-usable assets stay warnings (the attestation queue), so a
 // producer that correctly excluded them is not blocked.
 export function validateProofAttestation(packet, errors, warnings, ready, derived, buildState = {}) {
-  const brief = loadBriefPayload(derived.target_repo);
+  const brief = loadBriefPayload(derived.target_repo, packetRuntimeRelPath(packet));
   if (!brief) return; // not an AI-assembled run — no brief payload, no gate
   if (brief.error) {
     // Fail closed: the brief payload is the source of attestation state. If