@nextcommerce/campaigns-os 1.43.1 → 1.43.2

package/src/qa-build-scope.mjs

@@ -0,0 +1,47 @@
+import { resolveBuiltSiteScope } from "./built-site-scope.mjs";
+import { runtimeRelativeRouteForSpecValue } from "./route-identity.mjs";
+
+// Use the recorded declaration, not a doctor's cached derived scope: failed
+// intake also writes skip_reason mappings, which must never hide missing pages.
+export function applyQaBuildScope(topologies, { packet, report, targetRepo, publicRouteSlug } = {}) {
+  const declared = report?.stages?.prepare_build?.declared_out_of_scope;
+  if (!Array.isArray(declared) || !packet) return { topologies, excludedPages: [] };
+  const declaredIds = new Set(declared.map(page => page?.page_id));
+  const skippedIds = new Set((packet.source_html?.pages || [])
+    .filter(page => declaredIds.has(page.page_id) && !page.path && typeof page.skip_reason === "string" && page.skip_reason.trim())
+    .map(page => page.page_id));
+  if (!skippedIds.size) return { topologies, excludedPages: [] };
+  const built = targetRepo ? resolveBuiltSiteScope(targetRepo, { slug: publicRouteSlug }) : null;
+  const normalizeRoute = route => runtimeRelativeRouteForSpecValue(route, publicRouteSlug).replace(/^\/+|\/+$/g, "").replace(/(?:^|\/)index\.html$/, "").replace(/\/$/, "");
+  const builtRoutes = new Set((built?.pages || []).map(page => normalizeRoute(page.route)));
+  const excludedPages = [];
+  const scoped = topologies.map(topology => ({
+    ...topology,
+    partial_build_scope: topology.pages.some(page => skippedIds.has(page.page_id)),
+    pages: topology.pages.filter(page => {
+      if (!skippedIds.has(page.page_id)) return true;
+      // Without a resolved URL we cannot prove which output file represents
+      // this page. Keep it in QA so unresolved/materialized pages are not
+      // silently hidden as unbuilt declarations.
+      if (!page.url) return true;
+      // An explicitly materialized stock page rejoins QA. A declaration alone
+      // is not an instruction to build it, nor proof that it exists.
+      let route;
+      try { route = new URL(page.url).pathname; } catch { return true; }
+      if (builtRoutes.has(normalizeRoute(route))) return true;
+      excludedPages.push(page);
+      return false;
+    }),
+  }));
+  return { topologies: scoped, excludedPages };
+}
+
+export function specForQaScope(spec, excludedPages = []) {
+  const excluded = new Set(excludedPages.map(page => page.page_id));
+  if (Array.isArray(spec.funnel_pages) && !spec.funnels?.length) {
+    return { ...spec, funnel_pages: spec.funnel_pages.filter(page => !excluded.has(page.id)) };
+  }
+  return { ...spec, funnels: (spec.funnels || []).map(funnel => ({
+    ...funnel, pages: (funnel.pages || []).filter(page => !excluded.has(page.id)),
+  })) };
+}

package/src/qa-node.mjs

@@ -1,6 +1,7 @@
 import { campaignSpecIdentity, resolveCampaignIdentity, campaignIdentitiesMatch } from "./spec-source-identity.mjs";
-import { expectedBinding, createBindingScriptLoader, observeBinding, bindingAssertion } from './qa-binding-evidence.mjs';
+import { expectedBinding, createBindingScriptLoader, observeBinding, bindingAssertion, scriptParseAssertion } from './qa-binding-evidence.mjs';
 import { shellToken } from "./shell-token.mjs";
