@nextcommerce/campaigns-os 1.43.1 → 1.46.0

package/src/qa-test-order-topology.mjs

@@ -30,6 +30,19 @@ export function resolveTestOrderTopology(topology = {}, checkoutPage = null) {
     ...(entry?.kind === "terminal" ? [entry.terminal] : []),
     ...terminalPaths.map((candidate) => candidate.terminal),
   ]);
+  // Every declared offer page with the offer page each action leads to, so a
+  // planned path that stops short of a terminal can still be walked to the
+  // controls it clicks.
+  const offerEdges = [];
+  for (const [key, page] of pagesByUrl) {
+    if (!OFFER_PAGE_TYPES.has(pageType(page))) continue;
+    const edge = { key, page_id: page.page_id || null, page_type: page.page_type || null, url: page.url };
+    for (const [action, field] of ACTIONS) {
+      const target = targetNode(page?.[field], pagesByUrl, topologyOrigin);
+      edge[`${action}_key`] = target?.kind === "offer" ? canonicalHttpUrl(target.page.url) : null;
+    }
+    offerEdges.push(edge);
+  }
 
   return {
     topology_id: topology?.funnel_id || "default",
@@ -48,6 +61,8 @@ export function resolveTestOrderTopology(topology = {}, checkoutPage = null) {
     terminal_paths: terminalPaths,
     invalid_paths: invalidPaths,
     recognized_terminals: recognizedTerminals,
+    entry_offer_key: entry?.kind === "offer" ? canonicalHttpUrl(entry.page.url) : null,
+    offer_edges: offerEdges,
   };
 }
 
@@ -95,6 +110,139 @@ export function commonTestOrderPaths(resolvedTopology) {
   return paths;
 }
 
