@nextcommerce/campaigns-os 1.60.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-file-reference.mjs

@@ -0,0 +1,93 @@
+import { collectFigmaProvenanceFindings } from "./doctor/source-provenance.mjs";
+import { createHash } from "node:crypto";
+import { canonicalJson } from "./polish-capture.mjs";
+
+const VIEWPORTS = ["desktop", "tablet", "mobile"];
+const nonEmpty = (value) => typeof value === "string" && value.trim().length > 0;
+const object = (value) => value && typeof value === "object" && !Array.isArray(value);
+const absoluteHttps = (value) => {
+  if (!nonEmpty(value)) return null;
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" ? url : null;
+  } catch { return null; }
+};
+
+// Declared links are data. No design-file reader or network access lives here.
+export function normalizeDesignFileReference(value) {
+  const warnings = [];
+  const url = object(value) && absoluteHttps(value.file_url);
+  if (!url) return { declaration: null, warnings: ["file_url must be a non-empty absolute https: URL"] };
+  const type = nonEmpty(value.type) ? value.type.toLowerCase() : (url.hostname === "figma.com" || url.hostname.endsWith(".figma.com")) ? "figma" : "other";
+  let fileKey = null;
+  if (type === "figma") {
+    const parts = url.pathname.split("/");
+    const index = parts.findIndex((part) => ["file", "design", "proto", "board"].includes(part));
+    let candidate = index < 0 ? null : parts[index + 1];
+    const branch = parts.indexOf("branch", index + 2);
+    if (index >= 0 && branch >= 0 && /^[A-Za-z0-9]+$/.test(parts[branch + 1] ?? "")) candidate = parts[branch + 1];
+    if (typeof candidate === "string" && /^[A-Za-z0-9]+$/.test(candidate)) fileKey = candidate;
+  }
+  const identity = fileKey == null ? { type, url: url.origin + url.pathname } : { type, file_key: fileKey };
+  const file_identity_sha256 = createHash("sha256").update(canonicalJson(identity)).digest("hex");
+  const frames = {};
+  for (const viewport of VIEWPORTS) {
+    if (!object(value.breakpoints) || !Object.hasOwn(value.breakpoints, viewport)) continue;
+    const link = value.breakpoints[viewport];
+    let frame;
+    try { frame = nonEmpty(link) ? new URL(link) : null; } catch { frame = null; }
+    if (!frame) { warnings.push(`breakpoints.${viewport} must be an absolute frame URL`); continue; }
+    frames[viewport] = { url: link, node_id: frame.searchParams.get("node-id")?.replaceAll("-", ":") ?? null };
+  }
+  return { declaration: { type, file_url: value.file_url, file_key: fileKey, identity, file_identity_sha256, frames }, warnings };
+}
+
+export function resolveDesignFileReferences({ activePages = [], mappings = [], manifest = null, specChannel = { mode: "intake" } } = {}) {
+  const pages = [];
+  const files = new Map();
+  // Intake records only Figma spec pointers backed by #534's provenance test.
+  // Doctor first uses today's intake declaration. Only a page with recorded
+  // design-file lineage can fall back to its Figma spec without provenance.
+  // Manifest declarations stand alone; a shared file's producer is not per-page.
+  const exportProvenance = manifest != null && !collectFigmaProvenanceFindings(manifest).some((finding) => finding.severity === "provenance");
+  const producer = manifest?.producer_provenance;
+  const producerKeys = new Set([producer?.figma_file_key, ...(Array.isArray(producer?.figma_file_keys) ? producer.figma_file_keys : [])].filter(nonEmpty));
+  for (const page of activePages) {
+    const mapping = mappings.find((entry) => entry?.page_id === page.id);
+    if (!nonEmpty(mapping?.path)) continue;
+    const matches = (Array.isArray(manifest?.pages) ? manifest.pages : []).filter((entry) => entry?.page_id === page.id && entry.path === mapping.path);
+    const manifestValue = matches.length === 1 ? matches[0].design_file : null;
+    const specDeclaration = normalizeDesignFileReference(page.design_source).declaration;
+    const fromManifest = normalizeDesignFileReference(manifestValue);
+    const intakeSpec = specDeclaration?.type === "figma" && exportProvenance ? specDeclaration : null;
+    const fallbackSpec = !intakeSpec && !fromManifest.declaration
+      && specChannel.mode === "doctor" && specChannel.recordedPageIds?.has(page.id)
+      && specDeclaration?.type === "figma" ? specDeclaration : null;
+    const fromSpec = intakeSpec || fallbackSpec;
+    const declaration = fromSpec || fromManifest.declaration;
+    if (!declaration) continue;
+    const declared_by = fromSpec ? "campaign_spec" : "source_html_manifest";
+    let conflict = null;
+    // Provenance decides which declaration records lineage, never whether a
+    // Figma spec that disagrees with the manifest is reported.
+    const specNamed = fromSpec || (specDeclaration?.type === "figma" ? specDeclaration : null);
+    if (specNamed && fromManifest.declaration) {
+      const other = fromManifest.declaration;
+      const frames = VIEWPORTS.filter((viewport) => specNamed.frames[viewport] && other.frames[viewport] && specNamed.frames[viewport].node_id !== other.frames[viewport].node_id).sort();
+      if (specNamed.file_identity_sha256 !== other.file_identity_sha256 || frames.length) {
+        conflict = { kind: "spec_vs_manifest", identities: [specNamed.file_identity_sha256, other.file_identity_sha256].sort(), ...(frames.length ? { frames } : {}) };
+      }
+    }
+    if (!conflict && declaration.type === "figma" && declaration.file_key && producerKeys.size && !producerKeys.has(declaration.file_key)) {
+      conflict = { kind: "producer_file_key", identities: [declaration.file_identity_sha256] };
+    }
+    pages.push({ page_id: page.id, declaration, declared_by, conflict, warnings: manifestValue == null ? [] : fromManifest.warnings });
+    const sha = declaration.file_identity_sha256;
+    if (!files.has(sha)) files.set(sha, { contribution_id: `design-file-${sha.slice(0, 12)}`, identity: declaration.identity, file_url: declaration.file_url, producer: declared_by, pages: [] });
+    const file = files.get(sha);
+    // A shared file keeps the manifest's provenance if any page declared it there.
+    if (declared_by === "source_html_manifest") file.producer = declared_by;
+    file.pages.push(page.id);
+  }
+  return { pages, files: [...files.values()] };
+}

