@nextcommerce/campaigns-os 1.41.2 → 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,5 +1,7 @@
-import { expectedBinding, createBindingScriptLoader, observeBinding, bindingAssertion } from './qa-binding-evidence.mjs';
+import { campaignSpecIdentity, resolveCampaignIdentity, campaignIdentitiesMatch } from "./spec-source-identity.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 {
@@ -13,7 +15,7 @@ import {
 import { singleLineFragment } from "./text-safety.mjs";
 import { absentOrMalformed } from "./fs-identity.mjs";
 import { DEFAULT_PROXY_BASE, fetchSpecByMapId } from "./spec-fetch.mjs";
-import { specMaterialHash } from "./spec-identity.mjs";
+import { specMaterialHash, specHashesMatch } from "./spec-identity.mjs";
 import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
 import { PLAYWRIGHT_INSTALL_HINT } from "./browser-launch.mjs";
 import { dirname, join, relative, resolve, isAbsolute } from "node:path";
@@ -28,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.
@@ -345,9 +356,20 @@ async function resolveQaInputs(args, {
   readJsonFile = readJson,
   loadCampaignEntry = loadPageKitCampaignEntry,
 } = {}) {
+  // Selector flags without a non-empty value are argv-only refusals for both
+  // qa run and qa resolve. Check them before checkpoint preflight or site reads.
+  for (const flag of ["packet", "site", "built", "map-id"]) {
+    if (Object.hasOwn(args, flag) && !stringArg(args[flag])) {
+      throw refused(`Missing value for --${flag}`);
+    }
+  }
   if (args.packet && args.spec) {
     throw refused("Packet QA does not accept --spec; it always uses packet.spec.local_path.");
   }
+  // No non-empty campaign selector in argv is also decided before any read.
+  if (![args.packet, args.site, args.built, args._[2], args["map-id"]].some(stringArg)) {
+    throw refused("QA requires a Map ID. Provide --packet or positional <map-id>.");
+  }
   // Non-packet mode (learnings L7): QA a `campaign-build`'d page-kit campaign
   // that has only a built _site/ and a served URL — no Build Packet, no Map ID,
   // no CampaignSpec. Scope (pages + funnel types) is resolved from the built
@@ -371,15 +393,13 @@ async function resolveQaInputs(args, {
   const mapId = stringArg(args["map-id"])
     || stringArg(args._[2])
     || stringArg(packet?.spec?.map_id);
-  // A refusal to identify a campaign, not a failure to QA one: with no
-  // --packet, no --site/--built and no positional <map-id>, every read above
-  // was skipped and `qa run` has nothing to work on. Tagged on both paths, not
-  // just the empty one — the journal question is whether the CLI reached a
-  // handler's WORK, and a missing-identity refusal decides that before any
-  // spec is fetched, any browser launches and anything is written. (When a
-  // packet WAS named, it has been read by here; the packet read is a lookup
-  // for the same identity question, and one message cannot be two verdicts.)
-  if (!mapId) throw refused("QA requires a Map ID. Provide --packet or positional <map-id>.");
+  // A named packet has been read by checkpoint preflight. Its missing or
+  // conflicting identity is a handler failure, not an argv-only refusal.
+  const localSpecId = packet?.spec?.local_spec_id ?? null;
+  if (!mapId && !localSpecId) throw new Error("QA requires a Map ID or a local-spec packet. The named Build Packet has no campaign identity.");
+  if (packet && localSpecId != null && (!resolveCampaignIdentity(packet.spec) || mapId)) {
+    throw new Error("Local-spec packet QA cannot use a Map ID override or an ambiguous identity.");
+  }
 
   const proxyBase = stringArg(args["proxy-base"]) || DEFAULT_PROXY_BASE;
   const inputBaseUrl = normalizeBaseUrl(stringArg(args["base-url"]) || packet?.deploy?.preview_url || packet?.deploy?.production_url || null);
@@ -404,6 +424,13 @@ async function resolveQaInputs(args, {
     specSource = `${proxyBase.replace(/\/+$/, "")}/api/spec/${encodeURIComponent(mapId)}`;
   }
 
+  if (!packet && rawSpec?.spec_identity?.local_spec_id != null) {
+    throw new Error("Local-spec QA requires --packet; a local spec cannot be published under a Map ID.");
+  }
+  if (packet && (localSpecId != null || rawSpec?.spec_identity?.local_spec_id != null)
+    && !campaignIdentitiesMatch(packet.spec, campaignSpecIdentity(rawSpec))) {
+    throw new Error("Packet local_spec_id does not match the local CampaignSpec identity. Re-run prepare-build from the intended spec.");
+  }
   const normalized = normalizeSpec(rawSpec);
   const publicRouteSlug = resolvePublicRouteSlug({ packet, spec: normalized, rawSpec });
   const baseUrl = normalizeQaBaseUrl(inputBaseUrl, publicRouteSlug);
@@ -438,17 +465,28 @@ 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,
     packet,
     mapId,
+    localSpecId,
     publicRouteSlug,
     proxyBase,
     baseUrl,
@@ -463,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.
@@ -478,6 +517,10 @@ function resolvePacketCheckpointPreflight(args, {
 } = {}) {
   const packetPath = resolve(String(args.packet));
   const packet = readJsonFile(packetPath);
+  if (packet?.spec?.local_spec_id != null && (!resolveCampaignIdentity(packet.spec)
+    || stringArg(args["map-id"]) || stringArg(args._?.[2]))) {
+    throw new Error("Local-spec packet QA cannot use a Map ID override or an ambiguous identity.");
+  }
   const specPath = stringArg(args.spec)
     ? resolve(String(args.spec))
     : stringArg(packet?.spec?.local_path)
@@ -513,6 +556,10 @@ function resolvePacketCheckpointPreflight(args, {
       report = null;
     }
   }
+  if (packet?.spec?.local_spec_id != null && (!reportMatchesPacketIdentity(report, packet)
+    || (specStatus === "ok" && !specHashesMatch(report.identity?.spec_material_hash, computeSpecHash(rawSpec))))) {
+    throw new Error("Local-spec QA requires the matching Assembly Report and current spec material hash. Re-run prepare-build after a material revision; do not reuse foreign or stale proof.");
+  }
   const checkpointGates = [
     evaluatePageKitStoreProfile({
       specCampaign: rawSpec?.campaign || null,
@@ -548,12 +595,9 @@ function resolvePacketCheckpointPreflight(args, {
 
 function reportMatchesPacketIdentity(report, packet) {
   if (!isPlainObject(report) || !isPlainObject(report.identity)) return false;
-  const packetMapId = stringArg(packet?.spec?.map_id);
-  const reportMapId = stringArg(report.identity.map_id);
   const packetSlug = normalizePublicRouteSlug(packet?.campaign?.public_route_slug);
   const reportSlug = normalizePublicRouteSlug(report.identity.public_route_slug);
-  return !!packetMapId
-    && packetMapId === reportMapId
+  return campaignIdentitiesMatch(packet?.spec, report.identity)
     && !!packetSlug
     && packetSlug === reportSlug;
 }
@@ -640,7 +684,8 @@ function resolvedFromBlockedCheckpointPreflight(preflight, args) {
     brandContractStatus: "not_evaluated",
     packetPath: preflight.packetPath,
     packet: preflight.packet,
-    mapId: stringArg(preflight.packet?.spec?.map_id) || "unknown-map",
+    mapId: stringArg(preflight.packet?.spec?.map_id) || (preflight.packet?.spec?.local_spec_id ? null : "unknown-map"),
+    localSpecId: preflight.packet?.spec?.local_spec_id ?? null,
     publicRouteSlug,
     proxyBase: stringArg(args["proxy-base"]) || DEFAULT_PROXY_BASE,
     baseUrl: inputBaseUrl,
@@ -666,18 +711,18 @@ function resolvedFromBlockedCheckpointPreflight(preflight, args) {
 // yields "not_applicable" rather than blocking, so browser QA still runs the
 // residue/placeholder/demo gates. Test orders are not attempted (no policy).
 export function resolveQaInputsFromSite(args) {
-  const targetRepo = resolve(String(args.site || args.built));
-  const scope = resolveBuiltSiteScope(targetRepo, { slug: stringArg(args.slug) });
-  if (!scope.ok) {
-    throw new Error(scope.error || `Could not resolve a built campaign from ${targetRepo}.`);
-  }
   const baseUrl = normalizeBaseUrl(stringArg(args["base-url"]));
   if (!baseUrl) {
-    throw new Error("Non-packet site QA requires --base-url <served-campaign-root> so built pages have a fetchable URL.");
+    throw refused("Non-packet site QA requires --base-url <served-campaign-root> so built pages have a fetchable URL.");
   }
   const templateFamily = stringArg(args.family);
   if (!templateFamily) {
-    throw new Error("Non-packet site QA requires --family <template-family> so residue, placeholder, and demo-asset gates can load the family brand contract.");
+    throw refused("Non-packet site QA requires --family <template-family> so residue, placeholder, and demo-asset gates can load the family brand contract.");
+  }
+  const targetRepo = resolve(String(args.site || args.built));
+  const scope = resolveBuiltSiteScope(targetRepo, { slug: stringArg(args.slug) });
+  if (!scope.ok) {
+    throw new Error(scope.error || `Could not resolve a built campaign from ${targetRepo}.`);
   }
   const brandContract = loadBrandContract(templateFamily);
   if (brandContract.status !== "loaded" || !brandContract.contract) {
@@ -1506,6 +1551,7 @@ function resolvePayload(resolved, { routeProbe = null } = {}) {
     ok: status !== "blocked" && status !== "routes_unresolved",
     status,
     map_id: resolved.mapId,
+    ...(resolved.localSpecId ? { local_spec_id: resolved.localSpecId } : {}),
     ...(resolved.packetPath ? { packet_path: resolved.packetPath } : {}),
     ...reportPathField(resolved),
     ...(resolved.proxyBase && resolved.proxyBase !== DEFAULT_PROXY_BASE ? { proxy_base: resolved.proxyBase } : {}),
@@ -2105,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);
 }
@@ -2182,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)
@@ -2272,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({
@@ -2291,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);
@@ -2311,12 +2496,14 @@ async function finalizeQaRun({ args, resolved, runId, startedAt, assertions, tes
     baseDir: resolved.packetPath ? dirname(resolved.packetPath) : null,
     targetRepo: resolved.packetPath ? targetRepoFor(resolved.packetPath, resolved.packet) : null,
     mapId: resolved.mapId,
+    localSpecId: resolved.localSpecId,
     currentRunId: runId,
     isFinding: isFindingAssertion,
   });
   const verdict = createVerdict({
     runId,
     mapId: resolved.mapId,
+    localSpecId: resolved.localSpecId,
     publicRouteSlug: resolved.publicRouteSlug || null,
     campaignRefId: resolved.spec.campaign?.ref_id || null,
     specVersion: resolved.specVersion,
@@ -2370,7 +2557,9 @@ async function finalizeQaRun({ args, resolved, runId, startedAt, assertions, tes
   // config, or scope mismatch should be visible on the QA path too, not just
   // on remit (Kilo review, PR #177).
   const consent = resolveConsent({ proxyBase: resolved.proxyBase });
-  const publishDecision = decidePublishVerdict({ args, portalManaged: resolved.portalManaged === true, consent });
+  const publishDecision = resolved.localSpecId
+    ? { publish: false, reason: "local_spec", flag_invalid: false }
+    : decidePublishVerdict({ args, portalManaged: resolved.portalManaged === true, consent });
   if (publishDecision.flag_invalid) {
     process.stderr.write(`[campaigns-os] --post-verdict "${args["post-verdict"]}" is not a recognized value (use true|1|yes|y|on or false|0|no|n|off); the flag was ignored and the default publish decision applied.\n`);
   }
@@ -2390,6 +2579,7 @@ async function finalizeQaRun({ args, resolved, runId, startedAt, assertions, tes
     status: verdict.disposition,
     run_id: verdict.run_id,
     map_id: resolved.mapId,
+    ...(resolved.localSpecId ? { local_spec_id: resolved.localSpecId } : {}),
     public_route_slug: resolved.publicRouteSlug || null,
     ...reportPathField(resolved),
     base_url: resolved.baseUrl,
@@ -2417,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",
@@ -2434,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",
@@ -2528,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({
@@ -2698,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) {
@@ -3015,7 +3239,7 @@ function output(value, args) {
   }
   if (value.verdict) {
     console.log(`QA run complete.`);
-    console.log(`Map ID: ${value.map_id}`);
+    console.log(`${value.local_spec_id ? "Local spec ID" : "Map ID"}: ${value.local_spec_id || value.map_id}`);
     console.log(`Base URL: ${value.base_url || "(missing)"}`);
     printEntryUrlLines(value.entry_urls);
     console.log(`Run ID: ${value.run_id}`);
@@ -3048,7 +3272,7 @@ function output(value, args) {
   }
   console.log(`QA resolve complete.`);
   console.log(`Status: ${value.status}`);
-  console.log(`Map ID: ${value.map_id}`);
+  console.log(`${value.local_spec_id ? "Local spec ID" : "Map ID"}: ${value.local_spec_id || value.map_id}`);
   console.log(`Spec: ${value.spec_source}`);
   console.log(`Base URL: ${value.base_url || "(missing)"}`);
   printEntryUrlLines(value.entry_urls);
@@ -3198,7 +3422,9 @@ export function qaResolveNextProofLines(value) {
   return [
     `Next expected proof: ${qaRunCommandFromResolve(value)}`,
     `Entry URL(s) resolved: ${formatEntryUrlsForProof(value.entry_urls)}`,
-    "Typed-card test orders use global test cards (no transactions/no permission gate); QA publishes to the portal by default.",
+    value.local_spec_id
+      ? "Typed-card test orders use global test cards (no transactions/no permission gate); local-spec QA stays in the repository."
+      : "Typed-card test orders use global test cards (no transactions/no permission gate); QA publishes to the portal by default.",
   ];
 }
 
@@ -3572,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) => {
@@ -3617,6 +3851,9 @@ export const __qaNodeTestHooks = Object.freeze({
   resolveQaInputs,
   runResolvedQa,
   runPageChecks,
+  analyticsCaptureScope,
+  resolveLocalServeAnalytics,
+  applyLocalServeAnalyticsReview,
   analyticsCorrectnessLegDecision,
   analyticsCorrectnessDisabledAssertion,
   runAnalyticsOrderSequence,

package/src/qa-publish.mjs

@@ -46,6 +46,7 @@ export const QA_PUBLISH_STATUSES = Object.freeze({
 // thrown error, so --json readers get a code to branch on.
 export const QA_PUBLISH_REFUSALS = Object.freeze({
   packet_required: "packet_required",
+  local_spec: "local_spec",
   order_flags_refused: "order_flags_refused",
   verdict_missing: "verdict_missing",
   verdict_unreadable: "verdict_unreadable",
@@ -218,6 +219,9 @@ async function attemptPublish(args, operations, dryRun) {
     return refusal(QA_PUBLISH_REFUSALS.packet_required, `Build Packet ${packetPath} is not readable (${error.code || error.message}).`);
   }
 
+  if (packet?.spec?.local_spec_id != null) {
+    return refusal(QA_PUBLISH_REFUSALS.local_spec, "Local-spec QA has no saved Map destination; keep its verdict in the repository. Portal publication requires a saved Map and fresh evidence.");
+  }
   const source = resolveStoredVerdictSource({ args, packetPath, packet, readJsonFile: ops.readJsonFile, exists: ops.exists });
   if (source.error) return source.error;
   let verdict;

package/src/qa-sidecar.mjs

@@ -1,3 +1,4 @@
+import { localSpecIdentityFields } from "./spec-source-identity.mjs";
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { dirname, join, resolve } from "node:path";
@@ -77,6 +78,7 @@ export function projectVerdictForSidecar(verdict, { generatedAt }) {
     schema_version: verdict.schema_version,
     run_id: verdict.run_id,
     campaign_slug: verdict.campaign_slug,
+    ...localSpecIdentityFields(verdict),
     ...(verdict.public_route_slug != null ? { public_route_slug: verdict.public_route_slug } : {}),
     ...(verdict.campaign_ref_id != null ? { campaign_ref_id: verdict.campaign_ref_id } : {}),
     spec_version: verdict.spec_version,