@nextcommerce/campaigns-os 1.60.0 → 1.62.0

package/src/built-site-scope.mjs

@@ -96,14 +96,14 @@ function listHtmlFiles(root, links = null) {
   return files.sort();
 }
 
-function routeForFile(campaignDir, file) {
+export function routeForFile(campaignDir, file) {
   const rel = relative(campaignDir, file).split(sep).join("/");
   if (rel === "index.html") return "";
   if (rel.endsWith("/index.html")) return rel.slice(0, -"/index.html".length);
   return rel.replace(/\.html$/i, "");
 }
 
-function pageIdForRoute(route) {
+export function pageIdForRoute(route) {
   if (!route) return "index";
   return route.replace(/\//g, "-").replace(/[^A-Za-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "") || "index";
 }

package/src/campaign-workspace.mjs

@@ -2,21 +2,86 @@
 //
 // Two roots matter. The TARGET REPO (`packet.assembly.target_repo` resolved
 // against the packet's directory, else that directory) carries the build
-// sidecars under `.campaign-runtime/` and the local QA verdicts under
-// `qa-output/`; the packet's own directory (`baseDir`) carries what is written
-// beside the packet (run records, the committed QA verdict sidecar). They
-// coincide for a packet at the target root and diverge for `prepare-build
-// --out` elsewhere — exactly when a stage spelling the rule for itself drifts.
+// sidecars under the funnel's runtime directory and the local QA verdicts
+// under `qa-output/`; the packet's own directory (`baseDir`) carries what is
+// written beside the packet (run records, the committed QA verdict sidecar).
+// They coincide for a packet at the target root and diverge for
+// `prepare-build --out` elsewhere — exactly when a stage spelling the rule for
+// itself drifts.
+//
+// One Page Kit project can hold several funnels. Each funnel has its own
+// packet and its own runtime directory, so setting one up never touches
+// another's records (#719). The first funnel set up in a project keeps the
+// project-level `.campaign-runtime/`, which is also where every packet that
+// records no `assembly.runtime_dir` (all packets before per-funnel records)
+// keeps its records. Every later funnel gets `.campaign-runtime/funnels/<public
+// route slug>/`, recorded on its packet as `assembly.runtime_dir`, and its
+// packet is named `campaign-runtime-<public route slug>.build.json` beside the
+// default `campaign-runtime.build.json`.
 // A leaf: node built-ins and the sidecar leaves only.
 
-import { readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
 import { DOCTOR_SIDECAR_REL_PATH } from "./doctor-sidecar.mjs";
 import { absentOrMalformed, sameFile } from "./fs-identity.mjs";
+import { normalizePublicRouteSlug } from "./route-identity.mjs";
 
+export const RUNTIME_DIR_REL_PATH = ".campaign-runtime";
+export const FUNNEL_RUNTIME_PARENT_REL_PATH = ".campaign-runtime/funnels";
 export const BUILD_CONTEXT_REL_PATH = ".campaign-runtime/build-context.json";
 export const ASSEMBLY_REPORT_REL_PATH = ".campaign-runtime/assembly-report.json";
 export const QA_OUTPUT_REL_PATH = "qa-output";
+export const DEFAULT_PACKET_FILENAME = "campaign-runtime.build.json";
+// A project's other root-level packets, one per additional funnel. The same
+// shape readback discovers (src/readback.mjs PACKET_CANDIDATE_PATTERN).
+export const FUNNEL_PACKET_PATTERN = /^campaign-runtime-.+\.build\.json$/;
+
+// A route slug that can name a directory and a file: the characters the packet
+// schema allows in route_root, not starting with a dot (so never `.` or `..`).
+const ROUTE_COMPONENT = /^[A-Za-z0-9_-][A-Za-z0-9._-]*$/;
+
+function routeComponent(routeSlug) {
+  const slug = normalizePublicRouteSlug(routeSlug);
+  if (!ROUTE_COMPONENT.test(slug)) {
+    throw new Error(
+      `Public route slug ${JSON.stringify(routeSlug)} cannot name a funnel's runtime directory or packet file: `
+      + "use letters, digits, dots, underscores and hyphens, not starting with a dot.",
+    );
+  }
+  return slug;
+}
+
+// `.campaign-runtime/funnels/<route>`: a funnel's runtime directory when it is
+// not the project's first, relative to the target repo.
+export function funnelRuntimeRelPath(routeSlug) {
+  return `${FUNNEL_RUNTIME_PARENT_REL_PATH}/${routeComponent(routeSlug)}`;
+}
+
+// `campaign-runtime-<route>.build.json`: the packet of a funnel that is not
+// the project's first.
+export function funnelPacketFilename(routeSlug) {
+  return `campaign-runtime-${routeComponent(routeSlug)}.build.json`;
+}
+
+// The runtime directory a packet's records live under, relative to its target
+// repo (and, for the QA verdict sidecar and Run Records, to the packet's own
+// directory). A packet that records no `assembly.runtime_dir` uses the
+// project-level `.campaign-runtime`, as every packet did before per-funnel
+// records, so an existing project reads its records where they already are.
+// A recorded value must be one of the two shapes for this packet's route:
+// anything else could point one funnel at another's records, so it is refused
+// rather than followed.
+export function packetRuntimeRelPath(packet) {
+  const declared = packet?.assembly?.runtime_dir;
+  if (declared === undefined || declared === null || declared === RUNTIME_DIR_REL_PATH) return RUNTIME_DIR_REL_PATH;
+  const slug = normalizePublicRouteSlug(packet?.campaign?.public_route_slug);
+  if (typeof declared === "string" && ROUTE_COMPONENT.test(slug) && declared === `${FUNNEL_RUNTIME_PARENT_REL_PATH}/${slug}`) return declared;
+  throw new Error(
+    `Build Packet assembly.runtime_dir ${JSON.stringify(declared)} is not this funnel's runtime directory: `
+    + `it must be "${RUNTIME_DIR_REL_PATH}" or "${FUNNEL_RUNTIME_PARENT_REL_PATH}/<campaign.public_route_slug>"`
+    + `${slug ? ` ("${FUNNEL_RUNTIME_PARENT_REL_PATH}/${slug}")` : ""}. Restore the value prepare-build wrote, or re-run prepare-build.`,
+  );
+}
 
 // The target repo a packet builds into.
 export function targetRepoFor(packetPath, packet) {
@@ -25,12 +90,16 @@ export function targetRepoFor(packetPath, packet) {
   return typeof declared === "string" && declared.trim() ? resolve(packetDir, declared) : packetDir;
 }
 
-// The default location of every build sidecar a target repo carries.
-export function campaignSidecarPaths(targetRepo) {
+// The default location of every build sidecar a funnel carries: under the
+// target repo's project-level `.campaign-runtime/` unless the packet records
+// its own runtime directory (packetRuntimeRelPath).
+export function campaignSidecarPaths(targetRepo, runtimeRelPath = RUNTIME_DIR_REL_PATH) {
+  const runtimeDir = join(targetRepo, runtimeRelPath);
   return {
-    contextPath: join(targetRepo, BUILD_CONTEXT_REL_PATH),
-    reportPath: join(targetRepo, ASSEMBLY_REPORT_REL_PATH),
-    doctorOutPath: join(targetRepo, DOCTOR_SIDECAR_REL_PATH),
+    runtimeDir,
+    contextPath: join(runtimeDir, basename(BUILD_CONTEXT_REL_PATH)),
+    reportPath: join(runtimeDir, basename(ASSEMBLY_REPORT_REL_PATH)),
+    doctorOutPath: join(runtimeDir, basename(DOCTOR_SIDECAR_REL_PATH)),
     qaOutputDir: join(targetRepo, QA_OUTPUT_REL_PATH),
   };
 }
@@ -44,9 +113,11 @@ export function campaignSidecarPaths(targetRepo) {
 // report IS that default, so the printed command stays short; the path when
 // it is not, or when the target repo is unknown and the default cannot be
 // ruled out. Doctor's report and the QA runner's both print through this.
-export function explicitReportPath(reportPath, targetRepo) {
+// `runtimeRelPath` is the packet's runtime directory (packetRuntimeRelPath),
+// since that is where those commands infer the report for that packet.
+export function explicitReportPath(reportPath, targetRepo, runtimeRelPath = RUNTIME_DIR_REL_PATH) {
   if (typeof reportPath !== "string" || !reportPath) return null;
-  const inferred = typeof targetRepo === "string" && targetRepo ? campaignSidecarPaths(targetRepo).reportPath : null;
+  const inferred = typeof targetRepo === "string" && targetRepo ? campaignSidecarPaths(targetRepo, runtimeRelPath).reportPath : null;
   return reportPath !== inferred ? reportPath : null;
 }
 
@@ -99,7 +170,8 @@ export function resolveCampaignWorkspace(packetPath, {
   const loadedPacket = packet === undefined ? JSON.parse(readFileSync(absolutePacketPath, "utf8")) : packet;
   const baseDir = dirname(absolutePacketPath);
   const targetRepo = targetRepoFor(absolutePacketPath, loadedPacket);
-  const defaults = campaignSidecarPaths(targetRepo);
+  const runtimeRelPath = packetRuntimeRelPath(loadedPacket);
+  const defaults = campaignSidecarPaths(targetRepo, runtimeRelPath);
   const resolvedContextPath = contextPath === undefined ? defaults.contextPath : contextPath;
   const context = followContextPointer ? readContextForBinding(resolvedContextPath) : null;
   const recorded = typeof context?.report_path === "string" && context.report_path.trim() ? context.report_path.trim() : null;
@@ -118,6 +190,11 @@ export function resolveCampaignWorkspace(packetPath, {
     packetPath: absolutePacketPath,
     baseDir,
     targetRepo,
+    // The funnel's runtime directory under the target repo, and the same
+    // directory beside the packet (QA verdict sidecar, Run Records).
+    runtimeRelPath,
+    runtimeDir: defaults.runtimeDir,
+    packetRuntimeDir: join(baseDir, runtimeRelPath),
     contextPath: resolvedContextPath,
     reportPath: resolvedReportPath,
     defaultReportPath: defaults.reportPath,
@@ -125,3 +202,199 @@ export function resolveCampaignWorkspace(packetPath, {
     qaOutputDir: defaults.qaOutputDir,
   };
 }
+
+// ---------------------------------------------------------------------------
+// Several funnels in one project.
+
+function readJsonState(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    return { state: "present", value: parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null };
+  } catch (error) {
+    if (error?.code === "ENOENT") return { state: "absent", value: null };
+    if (absentOrMalformed(error)) return { state: "present", value: null };
+    throw error;
+  }
+}
+
+function routeOf(packet) {
+  return normalizePublicRouteSlug(packet?.campaign?.public_route_slug) || null;
+}
+
+// The root-level Build Packets of a project, default name first, then one per
+// additional funnel by name, each with the route it names (null when the
+// packet names none), its generated_at instant in milliseconds (null when it
+// records none it can parse) and whether it could be read at all.
+export function projectFunnelPackets(root) {
+  const projectRoot = resolve(root);
+  let names = [];
+  try {
+    names = readdirSync(projectRoot);
+  } catch {
+    names = [];
+  }
+  const ordered = [
+    ...(names.includes(DEFAULT_PACKET_FILENAME) ? [DEFAULT_PACKET_FILENAME] : []),
+    ...names.filter((name) => FUNNEL_PACKET_PATTERN.test(name)).sort(),
+  ];
+  const packets = [];
+  for (const name of ordered) {
+    const path = join(projectRoot, name);
+    try {
+      if (!statSync(path).isFile()) continue;
+    } catch {
+      continue;
+    }
+    const { value } = readJsonState(path);
+    const generated = typeof value?.generated_at === "string" ? Date.parse(value.generated_at) : Number.NaN;
+    packets.push({ name, path, route: routeOf(value), readable: Boolean(value), generatedAt: Number.isFinite(generated) ? generated : null });
+  }
+  return packets;
+}
+
+// The packet a command acts on when it was given no --packet, chosen the way
+// readback discovers one: null when there is none, the only readable packet,
+// or among packets that all name one route (later runs of one funnel) the
+// newest by generated_at, the default name first on a tie. Packets naming
+// different routes are different funnels, and picking one would read or write
+// another funnel's records, so that is refused with every packet named.
+export function soleProjectPacket(root, { command = "this command" } = {}) {
+  const packets = projectFunnelPackets(root);
+  const readable = packets.filter((packet) => packet.readable);
+  if (!readable.length) return packets[0]?.path || null;
+  if (new Set(readable.map((packet) => packet.route)).size > 1) {
+    const listed = readable.map((packet) => `${packet.name} (route ${packet.route || "unnamed"})`).join(", ");
+    throw Object.assign(new Error(
+      `${resolve(root)} holds Build Packets for ${new Set(readable.map((packet) => packet.route)).size} funnels: ${listed}. `
+      + `Pass --packet <packet> to ${command} to name the funnel to act on.`,
+    ), { code: "MULTIPLE_FUNNEL_PACKETS", packets: readable.map((packet) => packet.path) });
+  }
+  const newest = readable.reduce((best, packet) => ((packet.generatedAt ?? -Infinity) > (best.generatedAt ?? -Infinity) ? packet : best));
+  return newest.path;
+}
+
+// The route the project-level records belong to: undefined when there are
+// none, the route the Assembly Report (else the Build Context's packet) names,
+// or null when records exist but name no route anyone can read.
+function projectRecordsRoute(targetRepo) {
+  const defaults = campaignSidecarPaths(targetRepo);
+  const report = readJsonState(defaults.reportPath);
+  const context = readJsonState(defaults.contextPath);
+  if (report.state === "absent" && context.state === "absent") return undefined;
+  const reported = normalizePublicRouteSlug(report.value?.identity?.public_route_slug);
+  if (reported) return reported;
+  const named = typeof context.value?.packet_path === "string" && context.value.packet_path.trim()
+    ? resolve(targetRepo, context.value.packet_path.trim())
+    : null;
+  return named ? routeOf(readJsonState(named).value) : null;
+}
+
+/**
+ * Where prepare-build puts one funnel's packet and records.
+ *
+ * Packet: an explicit `--out` wins. Otherwise the default
+ * `campaign-runtime.build.json` when it is this route's, else the funnel's own
+ * `campaign-runtime-<route>.build.json` when it already exists, else the
+ * default when it is absent, else the funnel's own name. A Build Packet that
+ * exists at the chosen path for another route, or one whose route cannot be
+ * read, is replaced only with `force`: that is the operator saying this
+ * funnel takes the other's place (renaming a funnel's route), never a side
+ * effect of naming a path.
+ *
+ * Records: a packet already at that path for this route keeps the runtime
+ * directory it records (the project-level one when it records none and those
+ * records are this route's or absent). A packet replaced with `force` whose records are the
+ * project-level ones hands those to this funnel, so renaming a project's first
+ * funnel keeps the default layout. Otherwise the funnel's own directory when
+ * it already exists, else the project-level `.campaign-runtime` when it holds
+ * no records or this route's, else the funnel's own directory. Records another
+ * route owns, or records whose route cannot be read, are never replaced.
+ *
+ * Returns `{ packetPath, runtimeRelPath, scoped, addedBeside }`; `scoped` is
+ * true when the packet must record `assembly.runtime_dir`, and `addedBeside`
+ * names the default packet and its route when this run sets the funnel up as
+ * a new one beside it (null otherwise).
+ */
+export function planFunnelWorkspace(targetRepo, routeSlug, { packetPath: explicitPacketPath = null, force = false } = {}) {
+  const repo = resolve(targetRepo);
+  const slug = normalizePublicRouteSlug(routeSlug);
+  const nameable = ROUTE_COMPONENT.test(slug);
+  const rootPacket = join(repo, DEFAULT_PACKET_FILENAME);
+  const ownPacket = nameable ? join(repo, funnelPacketFilename(slug)) : null;
+  const rootPacketState = readJsonState(rootPacket);
+  const rootPacketRoute = routeOf(rootPacketState.value);
+
+  let packetPath = explicitPacketPath ? resolve(explicitPacketPath) : null;
+  if (!packetPath) {
+    const rootPacketFree = rootPacketState.state === "absent" || rootPacketRoute === slug;
+    packetPath = rootPacketRoute === slug ? rootPacket
+      : ownPacket && existsSync(ownPacket) ? ownPacket
+        : rootPacketFree || !ownPacket ? rootPacket
+          : ownPacket;
+    if (!rootPacketFree && packetPath === rootPacket && !force) {
+      throw new Error(
+        `${rootPacket} belongs to route ${rootPacketRoute || "(unreadable)"}, and route ${JSON.stringify(slug)} cannot name a packet of its own. `
+        + "Pass --out <packet> to keep this funnel's packet elsewhere, or set a public route slug of letters, digits, dots, underscores and hyphens.",
+      );
+    }
+  }
+
+  const existingState = readJsonState(packetPath);
+  const existing = existingState.value;
+  const existingRoute = routeOf(existing);
+  const replacing = isBuildPacketAt(packetPath, existingState) && existingRoute !== slug;
+  if (replacing && !force) {
+    throw new Error(
+      `${packetPath} is the Build Packet of route ${existingRoute || "(unreadable)"}, not ${JSON.stringify(slug)}; replacing it would leave that funnel's records with no packet. `
+      + "Pass a different --out to set this funnel up beside it, or --force to replace that funnel with this one (renaming its route).",
+    );
+  }
+  const addedBeside = !replacing && existingState.state === "absent" && packetPath !== rootPacket
+    && rootPacketState.state === "present" && rootPacketRoute !== slug
+    ? { packetPath: rootPacket, route: rootPacketRoute }
+    : null;
+  const plan = (runtimeRelPath) => ({ packetPath, runtimeRelPath, scoped: runtimeRelPath !== RUNTIME_DIR_REL_PATH, addedBeside });
+
+  const owner = projectRecordsRoute(repo);
+  if (existing && existingRoute === slug) {
+    if (existing.assembly?.runtime_dir != null) return plan(packetRuntimeRelPath(existing));
+    if (owner === undefined || owner === slug) return plan(RUNTIME_DIR_REL_PATH);
+  }
+  if (replacing && existing && replacedRuntimeRelPath(existing) === RUNTIME_DIR_REL_PATH
+    && (owner === undefined || owner === null || owner === existingRoute || owner === slug)) {
+    return plan(RUNTIME_DIR_REL_PATH);
+  }
+  const ownRuntime = nameable ? funnelRuntimeRelPath(slug) : null;
+  if (ownRuntime && existsSync(join(repo, ownRuntime))) return plan(ownRuntime);
+  if (owner === undefined || owner === slug) return plan(RUNTIME_DIR_REL_PATH);
+  if (!ownRuntime) {
+    throw new Error(
+      `${join(repo, RUNTIME_DIR_REL_PATH)} holds the records of route ${owner || "(unreadable)"}, and route ${JSON.stringify(slug)} cannot name a runtime directory of its own. `
+      + "Set a public route slug of letters, digits, dots, underscores and hyphens.",
+    );
+  }
+  return plan(ownRuntime);
+}
+
+// Whether the file at `path` is a Build Packet another funnel may own: a
+// packet by its contents, or a file at a packet's name that cannot be read.
+// Any other file there is left to prepare-build's output collision checks.
+function isBuildPacketAt(path, { state, value }) {
+  if (state !== "present") return false;
+  if (value) {
+    return (typeof value.schema_version === "string" && value.schema_version.startsWith("campaign-runtime-build-packet/"))
+      || (value.campaign !== null && typeof value.campaign === "object" && !Array.isArray(value.campaign));
+  }
+  const name = basename(path);
+  return name === DEFAULT_PACKET_FILENAME || FUNNEL_PACKET_PATTERN.test(name);
+}
+
+// The runtime directory a packet being replaced keeps its records in, or null
+// when its recorded value is not one prepare-build writes.
+function replacedRuntimeRelPath(packet) {
+  try {
+    return packetRuntimeRelPath(packet);
+  } catch {
+    return null;
+  }
+}

package/src/change-scope.mjs

@@ -0,0 +1,284 @@
+// Change scope: what a change to built output owes.
+//
+// A change that touches only some pages' copy, images or styling owes QA on
+// those pages; Polish is advisory for it. A change that touches commerce owes
+// the full Polish and QA. Commerce here is what a page sends to the Campaign
+// Cart SDK or the funnel: the campaign's Page Kit config entry (SDK pin,
+// analytics ids, store fields), package, offer and shipping refs, the upsell
+// order and routes, and scripts. A file that cannot be mapped to one page
+// counts as commerce, and so does any change this module cannot classify.
+//
+// `record build` keeps a commerce signature beside the build manifest: one
+// hash per built page over the page's commerce-bearing markup, plus one hash
+// of the campaign's config entry. A later change compares the pages that
+// differ against those hashes. It also keeps `build_changes`, one entry per
+// recorded rebuild, so a stage that reviewed an older build can still read
+// which pages changed since then after the manifest has moved on.
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { parse } from "parse5";
+
+import { inferPageType, pageIdForRoute, routeForFile } from "./built-site-scope.mjs";
+import { loadPageKitCampaignEntry } from "./page-kit-campaign-config.mjs";
+
+export const COMMERCE_SIGNATURE_ALGORITHM = "commerce-signature/v1";
+export const CHANGE_KINDS = Object.freeze(["none", "page_only", "commerce_affecting", "unknown"]);
+// The reasons a change counts as commerce, closed so readers can switch on them.
+export const COMMERCE_REASONS = Object.freeze([
+  "unmapped_file",
+  "page_added",
+  "page_removed",
+  "checkout_page",
+  "commerce_markup_changed",
+  "commerce_signature_unavailable",
+  "campaign_config_changed",
+  "campaign_config_unavailable",
+  "change_history_unavailable",
+]);
+// How many rebuilds `record build` keeps in build_changes, and how many paths
+// one entry lists per list. A stage that reviewed a build older than the
+// kept history reads its change as unknown, and so owes the full stages.
+export const BUILD_CHANGES_LIMIT = 25;
+export const CHANGE_PATH_LIMIT = 20;
+// CPK page types that take payment or render the checkout surface.
+const CHECKOUT_PAGE_TYPES = new Set(["checkout", "checkout_step", "select"]);
+// Attribute names that carry package, offer, shipping, upsell or checkout
+// identity on built pages: data-next-*, the older os-checkout-* bindings and
+// other data-* names for those refs. Inline event handlers (onclick and the
+// like) can call the SDK, so they count too.
+const COMMERCE_ATTRIBUTE = /^data-next-|^data-[a-z0-9-]*(?:package|offer|shipping|upsell|voucher|coupon)[a-z0-9-]*$|^data-(?:next-)?[a-z0-9-]*template-id$|^os-checkout(?:-|$)|^on[a-z]+$/;
+// Attributes that render the checkout surface or take payment. A page that
+// carries one is a checkout page whatever its type or route says.
+const CHECKOUT_ATTRIBUTE = /^data-next-(?:checkout|payment|express-checkout)(?:-|$)|^os-checkout(?:-|$)/;
+
+const sha256 = (value) => `sha256:${createHash("sha256").update(value).digest("hex")}`;
+const isObject = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+
+function textOf(node) {
+  const children = node.content ? node.content.childNodes : node.childNodes;
+  return (children || []).map((child) => (child.nodeName === "#text" ? child.value || "" : "")).join("");
+}
+
+// The commerce-bearing facts of one built page, in document order: every
+// SDK attribute and inline event handler, every next-* meta tag, every
+// script (src, or the inline body), every link target and form action. Copy,
+// images and styling are left out, so a copy edit keeps the signature.
+// `checkout` is true when the page carries checkout or payment markup.
+export function pageCommerceFacts(html) {
+  const facts = [];
+  let pageType = null;
+  let checkout = false;
+  const walk = (node) => {
+    const children = node.content ? node.content.childNodes : node.childNodes;
+    for (const child of children || []) {
+      if (child.nodeName && !child.nodeName.startsWith("#")) {
+        const tag = child.nodeName.toLowerCase();
+        const attrs = new Map((child.attrs || []).map((attr) => [attr.name.toLowerCase(), attr.value]));
+        for (const [name, value] of attrs) {
+          if (COMMERCE_ATTRIBUTE.test(name)) facts.push(`${tag}[${name}]=${value}`);
+          if (CHECKOUT_ATTRIBUTE.test(name)) checkout = true;
+        }
+        const metaName = String(attrs.get("name") || "").trim().toLowerCase();
+        if (tag === "meta" && metaName.startsWith("next-")) {
+          facts.push(`meta[${metaName}]=${attrs.get("content") ?? ""}`);
+          if (metaName === "next-page-type") pageType = String(attrs.get("content") || "").trim().toLowerCase() || null;
+        }
+        if (tag === "script") facts.push(attrs.has("src") ? `script[src]=${attrs.get("src")}` : `script=${sha256(textOf(child))}`);
+        if (tag === "a" && attrs.has("href")) facts.push(`a[href]=${attrs.get("href")}`);
+        if (tag === "form" && attrs.has("action")) facts.push(`form[action]=${attrs.get("action")}`);
+      }
+      walk(child);
+    }
+  };
+  walk(parse(String(html)));
+  return { signature: sha256(facts.join("\n")), page_type: pageType, checkout };
+}
+
+// The campaign's own Page Kit config entry, hashed; a missing or unreadable
+// entry is its status, so a change from present to absent still differs.
+export function campaignConfigFingerprint(targetRepo, publicRouteSlug) {
+  const load = loadPageKitCampaignEntry({ targetRepo, publicRouteSlug });
+  if (load.status !== "ok") return `unavailable:${load.status}`;
+  const canonical = (value) => Array.isArray(value) ? value.map(canonical)
+    : isObject(value) ? Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])])) : value;
+  return sha256(JSON.stringify(canonical(load.entry)));
+}
+
+/**
+ * The signature `record build` keeps on stages.assembly.commerce_signature:
+ * `{ algorithm, campaign_config, pages: { <built path>: sha256 } }` for the
+ * pages of a resolved built-site scope (resolveBuiltSiteScope). Null when the
+ * scope did not resolve; a page that cannot be read is left out, so a later
+ * change to it reads as unclassifiable.
+ */
+export function buildCommerceSignature({ scope, outputRoot, targetRepo, publicRouteSlug }) {
+  if (!scope?.ok) return null;
+  const pages = {};
+  for (const page of scope.pages) {
+    const path = builtPath(outputRoot, page.built_path);
+    try {
+      pages[path] = pageCommerceFacts(readFileSync(page.built_path, "utf8")).signature;
+    } catch { /* left out: an unreadable page cannot be classified later */ }
+  }
+  return { algorithm: COMMERCE_SIGNATURE_ALGORITHM, campaign_config: campaignConfigFingerprint(targetRepo, publicRouteSlug), pages };
+}
+
+function builtPath(outputRoot, file) {
+  const relativePath = file.startsWith(outputRoot) ? file.slice(outputRoot.length).replace(/^[\\/]+/, "") : file;
+  return relativePath.split(/[\\/]/).join("/");
+}
+
+function recordedSignature(assembly) {
+  const signature = assembly?.commerce_signature;
+  return isObject(signature) && signature.algorithm === COMMERCE_SIGNATURE_ALGORITHM && isObject(signature.pages)
+    && typeof signature.campaign_config === "string" ? signature : null;
+}
+
+const capped = (items) => items.slice(0, CHANGE_PATH_LIMIT);
+
+/**
+ * Classify the drift between a recorded build and the output on disk.
+ * `changes` is assessEvidenceDebt's known change list (changed_pages,
+ * unmapped_files, extra, missing). `baseline` is the recorded
+ * stages.assembly. Returns `{ kind, reasons }`, `kind` one of CHANGE_KINDS
+ * and `reasons` the commerce reasons found, each `{ code, path? }`.
+ */
+export function classifyDrift({ changes, baseline, outputRoot, targetRepo, publicRouteSlug }) {
+  if (changes?.status !== "known") return { kind: "unknown", reasons: [] };
+  if (!changes.changed_pages.length && !changes.unmapped_files.length) return { kind: "none", reasons: [] };
+  const reasons = [];
+  for (const path of changes.unmapped_files) reasons.push({ code: "unmapped_file", path });
+  const signature = recordedSignature(baseline);
+  if (!signature) reasons.push({ code: "commerce_signature_unavailable" });
+  else if (signature.campaign_config.startsWith("unavailable:")
+    || campaignConfigFingerprint(targetRepo, publicRouteSlug) !== signature.campaign_config) {
+    reasons.push({ code: signature.campaign_config.startsWith("unavailable:") ? "campaign_config_unavailable" : "campaign_config_changed" });
+  }
+  for (const page of changes.changed_pages) {
+    if (changes.extra.includes(page.built_path)) { reasons.push({ code: "page_added", path: page.built_path }); continue; }
+    if (changes.missing.includes(page.built_path)) { reasons.push({ code: "page_removed", path: page.built_path }); continue; }
+    let current;
+    try {
+      current = pageCommerceFacts(readFileSync(join(outputRoot, page.built_path), "utf8"));
+    } catch {
+      reasons.push({ code: "commerce_signature_unavailable", path: page.built_path });
+      continue;
+    }
+    const type = current.page_type || inferPageType(routeForFile(outputRoot, join(outputRoot, page.built_path)));
+    if (CHECKOUT_PAGE_TYPES.has(type) || current.checkout) reasons.push({ code: "checkout_page", path: page.built_path });
+    else if (!signature || !Object.hasOwn(signature.pages, page.built_path)) {
+      if (signature) reasons.push({ code: "commerce_signature_unavailable", path: page.built_path });
+    } else if (signature.pages[page.built_path] !== current.signature) {
+      reasons.push({ code: "commerce_markup_changed", path: page.built_path });
+    }
+  }
+  return { kind: reasons.length ? "commerce_affecting" : "page_only", reasons: capped(reasons) };
+}
+
+/**
+ * One build_changes entry for a rebuild from `from` to `to`, from the debt
+ * assessment of the new output against the previous record.
+ */
+export function buildChangeEntry({ from, to, at, changes, classification }) {
+  return {
+    from_build_fingerprint: from,
+    build_fingerprint: to,
+    recorded_at: at,
+    kind: classification.kind,
+    changed_pages: changes.status === "known" ? changes.changed_pages.map((page) => ({ page_id: page.page_id, built_path: page.built_path })) : [],
+    unmapped_files: changes.status === "known" ? capped(changes.unmapped_files) : [],
+    unmapped_file_count: changes.status === "known" ? changes.unmapped_files.length : 0,
+    reasons: classification.reasons,
+  };
+}
+
+function validEntry(entry) {
+  return isObject(entry) && typeof entry.from_build_fingerprint === "string" && typeof entry.build_fingerprint === "string"
+    && CHANGE_KINDS.includes(entry.kind) && Array.isArray(entry.changed_pages) && Array.isArray(entry.reasons);
+}
+
+/**
+ * The kept rebuild history after recording `entry`: the previous history
+ * with this rebuild appended, trimmed to the entries a stage anchored at one
+ * of `anchors` can still walk, and to BUILD_CHANGES_LIMIT.
+ */
+export function nextBuildChanges(previous, entry, anchors = []) {
+  const history = [...(Array.isArray(previous) ? previous.filter(validEntry) : []), entry];
+  const wanted = new Set(anchors.filter((anchor) => typeof anchor === "string" && anchor));
+  const kept = [];
+  let at = entry.build_fingerprint;
+  for (let index = history.length - 1; index >= 0 && wanted.size; index -= 1) {
+    if (history[index].build_fingerprint !== at) break;
+    kept.unshift(history[index]);
+    at = history[index].from_build_fingerprint;
+    wanted.delete(at);
+  }
+  return kept.slice(-BUILD_CHANGES_LIMIT);
+}
+
+const KIND_RANK = Object.freeze({ none: 0, page_only: 1, commerce_affecting: 2, unknown: 3 });
+// The worse of two change kinds; an unrecognized kind reads as unknown.
+const rankOf = (kind) => KIND_RANK[kind] ?? KIND_RANK.unknown;
+export function worseChangeKind(a, b) {
+  const kind = rankOf(a) >= rankOf(b) ? a : b;
+  return Object.hasOwn(KIND_RANK, kind) ? kind : "unknown";
+}
+
+/**
+ * The change a stage that reviewed `anchor` owes for: the recorded rebuilds
+ * from `anchor` to the recorded build, then the drift from the recorded build
+ * to the output on disk. Returns `{ kind, since_build_fingerprint,
+ * changed_pages, unmapped_files, reasons }`; `kind` is unknown when the
+ * history does not reach `anchor` or the drift cannot be read.
+ */
+export function changeSince(anchor, { assembly, drift, driftClassification }) {
+  const recorded = typeof assembly?.build_fingerprint === "string" ? assembly.build_fingerprint : null;
+  const result = { kind: "none", since_build_fingerprint: anchor || null, changed_pages: [], unmapped_files: [], reasons: [] };
+  if (!anchor || !recorded) return { ...result, kind: "unknown" };
+  const segments = [];
+  if (anchor !== recorded) {
+    const history = Array.isArray(assembly.build_changes) ? assembly.build_changes.filter(validEntry) : [];
+    let at = recorded;
+    for (let index = history.length - 1; index >= 0 && at !== anchor; index -= 1) {
+      if (history[index].build_fingerprint !== at) break;
+      segments.unshift(history[index]);
+      at = history[index].from_build_fingerprint;
+    }
+    if (at !== anchor) return { ...result, kind: "unknown", reasons: [{ code: "change_history_unavailable" }] };
+  }
+  const pages = new Map();
+  const unmapped = new Set();
+  let kind = "none";
+  const add = (part, partKind, reasons) => {
+    kind = worseChangeKind(kind, partKind);
+    for (const page of part.changed_pages || []) pages.set(page.built_path, { page_id: page.page_id, built_path: page.built_path });
+    for (const path of part.unmapped_files || []) unmapped.add(path);
+    result.reasons.push(...(reasons || []));
+  };
+  for (const segment of segments) add(segment, segment.kind, segment.reasons);
+  if (drift?.status !== "known") kind = "unknown";
+  else add(drift, driftClassification?.kind || "unknown", driftClassification?.reasons);
+  return {
+    ...result,
+    kind,
+    changed_pages: [...pages.values()].sort((a, b) => a.built_path.localeCompare(b.built_path)),
+    unmapped_files: capped([...unmapped].sort()),
+    reasons: capped(result.reasons),
+  };
+}
+
+// The page id a QA topology page has in the change lists: the id of its
+// route under the campaign base, as built-site scope derives it.
+export function routePageIdForUrl(url, baseUrl) {
+  try {
+    const base = new URL(baseUrl).pathname.replace(/\/+$/, "");
+    const path = new URL(url).pathname;
+    const route = (path.startsWith(`${base}/`) || path === base ? path.slice(base.length) : path)
+      .replace(/^\/+/, "").replace(/(?:^|\/)index\.html$/, "").replace(/\.html$/i, "").replace(/\/+$/, "");
+    return pageIdForRoute(route);
+  } catch {
+    return null;
+  }
+}