package/src/design-source-package.mjs

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { resolveDesignFileReferences } from "./design-file-reference.mjs";
 
 export const DESIGN_SOURCE_PACKAGE_SCHEMA = "campaign-design-source-package/v0";
 export const DESIGN_SOURCE_PACKAGE_REL_PATH = ".campaign-runtime/input/design-source-package.json";
@@ -166,7 +167,7 @@ const PRESENTATION_INTENT_FIELDS = new Set([
   "brand",
   "responsive_behavior",
 ]);
-const SOURCE_REF_FIELDS = new Set(["id", "kind", "path", "url", "sha256", "role", "media_type", "notes"]);
+const SOURCE_REF_FIELDS = new Set(["id", "kind", "path", "url", "sha256", "role", "media_type", "notes", "design_file_type"]);
 const VISUAL_REF_FIELDS = new Set([
   "id",
   "kind",
@@ -195,6 +196,7 @@ const TEMPLATE_REFERENCE_FIELDS = new Set([
   "standard_viewport_refs",
 ]);
 const COVERAGE_MAPPING_FIELDS = new Set([
+  "derived_from",
   "id",
   "surface_id",
   "coverage_role",
@@ -337,6 +339,7 @@ export function synthesizeHtmlFunnelDesignSourcePackage({
   });
 
   const manifestInput = normalizeManifestInput(manifest, manifestPath);
+  const designFiles = resolveDesignFileReferences({ activePages, mappings: resolvedMappings, manifest: manifestInput.value });
   const crawl = isObject(sourceAssetCrawl) ? sourceAssetCrawl : isObject(assetCrawl) ? assetCrawl : null;
   const crawlInputName = isObject(sourceAssetCrawl) ? "sourceAssetCrawl" : "assetCrawl";
   assertOptionalInputArray(manifestInput.value?.files, "manifest.files");
@@ -480,6 +483,9 @@ export function synthesizeHtmlFunnelDesignSourcePackage({
     htmlCoverage.push({
       id: `html-${surfaceId}-coverage`,
       surface_id: surfaceId,
+      ...(designFiles.pages.some((entry) => entry.page_id === page.pageId) ? {
+        derived_from: designFiles.files.find((file) => file.pages.includes(page.pageId)).contribution_id,
+      } : {}),
       coverage_role: explicitRole || "primary_design",
       confidence: normalizeConfidence(mapping?.confidence)
         || confidenceForHtmlMapping(mapping, manifestPage),
@@ -525,6 +531,37 @@ export function synthesizeHtmlFunnelDesignSourcePackage({
   };
 
   const contributions = [htmlContribution];
+  for (const file of [...designFiles.files].sort((a, b) => a.contribution_id.localeCompare(b.contribution_id))) {
+    const id = file.contribution_id;
+    // kind collapses non-Figma tools to "other". Use a new field so existing
+    // source-reference notes remain nonmaterial, including design_file refs.
+    const sourceRefs = [{ id: `${id}-file`, kind: "url", url: file.file_url, role: "design_file",
+      ...(!["figma", "other"].includes(file.identity.type) ? { design_file_type: file.identity.type } : {}),
+    }];
+    const mappings = file.pages.map((pageId) => {
+      const surfaceId = surfaceByPageId.get(pageId);
+      const declaration = designFiles.pages.find((page) => page.page_id === pageId).declaration;
+      const frameRefs = Object.entries(declaration.frames).map(([viewport, frame]) => ({
+        id: `${id}-${surfaceId}-frame-${viewport}`, kind: "url", url: frame.url, role: `design_frame:${viewport}`,
+      }));
+      sourceRefs.push(...frameRefs);
+      return { id: `${id}-${surfaceId}-coverage`, surface_id: surfaceId, coverage_role: "reference_only", confidence: "high", source_refs: [`${id}-file`, ...frameRefs.map((ref) => ref.id)], screenshot_refs: [], reference_refs: [] };
+    });
+    const fromManifest = file.producer === "source_html_manifest";
+    contributions.push({
+      id, kind: file.identity.type === "figma" ? "figma_frames" : "other", trust: file.identity.type === "figma" ? "native" : "opaque", renderable: false,
+      provenance: {
+        source_type: "design_file", adapter: "design-file-reference", producer: file.producer,
+        generator: null, generator_version: null, source_root: null,
+        manifest_schema_version: fromManifest ? optionalString(manifestInput.value?.schema_version) : null,
+        manifest_path: fromManifest ? optionalString(manifestInput.path) : null,
+        manifest_sha256: fromManifest ? validSha(manifestInput.value?.sha256) : null,
+        producer_material_fingerprint: null, asset_crawl_schema_version: null,
+      },
+      presentation_intent: { summary: "Design file the page's HTML export was produced from. Recorded as the design authority; this version does not read it." },
+      source_refs: sourceRefs, screenshot_refs: [], reference_refs: [], mappings,
+    });
+  }
   const template = normalizeTemplateFamily(templateFamily);
   const qualifyingHtmlSurfaces = new Set(
     htmlCoverage
@@ -893,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")}`;
@@ -998,6 +1071,15 @@ export function validateDesignSourcePackage(value, {
     if (contributionIds.has(contribution.id)) add("design_source_package.contribution_id_duplicate", `${path}.id`, `Duplicate contribution id "${contribution.id}".`);
     contributionIds.add(contribution.id);
   });
+  contributions.forEach((contribution, index) => {
+    arrayOrEmpty(contribution?.mappings).forEach((mapping, mappingIndex) => {
+      if (!Object.hasOwn(mapping || {}, "derived_from")) return;
+      const target = contributions.find((entry) => entry?.id === mapping.derived_from && entry !== contribution);
+      if (!target || !["figma_frames", "figma_sections", "other"].includes(target.kind) || !arrayOrEmpty(target.mappings).some((entry) => entry?.surface_id === mapping.surface_id)) {
+        add("design_source_package.derived_from_ref", `$.contributions[${index}].mappings[${mappingIndex}].derived_from`, "derived_from must name another design contribution mapped to the same surface_id.");
+      }
+    });
+  });
 
   validateRecordArray(value.source_gaps, "$.source_gaps", GAP_FIELDS,
     ["id", "kind", "scope", "applies_to", "reason", "status", "attributed_by"], add,
@@ -1394,6 +1476,8 @@ function projectContribution(contribution) {
 function projectSourceRef(ref) {
   return compactDefined({
     ...pickFields(ref, ["id", "kind", "path", "url", "role", "media_type"]),
+    // Absent from every BASE-valid package; never project existing prose notes.
+    design_file_type: ref?.design_file_type,
     sha256: canonicalHashSpelling(ref?.sha256),
   });
 }
@@ -1451,6 +1535,7 @@ function projectProvenance(provenance) {
 
 function projectCoverageMapping(mapping) {
   return compactDefined({
+    derived_from: mapping?.derived_from,
     id: mapping?.id,
     surface_id: mapping?.surface_id,
     coverage_role: mapping?.coverage_role,
@@ -2252,6 +2337,10 @@ function validateSourceReference(value, path, add) {
   if (!checkStrictObject(value, path, SOURCE_REF_FIELDS, ["id", "kind"], add)) return;
   checkNonEmptyString(value.id, `${path}.id`, add);
   checkEnum(value.kind, SOURCE_REF_KINDS, `${path}.kind`, add);
+  if (Object.hasOwn(value, "design_file_type")) {
+    checkNonEmptyString(value.design_file_type, `${path}.design_file_type`, add);
+    if (value.role !== "design_file") add("design_source_package.design_file_type", `${path}.design_file_type`, "design_file_type requires role design_file.");
+  }
   if (!isNonEmptyString(value.path) && !isNonEmptyString(value.url)) add("design_source_package.source_ref_location", path, "Source reference requires path or url.");
   for (const field of ["path", "url", "role", "media_type"]) if (value[field] != null) checkNonEmptyString(value[field], `${path}.${field}`, add);
   if (value.sha256 != null && !SHA256_PATTERN.test(value.sha256)) add("design_source_package.sha256", `${path}.sha256`, "sha256 must be 64 lowercase hex, with optional sha256: prefix.");
@@ -2293,6 +2382,7 @@ function validateCoverageMapping(value, path, add) {
     "id", "surface_id", "coverage_role", "confidence", "source_refs", "screenshot_refs", "reference_refs",
   ], add)) return false;
   checkNonEmptyString(value.id, `${path}.id`, add);
+  if (Object.hasOwn(value, "derived_from")) checkNonEmptyString(value.derived_from, `${path}.derived_from`, add);
   checkNonEmptyString(value.surface_id, `${path}.surface_id`, add);
   checkEnum(value.coverage_role, new Set(COVERAGE_ROLES), `${path}.coverage_role`, add);
   checkEnum(value.confidence, new Set(MAPPING_CONFIDENCE_LEVELS), `${path}.confidence`, add);

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);