+import { applyQaBuildScope, specForQaScope } from "./qa-build-scope.mjs";
 import { requiredActionText } from "./gate-actions.mjs";
 import { parseOrderPathDepthFlag } from "./proof-policy.mjs";
 import {
@@ -29,13 +30,22 @@ const PACKAGE_ROOT = installModeResolve(installModeDirname(installModeFileUrl(im
 function cmd(verb, rest = "") {
   return `${invocationPrefixFor(PACKAGE_ROOT)} ${verb}${rest ? ` ${rest}` : ""}`;
 }
-import { runAnalyticsCorrectnessChecks, runAnalyticsParityChecks, runBrowserChecks, runBrowserTestOrders, testEmail, validatedOrderCreationLimit } from "./qa-browser.mjs";
+import { isSameAnalyticsCapturePage, runAnalyticsCorrectnessChecks, runAnalyticsParityChecks, runBrowserChecks, runBrowserTestOrders, testEmail, validatedOrderCreationLimit } from "./qa-browser.mjs";
 import { assessReceiptPurchase } from "./qa-analytics-correctness.mjs";
 import { createVerdict, isFindingAssertion, QA_ASSERTION_FAMILY_VOCABULARY, SESSION_ENDING_DISPOSITIONS, SEVERITY, STATUS, validateVerdict } from "./qa-verdict.mjs";
 import { normalizeSdkMetaName, lookupSdkIgnoredMetaTag } from "./sdk-meta-tags.mjs";
 import { annotateQaAssertionCauses, formatCauseReportLines, formatCauseTag } from "./finding-cause.mjs";
 import { promoteQaVerdict, writeQaSidecar } from "./qa-sidecar.mjs";
 import { publishQaVerdict, qaPortalUrl, qaVerdictPublishBlock, QA_VERDICT_PUBLISHERS, skippedQaVerdictPublish } from "./qa-verdict-publish.mjs";
+import {
+  isLocalServePacket,
+  LOCAL_PROOF_BUILD_ENVIRONMENT,
+  LOCAL_PROOF_BUILD_ENVIRONMENT_FIELD,
+  LOCAL_PROOF_PARITY_FIELD,
+  recordedBuildEnvironment,
+  recordedProductionParity,
+} from "./local-proof.mjs";
+import { isLoopbackHostname } from "./remit.mjs";
 import { publishStoredVerdict, qaPublishTextLines, QA_PUBLISH_EXIT_CODES } from "./qa-publish.mjs";
 // Shared outgoing-edge resolver, so QA expectations and build-time wiring
 // cannot drift on which declared routing field wins.
@@ -455,12 +465,22 @@ async function resolveQaInputs(args, {
     hiddenEagerMediaGate,
   });
   const qaWaivers = resolveQaWaivers({ packetPath, report: checkpointPreflight?.runtimeReport });
+  const qaScope = applyQaBuildScope(topologies, {
+    packet, report: checkpointPreflight?.runtimeReport,
+    targetRepo: checkpointPreflight?.targetRepo, publicRouteSlug,
+  });
   const brandContract = loadBrandContract(templateFamily);
+  const localServeAnalytics = resolveLocalServeAnalytics({
+    packet,
+    report: checkpointPreflight?.runtimeReport,
+    captureUrl: analyticsCaptureTarget.url || baseUrl,
+  });
   return {
     themeGate,
     polishGate,
     qaWaivers,
     analyticsCaptureTarget,
+    localServeAnalytics,
     brandContract: brandContract.contract,
     brandContractStatus: brandContract.status,
     packetPath,
@@ -481,7 +501,8 @@ async function resolveQaInputs(args, {
     specHash,
     templateFamily,
     commerceStructureContract,
-    topologies,
+    topologies: qaScope.topologies,
+    excludedPages: qaScope.excludedPages,
     checkpointGates: checkpointPreflight?.checkpointGates || nonPacketCheckpointGates(),
     // The report the checkpoint gates were evaluated on, and the target repo
     // whose default it may or may not be: what the printed remediation names.
@@ -2130,6 +2151,13 @@ async function runQa(args, options = {}) {
   // Fail-fast before anything resolves or launches. The authoritative check
   // lives on the creation budget itself, which every browser path builds.
   refuseBadOrderCreationLimit(args);
+  // Match dispatch: an active browser mode takes precedence over legacy API
+  // diagnostics. Only the selected legacy path requires a cart and API mode.
+  const browserMode = String(args["test-order"] || "off").toLowerCase();
+  const legacyMode = String(args["legacy-api-test-order"] || "off").toLowerCase();
+  if (browserMode === "off" && legacyMode !== "off") {
+    refusing(() => legacyTestOrderInputs({ ...args, "test-order": legacyMode }));
+  }
   const resolved = await resolveQaInputs(args);
   return runResolvedQa(args, resolved, options);
 }
@@ -2207,12 +2235,19 @@ async function runResolvedQa(args, resolved, { runSessionActive = false } = {})
 
   const assertions = [
     ...checkpointAssertions,
+    ...(resolved.excludedPages || []).map(page => assertion({
+      id: `build-scope:${page.page_id}`, family: "funnel-flow", page,
+      status: STATUS.SKIPPED,
+      expected: "Only built routes are preview-QA targets",
+      actual: "out_of_build_scope",
+      evidence: { reason: "out_of_build_scope" },
+    })),
     ...(polishGate?.owned_checkpoint_only ? [] : [polishGateAssertion(polishGate)]),
     themeGateAssertion(gate),
   ];
   const contractAssertion = templateBrandContractAssertion(resolved);
   if (contractAssertion) assertions.push(contractAssertion);
-  const commercialPlanning = planCommercialParity(resolved.rawSpec || resolved.spec);
+  const commercialPlanning = planCommercialParity(specForQaScope(resolved.rawSpec || resolved.spec, resolved.excludedPages));
   const sourceLoader = createPageSourceLoader({ authCookie: args["auth-cookie"] });
   const commercialIds = new Set(commercialPlanning.pages
     .filter((page) => page?.id !== undefined && page?.id !== null)
@@ -2297,13 +2332,17 @@ async function runAnalyticsOrderSequence({ args, resolved, runId, assertions },
   } else if (analyticsLeg === "run") {
     assertions.push(...await operations.runInventory(args, analyticsContract || {}, {
       target: resolved.analyticsCaptureTarget,
+      ...analyticsCaptureScope(resolved),
     }));
   }
 
-  // Analytics parity is unchanged and remains opt-in between root inventory
-  // and typed-card receipt capture.
+  // Analytics parity remains opt-in between root inventory and typed-card
+  // receipt capture. #503: it gets the same partial-scope capture options.
   if (stringArg(args["analytics-baseline"])) {
-    assertions.push(...await operations.runParity(args, { target: resolved.analyticsCaptureTarget }));
+    assertions.push(...await operations.runParity(args, {
+      target: resolved.analyticsCaptureTarget,
+      ...analyticsCaptureScope(resolved),
+    }));
   }
 
   const result = await operations.runOrders({
@@ -2316,9 +2355,130 @@ async function runAnalyticsOrderSequence({ args, resolved, runId, assertions },
   if (analyticsLeg === "run") {
     assertions.push(operations.assessReceipt(result.receiptAnalytics, { waivers: resolved.qaWaivers }));
   }
+  applyLocalServeAnalyticsReview(assertions, resolved.localServeAnalytics);
   return result.orders;
 }
 
+// #483: local proof mode (deploy.target local-serve) renders the DEVELOPMENT
+// environment on purpose, and the starter templates gate every vendor loader
+// on it. A pixel that did not fire on that render is the render's design, not
+// the campaign's defect, so fire-dependent analytics checks become manual
+// review there instead of blockers. Only a run whose capture is actually
+// served from loopback qualifies: the same packet QA'd against the PR preview
+// (--base-url <preview>) is a production render and keeps its blockers, which
+// is the follow-up every downgraded assertion names.
+// The render itself must be on record, too: the exception applies only when
+// stages.assembly.evidence.build_environment says "development". A production
+// build served on localhost, or a build whose environment was never recorded,
+// keeps its blockers; the build-environment preflight only warns about those
+// states, so this gate cannot lean on it.
+// data-layer-purchase is deliberately not downgraded: it counts the SDK's own
+// dl_purchase, which the development render still pushes, so a miss on
+// localhost can be a real defect and keeps blocking.
+// A failure that is a capture or runner error, not "did not fire", is never
+// downgraded either: the environment gate explains a silent pixel, not an
+// unmeasured one. tag:* and oob:* are only emitted from a completed capture (a
+// failed capture is analytics-correctness:runner, which is outside this set);
+// purchase-fires names its unmeasured receipts in capture_error_plan_ids.
+const LOCAL_SERVE_ANALYTICS_REASON = "local_serve_development_render";
+const FIRE_DEPENDENT_ANALYTICS_ID = /^analytics-correctness:(?:tag:|oob:|purchase-fires(?::|$))/;
+
+function isCaptureErrorFailure(item) {
+  const evidence = item?.evidence;
+  if (evidence && typeof evidence === "object" && evidence.error_code) return true;
+  if (/^analytics-correctness:purchase-fires(?::|$)/.test(String(item?.id || ""))) {
+    // Downgrade only a Purchase reading that positively records no capture
+    // error; a missing list is an unknown, not a clean measurement.
+    const errors = evidence?.capture_error_plan_ids;
+    return !Array.isArray(errors) || errors.length > 0;
+  }
+  return false;
+}
+
+function isLoopbackUrl(value) {
+  if (typeof value !== "string" || !value.trim()) return false;
+  let hostname = null;
+  try { hostname = new URL(value).hostname; } catch { hostname = null; }
+  return !!hostname && isLoopbackHostname(hostname);
+}
+
+// #500: run-level eligibility is computed from the campaign-root URL, but the
+// page a failing check measured is not always that root. The #493 inventory
+// fallback can capture a built entry whose page.url is a remote production
+// preview, and a localhost root can redirect to a production host. So each
+// failing check is downgraded only when the page it measured is on record as
+// loopback:
+// - tag:* / oob:* — the check's own url and the inventory capture's
+//   capture_page.url (both the URL requested) AND the capture's final_url
+//   (page.url() after redirects and settling) must all be loopback;
+// - purchase-fires — every judged receipt's receipt_url (the order's final
+//   page URL, recorded before analytics settle) AND its receipt_document_url
+//   (page.url() read after the receipt analytics settled and were collected)
+//   must be loopback, and there must be one. A receipt that redirects to a
+//   hosted page during the settle window measured that host, not loopback.
+// A measured location that is missing or unparseable keeps the blocker.
+function localServeMeasuredOnLoopback(item, assertions) {
+  const id = String(item?.id || "");
+  if (/^analytics-correctness:purchase-fires(?::|$)/.test(id)) {
+    const receipts = item?.evidence?.receipts;
+    return Array.isArray(receipts) && receipts.length > 0
+      && receipts.every((receipt) => isLoopbackUrl(receipt?.receipt_url)
+        && isLoopbackUrl(receipt?.receipt_document_url));
+  }
+  const ownUrl = item?.evidence?.url ?? item?.url;
+  if (!isLoopbackUrl(ownUrl)) return false;
+  const capture = assertions.find((entry) => entry?.id === "analytics-correctness:capture" && entry.status === STATUS.PASS);
+  const capturePage = capture?.evidence?.capture_page;
+  return isLoopbackUrl(capturePage?.url) && isLoopbackUrl(capture?.evidence?.final_url);
+}
+
+function resolveLocalServeAnalytics({ packet, report, captureUrl }) {
+  if (!isLocalServePacket(packet)) return null;
+  if (!isLoopbackUrl(String(captureUrl ?? ""))) return null;
+  if (recordedBuildEnvironment(report) !== LOCAL_PROOF_BUILD_ENVIRONMENT) return null;
+  const parity = recordedProductionParity(report);
+  return {
+    deploy_target: "local-serve",
+    build_environment: { field: LOCAL_PROOF_BUILD_ENVIRONMENT_FIELD, value: LOCAL_PROOF_BUILD_ENVIRONMENT },
+    production_parity: parity
+      ? {
+          field: LOCAL_PROOF_PARITY_FIELD,
+          status: typeof parity.status === "string" ? parity.status : null,
+          checked_at: typeof parity.checked_at === "string" ? parity.checked_at : null,
+          page_count: Number.isFinite(parity.page_count) ? parity.page_count : null,
+          gated_hosts: [...new Set((Array.isArray(parity.pages) ? parity.pages : [])
+            .flatMap((page) => (Array.isArray(page?.gated_hosts) ? page.gated_hosts : []))
+            .filter((host) => typeof host === "string"))].sort(),
+        }
+      : { field: LOCAL_PROOF_PARITY_FIELD, status: "not_recorded" },
+  };
+}
+
+function applyLocalServeAnalyticsReview(assertions, localServe) {
+  if (!localServe) return;
+  const parityPassed = localServe.production_parity?.status === "pass";
+  for (const [index, item] of assertions.entries()) {
+    if (item?.status !== STATUS.FAIL || !FIRE_DEPENDENT_ANALYTICS_ID.test(String(item.id || ""))) continue;
+    if (isCaptureErrorFailure(item)) continue;
+    if (!localServeMeasuredOnLoopback(item, assertions)) continue;
+    assertions[index] = {
+      ...item,
+      status: STATUS.MANUAL_REVIEW,
+      severity: SEVERITY.WARN,
+      actual: `${item.actual ?? "did not fire"}; local-serve development render gates vendor loaders out, so re-run against the PR preview with --base-url <preview-url>`,
+      evidence: {
+        ...(item.evidence || {}),
+        reason: LOCAL_SERVE_ANALYTICS_REASON,
+        local_serve_status: STATUS.FAIL,
+        build_environment: localServe.build_environment,
+        follow_up: "Re-run qa run against the PR preview (a production render) with --base-url <preview-url>; that run gates these checks.",
+        production_parity: localServe.production_parity,
+        ...(parityPassed ? {} : { production_parity_note: "No passing page-kit parity is recorded, so nothing yet shows the production render carries these loaders." }),
+      },
+    };
+  }
+}
+
 async function finalizeQaRun({ args, resolved, runId, startedAt, assertions, testOrders, commercial = null, runSessionActive = false, browser = null }) {
   const entryUrls = deriveEntryUrls(resolved.topologies);
   const pageUrls = derivePageUrls(resolved.topologies);
@@ -2447,6 +2607,38 @@ async function finalizeQaRun({ args, resolved, runId, startedAt, assertions, tes
   };
 }
 
+// #493: a full build captures the campaign root. A partial build captures it
+// only when a built, in-scope page is served there; otherwise the root is
+// whatever the host answers (a directory index, a generic fallback) and must
+// not be measured. Either way the built entry pages (the same first in-scope
+// entry #482 selects) are the fallback when the root cannot be captured.
+// #503: "served there" is the page identity the capture leg deduplicates by
+// (isSameAnalyticsCapturePage): a query-routed page on the root's path
+// (`/campaign/?step=checkout`) is not the root, so it cannot put the root in
+// scope.
+function analyticsCaptureScope(resolved) {
+  const rootUrl = rootCaptureUrl(resolved?.analyticsCaptureTarget?.url);
+  const topologies = topologyList(resolved?.topologies);
+  const partial = topologies.some((topology) => topology?.partial_build_scope)
+    || (Array.isArray(resolved?.excludedPages) && resolved.excludedPages.length > 0);
+  const rootInScope = !rootUrl || !partial || topologies.some((topology) =>
+    (Array.isArray(topology?.pages) ? topology.pages : []).some((page) =>
+      typeof page?.url === "string" && isSameAnalyticsCapturePage(page.url, rootUrl)));
+  return {
+    rootInScope,
+    fallbackTargets: deriveEntryUrls(resolved?.topologies),
+  };
+}
+
+function rootCaptureUrl(value) {
+  if (typeof value !== "string" || !value.trim()) return null;
+  try {
+    return new URL(value).toString();
+  } catch {
+    return null;
+  }
+}
+
 const ENTRY_PAGE_TYPES = new Set([
   "entry",
   "presell",
@@ -2464,7 +2656,9 @@ function deriveEntryUrls(topologies) {
   for (const topology of topologyList(topologies)) {
     const pages = Array.isArray(topology?.pages) ? topology.pages.filter((page) => page?.url) : [];
     if (!pages.length) continue;
-    const page = pages.find(isEntryLikePage) || pages[0];
+    // #482: a partial build enters at its first in-scope page, which can be
+    // an opted-in select or checkout rather than a later landing/presell.
+    const page = topology.partial_build_scope ? pages[0] : pages.find(isEntryLikePage) || pages[0];
     entries.push({
       funnel_id: topology.funnel_id || "default",
       funnel_name: topology.funnel_name || topology.funnel_id || "default",
@@ -2558,7 +2752,10 @@ async function runPageChecks(page, args, {
   }
 
   const source = await sourceLoader(page);
-  assertions.push(bindingAssertion(page, await observeBinding({ source, page, expected: bindingExpected, scriptLoader: bindingScriptLoader })));
+  const scriptParseFailures = [];
+  assertions.push(bindingAssertion(page, await observeBinding({ source, page, expected: bindingExpected, scriptLoader: bindingScriptLoader, parseFailures: scriptParseFailures })));
+  const scriptParse = scriptParseAssertion(page, scriptParseFailures);
+  if (scriptParse) assertions.push(assertion({ ...scriptParse, page }));
   if (!source.ok) {
     const isHttpStatus = source.error_code === "http_status";
     assertions.push(assertion({
@@ -2728,15 +2925,12 @@ async function maybeRunLegacyApiTestOrders({ args, resolved, runId, assertions }
   const apiKey = stringArg(args["api-key"]) || process.env.QA_CAMPAIGNS_API_KEY;
   const apiBase = stringArg(args["campaigns-api-base"]) || process.env.CAMPAIGNS_API_BASE;
   if (!apiKey || !apiBase) throw new Error("Legacy direct API test orders require --api-key/QA_CAMPAIGNS_API_KEY and --campaigns-api-base/CAMPAIGNS_API_BASE.");
-  const cart = parseCart(args.cart);
-  if (!cart.length) throw new Error("--test-order requires --cart package_id:quantity pairs.");
+  const { cart, paths } = legacyTestOrderInputs(args);
   const checkout = findPage(resolved.topologies, "checkout");
   if (!checkout?.url) throw new Error("--test-order requires a checkout page URL.");
   const upsell = findPage(resolved.topologies, "upsell");
-  const paths = mode === "both" ? ["accept", "decline"] : [mode];
   const orders = [];
   for (const path of paths) {
-    if (!["accept", "decline"].includes(path)) throw new Error(`Unknown --test-order mode: ${mode}`);
     const create = await createTestOrder({ apiBase, apiKey, cart, runId, successUrl: checkout.expected_next_url || upsell?.url || checkout.url, spec: resolved.spec, args });
     const verification = { expected_line_count: cart.length, actual_line_count: 0, diff: [], verified: false };
     if (!create.ok) {
@@ -3604,6 +3798,14 @@ function decodeHtml(value) {
     .replace(/&gt;/g, ">");
 }
 
+function legacyTestOrderInputs(args) {
+  const cart = typeof args.cart === "string" ? parseCart(args.cart) : [];
+  if (!cart.length) throw new Error("--test-order requires --cart package_id:quantity pairs.");
+  const mode = String(args["test-order"] || "off").toLowerCase();
+  if (!["accept", "decline", "both"].includes(mode)) throw new Error(`Unknown --test-order mode: ${mode}`);
+  return { cart, paths: mode === "both" ? ["accept", "decline"] : [mode] };
+}
+
 function parseCart(value) {
   if (!value) return [];
   return String(value).split(",").map((part) => {
@@ -3649,6 +3851,9 @@ export const __qaNodeTestHooks = Object.freeze({
   resolveQaInputs,
   runResolvedQa,
   runPageChecks,
+  analyticsCaptureScope,
+  resolveLocalServeAnalytics,
+  applyLocalServeAnalyticsReview,
   analyticsCorrectnessLegDecision,
   analyticsCorrectnessDisabledAssertion,
   runAnalyticsOrderSequence,

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,

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

package/src/target-lock.mjs

@@ -0,0 +1,54 @@
+// The per-target writer lock (#496, #501). prepare-build holds it from reading
+// its inputs through publishing the packet, context and report; the stage
+// writers (every commitAssemblyReport) hold it for their read-modify-write of
+// the Assembly Report, so no stage evidence lands between prepare-build's
+// pre-publish re-check and its rename. It lives beside the Design Source
+// Package, inside the input directory prepare-build's writes already cover.
+import { existsSync, mkdirSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { DESIGN_SOURCE_PACKAGE_REL_PATH } from "./design-source-package.mjs";
+import { withDirectoryLock, withDirectoryLockSync } from "./directory-lock.mjs";
+
+// Generous: a live holder is doing ordinary local work, and a holder that
+// died is recovered by pid.
+export const TARGET_LOCK_BUDGET_MS = 60000;
+
+export function targetLockPath(targetRepo) {
+  const designSourcePackagePath = resolve(targetRepo, DESIGN_SOURCE_PACKAGE_REL_PATH);
+  return join(dirname(designSourcePackagePath), `.${basename(designSourcePackagePath)}.lock`);
+}
+
+// `command` names the waiting command. The lock does not record which command
+// holds it, only a pid, so the holder is described generically. A lock with
+// no owner record is called out on its own: it is never taken over, and the
+// operator needs to know it will not clear by waiting.
+function unavailable(targetRepo, lockPath, command) {
+  return (error) => {
+    if (error?.code !== "EEXIST") {
+      return new Error(`${command} could not take the target lock at ${lockPath}${error?.code ? ` (${error.code})` : ""}: ${error?.message}`, { cause: error });
+    }
+    if (existsSync(lockPath) && !existsSync(join(lockPath, "owner.json"))) {
+      return new Error(
+        `${command}: the target lock at ${lockPath} has no owner record, so it is never taken over automatically `
+        + "(an older campaigns-os release or an interrupted run left it). "
+        + `Confirm no campaigns-os process is working on ${targetRepo}, then remove that lock directory and retry.`,
+      );
+    }
+    return new Error(
+      `${command}: another campaigns-os command is writing ${targetRepo} (lock ${lockPath}). `
+      + "Retry after it finishes. If a run was interrupted, confirm no campaigns-os process is working on this target before removing that lock directory.",
+    );
+  };
+}
+
+export function withTargetLock(targetRepo, fn, { command = "campaigns-os", budgetMs = TARGET_LOCK_BUDGET_MS } = {}) {
+  const lockPath = targetLockPath(targetRepo);
+  mkdirSync(dirname(lockPath), { recursive: true });
+  return withDirectoryLock(lockPath, fn, { budgetMs, unavailable: unavailable(targetRepo, lockPath, command) });
+}
+
+export function withTargetLockSync(targetRepo, fn, { command = "campaigns-os", budgetMs = TARGET_LOCK_BUDGET_MS } = {}) {
+  const lockPath = targetLockPath(targetRepo);
+  mkdirSync(dirname(lockPath), { recursive: true });
+  return withDirectoryLockSync(lockPath, fn, { budgetMs, unavailable: unavailable(targetRepo, lockPath, command) });
+}

package/src/template-brand-contract.mjs

@@ -327,6 +327,22 @@ export function paymentChromeAssetHashes(chrome, { label = "template brand contr
   return byBasename;
 }
 
+// The starter templates' payment-logos.html partial renders one
+// <img data-payment-logo="<method>"> per method and keeps it `hidden` until the
+// campaign offers that method (server render, then payment-logos.js on
+// next:initialized; payment_flags.show_<method>: true forces it visible). A
+// hidden logo is the template gating the method, not residue, so both the
+// static scan and browser QA drop those tags before matching. A visible one
+// (forced on, or revealed at runtime) stays in and is judged like any chrome.
+const PAYMENT_LOGO_IMG_TAG = /<img\b[^>]*\sdata-payment-logo\s*=[^>]*>/gi;
+// Boolean attribute: present with any value (hidden, hidden="", hidden="true", …) means hidden.
+const HIDDEN_ATTRIBUTE = /\shidden(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'=<>`]+))?(?=[\s/>])/i;
+
+export function withoutHiddenPaymentLogos(html) {
+  const text = typeof html === "string" ? html : "";
+  return text.replace(PAYMENT_LOGO_IMG_TAG, (tag) => (HIDDEN_ATTRIBUTE.test(tag) ? "" : tag));
+}
+
 // Pure, static: the markers in rendered checkout HTML that say a payment method
 // shipped. Three sources, in order of authority: the SDK-owned
 // data-next-payment-method attribute every starter-template payment-methods
@@ -338,7 +354,7 @@ export function paymentChromeAssetHashes(chrome, { label = "template brand contr
 // browser QA, which fetches them to attribute the mark; a static scan cannot
 // tell a paypal strip from a card-only one by its filename.
 export function paymentMethodMarkupMatches(html, method, chrome = null) {
-  const text = typeof html === "string" ? html : "";
+  const text = withoutHiddenPaymentLogos(html);
   const canonical = String(method || "").toLowerCase().replace(/[\s-]+/g, "_");
   if (!canonical) return [];
   const matches = [];