+// The default `common` depth (#530). The sample above never reached a
+// downsell's decline, so a broken decline link passed QA. When every actual
+// terminal path fits under the cap, `common` runs them all. Above the cap it
+// keeps the sample and adds, for each offer page whose decline no planned path
+// clicks yet, the shortest path that clicks it, until the cap is reached. A
+// page counts as covered only when its decline is clicked: arriving at it, or
+// clicking its accept, does not. Pages still uncovered are returned, not
+// dropped. The sample is never trimmed, so a cap below it is still refused by
+// the flood guard exactly as before.
+export function commonTestOrderPlan(resolvedTopology, { cap } = {}) {
+  const baseline = commonTestOrderPaths(resolvedTopology);
+  let full = null;
+  try {
+    full = fullTestOrderPaths(resolvedTopology);
+  } catch {
+    full = null;
+  }
+  const plan = {
+    requested_depth: "common",
+    cap,
+    full_path_count: full ? full.length : null,
+    baseline_paths: baseline,
+  };
+  if (full && full.length <= cap) {
+    // Same set as `full`; the sample's paths keep their place at the front.
+    const paths = [...baseline.filter((path) => full.includes(path)), ...full.filter((path) => !baseline.includes(path))];
+    return { ...plan, effective_depth: "full", reason: "under_cap", paths, coverage_paths: [], uncovered_pages: [] };
+  }
+
+  const paths = baseline.slice();
+  const coveragePaths = [];
+  const offers = offerPagesByReach(resolvedTopology);
+  for (const offer of offers) {
+    if (paths.length >= cap) break;
+    const declined = declinedOfferKeys(resolvedTopology, paths);
+    if (declined.has(offer.key) || !offer.reach) continue;
+    const candidate = shortestDeclinePath(resolvedTopology, offer, declined);
+    if (!candidate || paths.includes(candidate)) continue;
+    paths.push(candidate);
+    coveragePaths.push(candidate);
+  }
+  const declined = declinedOfferKeys(resolvedTopology, paths);
+  const uncovered = offers
+    .filter((offer) => !declined.has(offer.key))
+    .map((offer) => ({
+      page_id: offer.page_id,
+      page_type: offer.page_type,
+      reason: offer.reach ? "cap" : "unreachable",
+    }));
+  return {
+    ...plan,
+    effective_depth: "common",
+    reason: full ? "over_cap" : "full_not_enumerable",
+    paths,
+    coverage_paths: coveragePaths,
+    uncovered_pages: uncovered,
+  };
+}
+
+// The offer pages a planned path clicks, in click order: `checkout` clicks
+// none, `decline-accept` clicks the entry offer's decline and then the accept
+// on whichever offer that decline leads to. A walk stops where the topology
+// leaves the offer graph, as the runner does.
+export function testOrderPathClicks(resolvedTopology, path) {
+  const normalized = String(path || "").toLowerCase();
+  const steps = !normalized || normalized === "checkout" ? [] : normalized.split("-");
+  const edges = new Map((resolvedTopology?.offer_edges || []).map((edge) => [edge.key, edge]));
+  const clicks = [];
+  let current = edges.get(resolvedTopology?.entry_offer_key) || null;
+  for (const step of steps) {
+    if (!current) break;
+    clicks.push({ key: current.key, page_id: current.page_id, action: step });
+    current = edges.get(current[`${step}_key`]) || null;
+  }
+  return clicks;
+}
+
+function declinedOfferKeys(resolvedTopology, paths) {
+  const keys = new Set();
+  for (const path of paths) {
+    for (const click of testOrderPathClicks(resolvedTopology, path)) {
+      if (click.action === "decline") keys.add(click.key);
+    }
+  }
+  return keys;
+}
+
+// Declared offer pages, shallowest first, each with the shortest action
+// sequence that reaches it (accept before decline on a tie) or null when no
+// path from the checkout reaches it.
+function offerPagesByReach(resolvedTopology) {
+  const edges = resolvedTopology?.offer_edges || [];
+  const byKey = new Map(edges.map((edge) => [edge.key, edge]));
+  const reach = new Map();
+  const entry = resolvedTopology?.entry_offer_key;
+  if (entry && byKey.has(entry)) {
+    reach.set(entry, []);
+    const queue = [entry];
+    while (queue.length) {
+      const key = queue.shift();
+      for (const action of ["accept", "decline"]) {
+        const next = byKey.get(key)?.[`${action}_key`];
+        if (!next || reach.has(next) || !byKey.has(next)) continue;
+        reach.set(next, [...reach.get(key), action]);
+        queue.push(next);
+      }
+    }
+  }
+  const reached = [...reach.keys()].map((key) => ({ ...byKey.get(key), reach: reach.get(key) }));
+  const unreached = edges.filter((edge) => !reach.has(edge.key)).map((edge) => ({ ...edge, reach: null }));
+  return [...reached, ...unreached];
+}
+
+// The shortest actual terminal path that clicks this offer's decline. Among
+// equally short paths, the one that also clicks the most still-undeclined
+// offers wins, then accept before decline. Where no terminal path clicks it
+// (the graph beyond is not enumerable), the path that reaches the offer and
+// declines it.
+function shortestDeclinePath(resolvedTopology, offer, declined) {
+  const newlyDeclined = (path) => new Set(testOrderPathClicks(resolvedTopology, path)
+    .filter((click) => click.action === "decline" && !declined.has(click.key))
+    .map((click) => click.key)).size;
+  const candidates = (resolvedTopology?.terminal_paths || [])
+    .filter((candidate) => testOrderPathClicks(resolvedTopology, candidate.path)
+      .some((click) => click.key === offer.key && click.action === "decline"))
+    .map((candidate) => ({ ...candidate, gain: newlyDeclined(candidate.path) }))
+    .sort((left, right) => (left.steps.length - right.steps.length)
+      || (right.gain - left.gain)
+      || compareActionSteps(left.steps, right.steps));
+  if (candidates.length) return candidates[0].path;
+  return [...offer.reach, "decline"].join("-");
+}
+
 function compareCommonReceiptPaths(left, right) {
   const lengthDelta = (left?.steps?.length || 0) - (right?.steps?.length || 0);
   if (lengthDelta) return lengthDelta;

package/src/sdk-markup.mjs

@@ -2,12 +2,12 @@
 //
 // `built_output.upsell_selector_scope` catches one shape of built markup that
 // the Campaign Cart SDK binds without complaint and that then does the wrong
-// thing to a shopper. This module is the rest of that family: six more
+// thing to a shopper. This module is the rest of that family: seven more
 // shapes, each a static read of built HTML, each producing either a silent
 // no-op (the shopper fills a field that never reaches the order; a button
 // that never enables) or a double cart write. A partner agency's Campaign
-// Cart skill kit listed them as stable lint codes; the codes are kept so the
-// two vocabularies line up.
+// Cart skill kit listed the first six as stable lint codes; the codes are
+// kept so the two vocabularies line up. ORPHANED_UPSELL_ACTION is ours.
 //
 //   Blockers (not waivable — the markup provably does not do what it says)
 //   SWAP_WITH_ADD_TO_CART      a bundle selector in swap mode (explicit, or
@@ -26,6 +26,12 @@
 //   MISSING_SELECTOR_ID_MATCH  an add-to-cart button whose data-next-selector-id
 //                              names no selector on the page. The button waits
 //                              for a selection that can never arrive.
+//   ORPHANED_UPSELL_ACTION     data-next-upsell-action with no ancestor carrying
+//                              data-next-upsell (#529). The upsell enhancer
+//                              binds only the actions inside its container; an
+//                              action outside it is a plain link, so a "No
+//                              thanks" goes nowhere and the shopper is stuck.
+//                              Every page type, not only upsell pages.
 //
 //   Warnings (advisory)
 //   DOUBLE_SELECTED            more than one data-next-selected="true" card in
@@ -34,6 +40,12 @@
 //   TEMPLATE_DOUBLE_BRACE      `{{` inside an SDK-owned <template>. SDK tokens
 //                              are single-brace and conditions are no-brace;
 //                              a double brace renders literally.
+//   CHECKOUT_BUMP_IS_UPSELL    data-next-is-upsell="true" on a checkout page
+//                              (#535). A checkout bump is a pre-purchase
+//                              add-on; the flag puts it on the initial order
+//                              as an upsell line. The page type is a live,
+//                              unambiguous next-page-type meta, since it is
+//                              what the SDK reads; otherwise the route type.
 //
 //   Info (advisory, one note per campaign, no code)
 //   unknown_attributes[]       a data-next-* name the pinned SDK's attribute
@@ -43,10 +55,11 @@
 //                              own data-next-* hooks, which is why it informs
 //                              rather than warns.
 //
-// Parsed with parse5 rather than regex because four of the six turn on
-// containment (a card inside a selector, a field inside a form, a template's
-// content), and HTML nesting is not a regular language. Template content is
-// walked too: the SDK clones it into the live DOM.
+// Parsed with parse5 rather than regex because five of the seven turn on
+// containment (a card inside a selector, a field inside a form, an action
+// inside its upsell container, a template's content), and HTML nesting is not
+// a regular language. Template content is walked too: the SDK clones it into
+// the live DOM.
 //
 // Pure: callers hand in built HTML. Both doctor entry points drive it.
 
@@ -57,6 +70,9 @@ import {
   isIndexedSdkAttribute,
   isKnownCheckoutFieldName,
 } from "./sdk-attribute-index.mjs";
+import { builtPageTypeMeta } from "./upsell-selector-scope.mjs";
+
+const normalizedPageTypeValue = (type) => (type == null ? null : String(type).trim().toLowerCase());
 
 export const SDK_MARKUP = "built_output.sdk_markup";
 
@@ -65,8 +81,10 @@ export const SDK_MARKUP_CODES = Object.freeze({
   CHECKOUT_NOT_FORM: { code: `${SDK_MARKUP}.checkout_not_form`, severity: "error" },
   WRONG_FIELD_NAME: { code: `${SDK_MARKUP}.wrong_field_name`, severity: "error" },
   MISSING_SELECTOR_ID_MATCH: { code: `${SDK_MARKUP}.missing_selector_id_match`, severity: "error" },
+  ORPHANED_UPSELL_ACTION: { code: `${SDK_MARKUP}.orphaned_upsell_action`, severity: "error" },
   DOUBLE_SELECTED: { code: `${SDK_MARKUP}.double_selected`, severity: "warning" },
   TEMPLATE_DOUBLE_BRACE: { code: `${SDK_MARKUP}.template_double_brace`, severity: "warning" },
+  CHECKOUT_BUMP_IS_UPSELL: { code: `${SDK_MARKUP}.checkout_bump_is_upsell`, severity: "warning" },
   // Unknown data-next-* names are not a finding and carry no code: they are
   // information on the gate (unknown_attributes[]) and one advisory ready line.
 });
@@ -142,11 +160,22 @@ function describe(entry) {
   return `${bits.join("")}>`;
 }
 
+function describeBump(entry) {
+  const id = entry.attrs.get("id");
+  const packageId = entry.attrs.get("data-next-package-id");
+  const bits = [`<${entry.tag}`];
+  if (id) bits.push(` id="${id}"`);
+  if (packageId) bits.push(` data-next-package-id="${packageId}"`);
+  return `${bits.join("")}>`;
+}
+
 /**
  * Scan one built page. Returns findings with { code_name, code, severity,
  * page_id, file, message, detail } and the set of unknown data-next-* names.
+ * `page_type` is the route-inferred type, used only when the page declares no
+ * live, unambiguous next-page-type meta (builtPageTypeMeta).
  */
-export function scanPageMarkup({ page_id, file = null, content = "" }) {
+export function scanPageMarkup({ page_id, file = null, content = "", page_type = null }) {
   const document = parse(String(content || ""));
   const where = file || page_id;
   const findings = [];
@@ -157,10 +186,13 @@ export function scanPageMarkup({ page_id, file = null, content = "" }) {
   const selectorIds = new Set(); // ids of elements that are themselves a selector
   const templates = []; // { entry, sdkOwned }
   const referencedTemplateIds = new Set();
+  const upsellFlagged = []; // entries carrying data-next-is-upsell="true"
 
   walkElements(document, (entry) => {
     const { tag, attrs: a, ancestors } = entry;
 
+    if ((a.get("data-next-is-upsell") || "").trim().toLowerCase() === "true") upsellFlagged.push(entry);
+
     for (const [name] of a) {
       if (name.startsWith("data-next-") && !isIndexedSdkAttribute(name)) unknown.add(name);
       if (TEMPLATE_ID_ATTRIBUTES.test(name) && a.get(name)) referencedTemplateIds.add(a.get(name).trim());
@@ -181,6 +213,18 @@ export function scanPageMarkup({ page_id, file = null, content = "" }) {
       }
     }
 
+    // An ancestor, not the element itself: the enhancer looks for actions
+    // inside the container it binds.
+    if (a.has("data-next-upsell-action") && !ancestors.some((anc) => anc.attrs.has("data-next-upsell"))) {
+      const value = a.get("data-next-upsell-action") ?? "";
+      // The SDK reads add/accept as accepting the offer and skip/decline as
+      // declining it; any other value does nothing even inside a container.
+      const verb = { add: "accept", accept: "accept", skip: "decline", decline: "decline" }[value.trim().toLowerCase()] || "act on";
+      findings.push(finding("ORPHANED_UPSELL_ACTION", page_id, where,
+        `${describe(entry)} data-next-upsell-action="${value}" on ${where} has no ancestor carrying data-next-upsell. The SDK binds upsell actions only inside that container, so this one never fires and the shopper cannot ${verb} the offer. Move it inside the data-next-upsell container it belongs to.`,
+        { tag, action: value }));
+    }
+
     const action = (a.get("data-next-action") || "").trim().toLowerCase();
     if (action === "add-to-cart") {
       addToCartButtons.push({ entry, selectorId: (a.get("data-next-selector-id") || "").trim() || null });
@@ -263,6 +307,26 @@ export function scanPageMarkup({ page_id, file = null, content = "" }) {
       { template_id: id || null, snippet }));
   }
 
+  // One finding per page, naming every flagged element: the repair is the
+  // same for each (drop the flag from the bump include's markup; several
+  // starter includes write it unconditionally, so an is_upsell=false argument
+  // does not always clear it).
+  // The page type is read only when a flag is present, so a page without one
+  // is not parsed a second time.
+  const pageTypeMeta = upsellFlagged.length ? builtPageTypeMeta(content) : null;
+  // The live, unambiguous meta wins because it is what the SDK reads; the
+  // upsell gate's narrower oto-route rule (builtPageTypeOverRouteGuess) does
+  // not apply to a checkout bump.
+  const effectivePageType = upsellFlagged.length
+    ? normalizedPageTypeValue(pageTypeMeta ?? page_type)
+    : null;
+  if (effectivePageType === "checkout") {
+    const elements = upsellFlagged.map(describeBump);
+    findings.push(finding("CHECKOUT_BUMP_IS_UPSELL", page_id, where,
+      `${elements.length > 1 ? `${elements.length} order bumps` : "An order bump"} on checkout page ${where} (${elements.join(", ")}) ${elements.length > 1 ? "carry" : "carries"} data-next-is-upsell="true". A checkout bump is a pre-purchase add-on; the flag puts it on the initial order as an upsell line. The flag comes from the bump include's markup, and several starter bump includes write it unconditionally, so remove data-next-is-upsell="true" from the include in this campaign unless the line really should be billed as an upsell.`,
+      { page_type: effectivePageType, page_type_source: pageTypeMeta !== null ? "next-page-type" : "route", elements }));
+  }
+
   return { page_id, file, findings, unknown_attributes: [...unknown].sort() };
 }
 

package/src/source-html-intake.mjs

@@ -106,7 +106,7 @@ function declaredScopeSkip(page, { skipEntry = null, buildScope = null, manifest
       id: `dec_page_scope_${page.id}`,
       stage: "prepare_build",
       decision_type: "deterministic_derivation",
-      decision: `recorded CampaignSpec page "${page.id}" as template stock, declared out of source scope (${skipEntry ? "explicit source-html manifest skip entry" : 'CampaignSpec build_scope mode "partial"'}); the build stage materialises the page from ${familyLabel}'s stock page, and intake demands no design source for it`,
+      decision: `recorded CampaignSpec page "${page.id}" as template stock, declared out of source scope (${skipEntry ? "explicit source-html manifest skip entry" : 'CampaignSpec build_scope mode "partial"'}); keep the route unbuilt unless the operator opts in to materialising it from ${familyLabel}'s stock page; intake demands no design source for it`,
       confidence: "high",
       template_stock: true,
       template_family: family,
@@ -138,6 +138,122 @@ function pageRouteForPageKit(value) {
   }
 }
 
+// The SDK meta tags whose content is a route. Doctor checks the same three.
+export const SDK_ROUTING_META_TAGS = [
+  "next-success-url",
+  "next-upsell-accept-url",
+  "next-upsell-decline-url",
+];
+
+export const HOST_STRIPPED_CODE = "routing_meta.host_stripped";
+
+// A route value that carries a host in front of its path (#531): an older
+// saved Map stored `shop.example.com/route/upsell/` where the route is
+// `/route/upsell/`, and every stage that roots a route then nested the host
+// inside the campaign path. Returns `{ host, from, to }` — `to` is the rooted
+// path with any query and fragment kept — or null when the value is not
+// host-prefixed.
+//
+// Read as host-prefixed:
+//   - `http://` or `https://` URLs (any host);
+//   - protocol-relative `//<host>/...`;
+//   - bare `<host>/...`, where the first segment is followed by "/" and is
+//     `localhost`, a valid IPv4 address (each octet 0-255), any name with a
+//     `:port`, or a dotted name whose last label is 2-63 letters and not a
+//     page or script extension (ROUTE_FILE_EXTENSION: `html`, `htm`,
+//     `shtml`, `php`, `asp`, `aspx`, `jsp`, `cgi`; not `pl`, which is also
+//     Poland's country-code domain), such as
+//     `shop.example.com`. `//<host>/...` takes the same hosts.
+// Everything else is a route and is left to the existing route checks: a
+// rooted `/...` value, a first segment with no dot (`route/x/`), a dotted
+// segment whose last label is not all letters (`v1.2/offer/`), a dotted
+// quad with an octet over 255 (`300.1.2.3/offer/`), a page or script
+// filename (`checkout.html`, `index.php/checkout/`), and a bare host with no
+// path after it.
+// `keepAbsolute: true` leaves an absolute http(s) URL alone: it is a valid
+// SDK routing meta target, and projection already converts an absolute
+// page_url to its path, so doctor accepts both; only the bare and
+// protocol-relative forms count.
+export function parseHostPrefixedRoute(value, { keepAbsolute = false } = {}) {
+  if (typeof value !== "string") return null;
+  const raw = value.trim();
+  if (!raw || (raw.startsWith("/") && !raw.startsWith("//"))) return null;
+  const scheme = /^([A-Za-z][A-Za-z0-9+.-]*):\/\//.exec(raw);
+  if (scheme) {
+    if (keepAbsolute || !/^https?$/i.test(scheme[1])) return null;
+    return splitHostPrefix(value, raw.slice(scheme[0].length), { requireHostShape: false });
+  }
+  if (raw.startsWith("//")) return splitHostPrefix(value, raw.slice(2), { requireHostShape: true });
+  return splitHostPrefix(value, raw, { requireHostShape: true, requirePath: true });
+}
+
+function splitHostPrefix(from, rest, { requireHostShape, requirePath = false }) {
+  const end = rest.search(/[/?#]/);
+  const host = end === -1 ? rest : rest.slice(0, end);
+  const tail = end === -1 ? "" : rest.slice(end);
+  if (!host || /\s/.test(host)) return null;
+  if (requirePath && !tail.startsWith("/")) return null;
+  if (requireHostShape && !looksLikeHost(host)) return null;
+  return { host, from, to: tail.startsWith("/") ? tail : `/${tail}` };
+}
+
+// A dotted first segment ending in one of these is a page or script filename
+// (`index.php/checkout/`), not a host.
+const ROUTE_FILE_EXTENSION = /^(?:html?|shtml|php|aspx?|jsp|cgi)$/i;
+
+function looksLikeHost(segment) {
+  if (/^localhost(?::\d+)?$/i.test(segment)) return true;
+  if (/^\d{1,3}(?:\.\d{1,3}){3}$/.test(segment) && segment.split(".").every((octet) => Number(octet) <= 255)) return true;
+  if (/^[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)*:\d+$/.test(segment)) return true;
+  const labels = /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?)+$/.test(segment)
+    ? segment.split(".")
+    : null;
+  if (!labels) return false;
+  const last = labels[labels.length - 1];
+  return /^[A-Za-z]{2,63}$/.test(last) && !ROUTE_FILE_EXTENSION.test(last);
+}
+
+// Intake normalisation (#531): every host-prefixed page_url, and every
+// host-prefixed SDK routing meta tag value, in funnels[].pages[] and the
+// funnel_pages[] mirror, reduced to its rooted path before anything reads the
+// spec. Returns the spec unchanged (the same object) with no evidence when
+// nothing carries a host; otherwise a copy and one evidence record per changed
+// value, `{ code, page_id, field, from, to }`, where `from` is the value
+// exactly as the Map or file held it.
+export function stripHostPrefixedRoutes(spec) {
+  const evidence = [];
+  if (!spec || typeof spec !== "object") return { spec, evidence };
+  const copy = JSON.parse(JSON.stringify(spec));
+  const lists = [];
+  if (Array.isArray(copy.funnels)) {
+    copy.funnels.forEach((funnel, funnelIndex) => {
+      if (Array.isArray(funnel?.pages)) lists.push([`funnels[${funnelIndex}].pages`, funnel.pages]);
+    });
+  }
+  if (Array.isArray(copy.funnel_pages)) lists.push(["funnel_pages", copy.funnel_pages]);
+  for (const [label, pages] of lists) {
+    pages.forEach((page, pageIndex) => {
+      if (!page || typeof page !== "object") return;
+      const at = `${label}[${pageIndex}]`;
+      const pageId = typeof page.id === "string" ? page.id : null;
+      const stripped = parseHostPrefixedRoute(page.page_url);
+      if (stripped) {
+        page.page_url = stripped.to;
+        evidence.push({ code: HOST_STRIPPED_CODE, page_id: pageId, field: `${at}.page_url`, from: stripped.from, to: stripped.to });
+      }
+      const metaTags = page.sdk_hints?.meta_tags;
+      if (!metaTags || typeof metaTags !== "object" || Array.isArray(metaTags)) return;
+      for (const tag of SDK_ROUTING_META_TAGS) {
+        const meta = parseHostPrefixedRoute(metaTags[tag], { keepAbsolute: true });
+        if (!meta) continue;
+        metaTags[tag] = meta.to;
+        evidence.push({ code: HOST_STRIPPED_CODE, page_id: pageId, field: `${at}.sdk_hints.meta_tags.${tag}`, from: meta.from, to: meta.to });
+      }
+    });
+  }
+  return evidence.length ? { spec: copy, evidence } : { spec, evidence };
+}
+
 function applyManifestToPages(specPages, manifest, manifestPath, { buildScope = null, templateFamily = null } = {}) {
   const mappings = [];
   const prompts = [];

package/src/source-html-manifest.mjs

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 
@@ -95,10 +96,16 @@ export function readSourceHtmlManifestFile(sourceRoot, { manifestPath = null } =
   return { ...readManifestAt(resolvedPath), explicit: Boolean(explicit) };
 }
 
+// One read: the manifest is parsed from, and hashed over, the same bytes. An
+// edit that lands on disk after the read changes neither, so the sha256 a
+// consumer records always describes what was parsed (#501).
 function readManifestAt(manifestPath) {
   let manifest;
+  let sha256;
   try {
-    manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+    const bytes = readFileSync(manifestPath);
+    sha256 = createHash("sha256").update(bytes).digest("hex");
+    manifest = JSON.parse(bytes.toString("utf8"));
   } catch (error) {
     return {
       manifest: null,
@@ -125,7 +132,7 @@ function readManifestAt(manifestPath) {
   const warnings = (validation.warnings || []).map(
     (entry) => `Source-html manifest at ${manifestPath}: [${entry.code}] ${entry.message}`,
   );
-  return { manifest, path: manifestPath, warning: null, warnings, validation };
+  return { manifest, path: manifestPath, sha256, warning: null, warnings, validation };
 }
 
 function validateManifestPage(entry, index, add, addWarning = () => {}) {

package/src/stage-ledger.mjs

@@ -3,6 +3,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { markDoctorSidecarStale, writeDoctorSidecar, writeJsonAtomic } from "./doctor-sidecar.mjs";
 import { STATUS as QA_STATUS } from "./qa-verdict.mjs";
 import { isPlainObject, normalizeString as optionalString } from "./repo-scan.mjs";
+import { withTargetLockSync } from "./target-lock.mjs";
 import {
   ASSEMBLY_REPORT_STAGE_KEYS,
   NEXT_STAGE_CONTRACTS,
@@ -425,6 +426,16 @@ export function assemblyReportMatchesPacket(report, packet) {
  * (waivers, evidence merges) pass no `stage`: they require the report to
  * exist and bind its identity themselves.
  *
+ * The read-modify-write runs under the per-target writer lock that
+ * prepare-build holds (src/target-lock.mjs, #501), so a stage producer's edit
+ * never lands between prepare-build's pre-publish evidence re-check and its
+ * publication; inside prepare-build's own critical section it enters
+ * directly. A workspace without `targetRepo` (only possible with an explicit
+ * refreshDoctor and no stale stamp) names no target to lock and runs as is.
+ * `lockBudgetMs` bounds the wait (default: the target lock budget). A caller
+ * whose mutate always returns null (a preview) passes `lock: false`: it
+ * writes nothing, so it takes no lock and creates no lock files.
+ *
  * Returns `{ written, skipped, report, reportPath, doctorOutPath }` where
  * `skipped` is `null`, `"absent"`, `"identity"` or `"unchanged"` and `report`
  * is what is now on disk (the mutated report when written, else the one read,
@@ -435,6 +446,10 @@ export function commitAssemblyReport(workspace, mutate, {
   staleReason = null,
   command = null,
   stage = null,
+  lockBudgetMs,
+  // lock: false skips the target lock entirely; only for callers that write
+  // nothing (the waiver dry-run preview). A real commit must take the lock.
+  lock = true,
 } = {}) {
   const hasRefresh = typeof refreshDoctor === "function";
   const hasStale = typeof staleReason === "string" && staleReason.trim();
@@ -453,6 +468,19 @@ export function commitAssemblyReport(workspace, mutate, {
   if (hasRefresh && !doctorOutPath) throw new TypeError("commitAssemblyReport requires a workspace with doctorOutPath to refresh the doctor sidecar.");
   if (hasStale && !targetRepo) throw new TypeError("commitAssemblyReport requires a workspace with targetRepo to stamp the doctor sidecar stale.");
 
+  const commit = () => commitAssemblyReportUnderLock(workspace, mutate, {
+    refreshDoctor, staleReason, command, stage, hasRefresh, reportPath, doctorOutPath, targetRepo,
+  });
+  if (!targetRepo || lock === false) return commit();
+  return withTargetLockSync(targetRepo, commit, {
+    command: command.trim(),
+    ...(lockBudgetMs === undefined ? {} : { budgetMs: lockBudgetMs }),
+  });
+}
+
+function commitAssemblyReportUnderLock(workspace, mutate, {
+  refreshDoctor, staleReason, command, stage, hasRefresh, reportPath, doctorOutPath, targetRepo,
+}) {
   const outcome = { written: false, skipped: null, report: null, reportPath, doctorOutPath };
   const finish = () => {
     if (hasRefresh) {