@nextcommerce/campaigns-os 1.33.0

package/src/qa-route-probe.mjs

@@ -0,0 +1,272 @@
+import { normalizePublicRouteSlug } from "./route-identity.mjs";
+
+// Route probe: the reachability half of `qa resolve`.
+//
+// Doctrine: `qa resolve` derives every route URL from the packet — the packet
+// is the authority on where a campaign is served — and until #273 it reported
+// `ready` on that derivation alone, never asking the deployment whether the
+// URLs it just printed exist. Pointed at a host serving the same campaign under
+// a different route root it printed nine entry URLs and `ready`; all nine were
+// 404, and the three checkpoints below them also said `pass` because they read
+// the packet rather than the deployment. The existing operator guidance —
+// "empty Entry URLs mean a dead preview or a wrong --base-url" — does not cover
+// that case, because the URLs are non-empty and all wrong.
+//
+// So resolve probes what it derived. Two rules shape the module:
+//
+//   1. A derivation is not a verification. `ready` now means the routes were
+//      probed AND resolved; a route set that does not resolve gets its own
+//      terminal status naming the first URL that failed.
+//   2. Probing must never make resolve unusable. An HTTP response saying 404 is
+//      evidence about the deployment; a transport error is evidence about this
+//      machine's network, which is not the deployment's fault. The first fails
+//      the probe, the second degrades to a named `not_probed` state that stays
+//      usable offline and in CI.
+
+export const ROUTE_PROBE_DEFAULT_TIMEOUT_MS = 5000;
+// Entry URLs are one per funnel, so a real campaign is well inside this. The
+// cap exists so a pathological topology cannot turn a diagnostic command into
+// an unbounded network sweep; anything past it is reported as skipped rather
+// than silently dropped.
+export const ROUTE_PROBE_MAX_URLS = 25;
+const ROUTE_PROBE_CONCURRENCY = 6;
+// A static host that refuses HEAD is answering about the method, not the route.
+const METHOD_NOT_SUPPORTED = new Set([405, 501]);
+
+/**
+ * Probe one URL. A response — any response — is evidence about the deployment;
+ * a throw is evidence about the transport between here and it.
+ */
+export async function probeOneUrl(url, { timeoutMs = ROUTE_PROBE_DEFAULT_TIMEOUT_MS, fetchImpl = fetch } = {}) {
+  const attempt = async (method) => fetchImpl(url, {
+    method,
+    redirect: "follow",
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  try {
+    let method = "HEAD";
+    let response = await attempt(method);
+    if (METHOD_NOT_SUPPORTED.has(Number(response?.status))) {
+      method = "GET";
+      response = await attempt(method);
+    }
+    const httpStatus = Number(response?.status);
+    return {
+      url,
+      outcome: httpStatus >= 400 ? "unresolved" : "resolved",
+      method,
+      http_status: Number.isFinite(httpStatus) ? httpStatus : null,
+      error: null,
+    };
+  } catch (error) {
+    return {
+      url,
+      outcome: "unreachable",
+      method: "HEAD",
+      http_status: null,
+      error: transportErrorText(error, timeoutMs),
+    };
+  }
+}
+
+function transportErrorText(error, timeoutMs) {
+  if (error?.name === "TimeoutError") return `no response within ${timeoutMs}ms`;
+  const cause = error?.cause?.code || error?.code || null;
+  const message = String(error?.message || error || "transport error");
+  return cause ? `${message} (${cause})` : message;
+}
+
+// Bounded-concurrency probe that preserves INPUT order. Workers pull indices
+// off a shared cursor and complete in whatever order the network allows, but
+// each writes to `results[index]` — its own input slot — so `results` reads back
+// in the order the entry URLs were derived, not the order the responses landed.
+// `first_failure` and the printed "First failure:" line depend on that, so a
+// future refactor to `push()` or `Promise.all(map(...))`-with-append would
+// silently change what "first" means.
+async function probeAll(urls, options) {
+  const results = new Array(urls.length);
+  let cursor = 0;
+  const worker = async () => {
+    for (let index = cursor++; index < urls.length; index = cursor++) {
+      results[index] = await probeOneUrl(urls[index], options);
+    }
+  };
+  await Promise.all(
+    Array.from({ length: Math.min(ROUTE_PROBE_CONCURRENCY, urls.length) }, worker),
+  );
+  return results;
+}
+
+/**
+ * The route root this resolve derived, with the packet's public_route_slug
+ * stripped back off.
+ *
+ * `resolve` appends `public_route_slug` unconditionally, so no documented input
+ * points the harness at a deployment served under a different route root — the
+ * packet is the authority, and that is intended. The failure mode is what was
+ * not intended: the operator saw `ready` rather than a message saying so. When
+ * every derived route is dead, one extra probe of the host without the slug
+ * separates "this deployment is down" from "this deployment does not serve the
+ * slug this packet declares", which is the actionable half.
+ */
+export function baseUrlWithoutSlug(baseUrl, publicRouteSlug) {
+  const slug = normalizePublicRouteSlug(publicRouteSlug);
+  if (!slug || !baseUrl) return null;
+  try {
+    const url = new URL(baseUrl);
+    const segments = url.pathname.split("/").filter(Boolean);
+    if (segments.at(-1) !== slug) return null;
+    url.pathname = `/${segments.slice(0, -1).join("/")}${segments.length > 1 ? "/" : ""}`;
+    return url.toString();
+  } catch {
+    return null;
+  }
+}
+
+function summarize(results) {
+  const counts = { resolved: 0, unresolved: 0, unreachable: 0, skipped: 0 };
+  for (const result of results) counts[result.outcome] = (counts[result.outcome] || 0) + 1;
+  return counts;
+}
+
+function describeFailure(result) {
+  if (!result) return "";
+  return result.outcome === "unresolved"
+    ? `${result.url} (HTTP ${result.http_status})`
+    : `${result.url} (${result.error})`;
+}
+
+/**
+ * Probe the entry URLs resolve just derived.
+ *
+ * @returns {{
+ *   status: "pass"|"failed"|"not_probed",
+ *   code: string,
+ *   reason: string,
+ *   counts: { resolved: number, unresolved: number, unreachable: number, skipped: number },
+ *   first_failure: object|null,   // first result that did not cleanly resolve, in the order the
+ *                                 // entry URLs were derived; null only when every probed URL
+ *                                 // resolved, or when nothing was probed at all.
+ *   results: object[],
+ *   route_root_hint: object|null,
+ * }}
+ */
+export async function probeRouteUrls({
+  entryUrls = [],
+  baseUrl = null,
+  publicRouteSlug = null,
+  enabled = true,
+  timeoutMs = ROUTE_PROBE_DEFAULT_TIMEOUT_MS,
+  fetchImpl = fetch,
+  skippedReason = null,
+} = {}) {
+  const urls = [];
+  const seen = new Set();
+  for (const entry of Array.isArray(entryUrls) ? entryUrls : []) {
+    const url = typeof entry === "string" ? entry : entry?.url;
+    if (typeof url !== "string" || !url.trim() || seen.has(url)) continue;
+    seen.add(url);
+    urls.push(url);
+  }
+
+  const notProbed = (code, reason, results = []) => ({
+    status: "not_probed",
+    code,
+    reason,
+    counts: summarize(results),
+    first_failure: null,
+    results,
+    route_root_hint: null,
+  });
+
+  if (!urls.length) {
+    return notProbed(
+      "route_probe.no_routes",
+      "No entry URLs were derived, so there was nothing to probe. An empty Entry URL list means a dead preview or a missing --base-url.",
+    );
+  }
+  if (!enabled) {
+    return notProbed(
+      "route_probe.disabled",
+      `Route probing is off${skippedReason ? ` (${skippedReason})` : ""}; the ${urls.length} derived entry URL(s) were not checked against the deployment.`,
+      urls.map((url) => ({ url, outcome: "skipped", method: null, http_status: null, error: null })),
+    );
+  }
+
+  const probeUrls = urls.slice(0, ROUTE_PROBE_MAX_URLS);
+  const skipped = urls.slice(ROUTE_PROBE_MAX_URLS)
+    .map((url) => ({ url, outcome: "skipped", method: null, http_status: null, error: null }));
+  const results = [...await probeAll(probeUrls, { timeoutMs, fetchImpl }), ...skipped];
+  const counts = summarize(results);
+
+  if (counts.unresolved > 0) {
+    const firstFailure = results.find((result) => result.outcome === "unresolved");
+    const hint = await routeRootHint({ results, baseUrl, publicRouteSlug, timeoutMs, fetchImpl });
+    const scope = counts.resolved === 0
+      ? `All ${counts.unresolved} derived entry URL(s) are dead on this host`
+      : `${counts.unresolved} of ${counts.unresolved + counts.resolved} derived entry URL(s) are dead on this host`;
+    return {
+      status: "failed",
+      code: "route_probe.routes_unresolved",
+      // The route-root diagnosis is long and belongs in exactly one place, so
+      // it stays on route_root_hint.reason rather than being inlined here too.
+      reason: `${scope}. First failure: ${describeFailure(firstFailure)}.`,
+      counts,
+      first_failure: firstFailure,
+      results,
+      route_root_hint: hint,
+    };
+  }
+
+  if (counts.resolved === 0) {
+    const firstFailure = results.find((result) => result.outcome === "unreachable");
+    return {
+      ...notProbed(
+        "route_probe.unreachable",
+        `No entry URL could be reached, so the route set is unverified rather than proven dead — a transport failure is evidence about this machine's network, not about the deployment. First failure: ${describeFailure(firstFailure)}.`,
+        results,
+      ),
+      first_failure: firstFailure,
+    };
+  }
+
+  // A pass reached over some unreachable URLs is partial reachability, not a
+  // clean sweep. `first_failure` carries the first of them so the structured
+  // field means the same thing on every branch, and the reason names it so an
+  // operator does not have to infer which URL from a bare count.
+  const firstUnreached = results.find((result) => result.outcome === "unreachable") || null;
+  return {
+    status: "pass",
+    code: "route_probe.all_resolved",
+    reason: firstUnreached
+      ? `${counts.resolved} entry URL(s) resolved; ${counts.unreachable} could not be reached from this machine. First unreached: ${describeFailure(firstUnreached)}.`
+      : `All ${counts.resolved} derived entry URL(s) resolved on this host.`,
+    counts,
+    first_failure: firstUnreached,
+    results,
+    route_root_hint: null,
+  };
+}
+
+async function routeRootHint({ results, baseUrl, publicRouteSlug, timeoutMs, fetchImpl }) {
+  // Only worth asking when the slug-rooted derivation is dead across the board.
+  if (results.some((result) => result.outcome === "resolved")) return null;
+  const withoutSlug = baseUrlWithoutSlug(baseUrl, publicRouteSlug);
+  if (!withoutSlug) return null;
+  const probe = await probeOneUrl(withoutSlug, { timeoutMs, fetchImpl });
+  const slug = normalizePublicRouteSlug(publicRouteSlug);
+  if (probe.outcome !== "resolved") {
+    return {
+      code: "route_probe.host_also_dead",
+      probed_url: withoutSlug,
+      result: probe,
+      reason: `${withoutSlug} does not resolve either, so the preview itself is likely dead rather than served under a different route root.`,
+    };
+  }
+  return {
+    code: "route_probe.route_root_mismatch",
+    probed_url: withoutSlug,
+    result: probe,
+    reason: `${withoutSlug} resolves but ${baseUrl} does not, so this host does not serve the campaign under the packet's public_route_slug "${slug}". resolve appends that slug from the packet on purpose — the packet is the authority on where the campaign is served — so the fix is to correct campaign.public_route_slug (or declare campaign.route_root) in the packet, not to pass a different --base-url.`,
+  };
+}

package/src/qa-sidecar.mjs

@@ -0,0 +1,188 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { dirname, join, resolve } from "node:path";
+
+import { deriveExceptions, validateVerdict } from "./qa-verdict.mjs";
+
+// The committed QA verdict sidecar: `.campaign-runtime/qa-verdict.json` beside
+// the Build Packet, the artifact campaigns-agent's readback projects. Full
+// verdicts under qa-output/ are gitignored because they carry live storefront
+// URLs, request evidence, and order references; the sidecar is committed to
+// merchant repos, so it is an allowlist PROJECTION of one verdict, never a
+// copy. Same schema ("1.0") — a second schema would fork the read end.
+
+export const SIDECAR_RELATIVE_PATH = ".campaign-runtime/qa-verdict.json";
+
+// Assertion fields that survive projection. Everything else — url, expected,
+// actual, evidence, request/response captures — stays in the full verdict.
+// `cause`/`cause_reason` survive projection: they are a short enum plus a
+// mechanical reason code — no URL, no order reference, no capture body — and
+// the committed sidecar is the artifact a readback reads, so stripping them
+// would leave the one consumer that cannot re-run QA unable to tell a
+// pre-existing finding from a regression.
+const ASSERTION_FIELDS = ["id", "family", "page", "status", "severity", "blocked_by", "cause", "cause_reason"];
+const EXCEPTION_FIELDS = ["id", "family", "page", "status", "severity", "cause", "cause_reason"];
+
+function pick(source, fields) {
+  const out = {};
+  for (const field of fields) {
+    if (source?.[field] !== undefined) out[field] = source[field];
+  }
+  return out;
+}
+
+/**
+ * Project one full QA verdict into its committable sidecar form. Pure:
+ * `generatedAt` is the promotion instant the caller stamps (writers pass the
+ * wall clock; tests pass a fixture). The projection must itself pass
+ * validateVerdict — the readback recognizes the sidecar by the same minimal
+ * schema as the full verdict.
+ */
+export function projectVerdictForSidecar(verdict, { generatedAt }) {
+  const errors = validateVerdict(verdict);
+  if (errors.length) {
+    throw new Error(`QA verdict failed validation before sidecar projection:\n- ${errors.join("\n- ")}`);
+  }
+  // Trust segregation (the readback chokepoint): the QA verdict receiver
+  // stamps `trusted: false` onto records that arrived without the ingest
+  // credential — anonymous submissions. Shape validity is NOT trust: a forged
+  // verdict passes validateVerdict by design. A record carrying that stamp
+  // must never be laundered into the committed sidecar campaigns-agent's
+  // readback consumes, so the projection refuses it outright instead of
+  // silently stripping the stamp. Fresh `qa run` verdicts never carry the
+  // field (it is server-stamped, not CLI-emitted), so this only ever fires on
+  // an explicit `qa promote` of a fetched, untrusted record. See
+  // docs/qa-and-test-orders.md (Verdict schema and trust semantics).
+  if (verdict.trusted === false) {
+    throw new Error(
+      "QA verdict is stamped trusted: false (an anonymous submission classified by the QA verdict receiver); "
+      + "refusing to project it into the committed sidecar. Promote a verdict this runner produced, or re-run QA.",
+    );
+  }
+  // Strict RFC3339 UTC with a Z suffix, not bare Date.parse: downstream
+  // freshness (readback staleness) documents the Z-suffixed form, and
+  // Date.parse would admit zone-less or locale strings that consumers can
+  // mis-parse.
+  if (typeof generatedAt !== "string" || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/.test(generatedAt)) {
+    throw new Error("Sidecar projection requires an ISO-8601 UTC generatedAt with a Z suffix.");
+  }
+  const assertions = (verdict.assertions || [])
+    .filter((assertion) => assertion && typeof assertion === "object")
+    .map((assertion) => pick(assertion, ASSERTION_FIELDS));
+  // Exceptions are re-derived from the PROJECTED assertions — which no longer
+  // carry url/expected/actual, so deriveExceptions can only emit null/absent
+  // for those keys — then pick() drops the null-valued keys themselves.
+  const exceptions = deriveExceptions(assertions).map((exception) => pick(exception, EXCEPTION_FIELDS));
+  return {
+    schema_version: verdict.schema_version,
+    run_id: verdict.run_id,
+    campaign_slug: verdict.campaign_slug,
+    ...(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,
+    spec_hash: verdict.spec_hash,
+    started_at: verdict.started_at,
+    completed_at: verdict.completed_at,
+    generated_at: generatedAt,
+    runtime: verdict.runtime,
+    disposition: verdict.disposition,
+    entry_urls: [],
+    page_urls: [],
+    tested_urls: [],
+    assertions,
+    test_orders: [],
+    exceptions,
+    ...(verdict.cause_summary && typeof verdict.cause_summary === "object" && !Array.isArray(verdict.cause_summary)
+      ? { cause_summary: verdict.cause_summary }
+      : {}),
+  };
+}
+
+export function sidecarPathForPacket(packetPath) {
+  return join(dirname(resolve(packetPath)), SIDECAR_RELATIVE_PATH);
+}
+
+const PACKET_SCHEMA = "campaign-runtime-build-packet/v0";
+
+/**
+ * Assert the sidecar anchor is a real Build Packet before any write. A typo'd
+ * or stale --packet path would otherwise scatter qa-verdict.json sidecars
+ * into unrelated trees — exactly the artifact sprawl the contracted home
+ * exists to prevent.
+ */
+function assertPacketAnchor(packetPath) {
+  let raw;
+  try {
+    raw = readFileSync(resolve(packetPath), "utf8");
+  } catch (error) {
+    // error.code only, never error.message: raw fs messages can carry local
+    // uid/path detail that does not belong in surfaced output.
+    throw new Error(`Sidecar anchor ${packetPath} is not a readable Build Packet (${error.code || "unreadable"}).`);
+  }
+  let packet;
+  try {
+    packet = JSON.parse(raw);
+  } catch {
+    throw new Error(`Sidecar anchor ${packetPath} is not a readable Build Packet (not valid JSON).`);
+  }
+  if (packet?.schema_version !== PACKET_SCHEMA) {
+    throw new Error(`Sidecar anchor ${packetPath} is not a Build Packet (expected schema_version ${PACKET_SCHEMA}).`);
+  }
+}
+
+function writeJsonAtomicAt(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${randomUUID()}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`);
+  renameSync(tmp, path);
+}
+
+/**
+ * Write the sidecar for a just-finalized verdict object. Called by `qa run`
+ * after local validation, before the exit-code decision, so blocked runs get
+ * a sidecar too (disposition is a recorded fact, not a write gate) and a run
+ * that dies before finalization never touches an existing sidecar.
+ */
+export function writeQaSidecar({ verdict, packetPath, now = () => new Date().toISOString() }) {
+  assertPacketAnchor(packetPath);
+  const projected = projectVerdictForSidecar(verdict, { generatedAt: now() });
+  const destination = sidecarPathForPacket(packetPath);
+  writeJsonAtomicAt(destination, projected);
+  return { path: destination, run_id: projected.run_id, disposition: projected.disposition, generated_at: projected.generated_at };
+}
+
+/**
+ * Explicit backfill: promote one named full verdict file to the sidecar.
+ * Both paths are required; nothing is selected by mtime or filename order —
+ * "latest" scans are how a wrong run gets promoted. The destination sidecar
+ * is refused as a source so CI cannot launder an old projection into a fresh
+ * timestamp. Validation happens before any write; on failure the prior
+ * sidecar bytes are untouched.
+ */
+export function promoteQaVerdict({ verdictPath, packetPath, now = () => new Date().toISOString() }) {
+  if (!verdictPath || !packetPath) {
+    throw new Error("qa promote requires both --verdict <full-verdict.json> and --packet <campaign-runtime.build.json>.");
+  }
+  assertPacketAnchor(packetPath);
+  const source = resolve(verdictPath);
+  const destination = sidecarPathForPacket(packetPath);
+  if (source === destination) {
+    throw new Error("qa promote refuses the destination sidecar as its own source: promote from the full verdict under qa-output/, not from a prior projection.");
+  }
+  let verdict;
+  try {
+    verdict = JSON.parse(readFileSync(source, "utf8"));
+  } catch (error) {
+    throw new Error(`qa promote could not read the source verdict at ${source}: ${error.message}`);
+  }
+  const projected = projectVerdictForSidecar(verdict, { generatedAt: now() });
+  writeJsonAtomicAt(destination, projected);
+  return {
+    ok: true,
+    source: source,
+    destination,
+    run_id: projected.run_id,
+    disposition: projected.disposition,
+    generated_at: projected.generated_at,
+  };
+}

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

@@ -0,0 +1,207 @@
+export const OFFER_PAGE_TYPES = new Set(["upsell", "downsell"]);
+export const RECEIPT_PAGE_TYPES = new Set(["receipt", "thankyou"]);
+const ACTIONS = Object.freeze([
+  ["decline", "expected_decline_url"],
+  ["accept", "expected_accept_url"],
+]);
+
+export function resolveTestOrderTopology(topology = {}, checkoutPage = null) {
+  const pages = Array.isArray(topology?.pages) ? topology.pages : [];
+  const checkout = checkoutPage || pages.find((page) => pageType(page) === "checkout") || null;
+  const pagesByUrl = new Map();
+  for (const page of pages) {
+    const key = canonicalHttpUrl(page?.url);
+    if (key && !pagesByUrl.has(key)) pagesByUrl.set(key, page);
+  }
+  const topologyOrigin = httpOrigin(checkout?.url) || pages.map((page) => httpOrigin(page?.url)).find(Boolean) || null;
+
+  const terminalPaths = [];
+  const invalidPaths = [];
+  const entry = checkout ? targetNode(checkout.expected_next_url, pagesByUrl, topologyOrigin) : null;
+  if (entry?.kind === "offer") {
+    walkOffer(entry.page, [], new Set(), pagesByUrl, topologyOrigin, terminalPaths, invalidPaths);
+  } else if (entry?.kind === "invalid") {
+    invalidPaths.push({ path: "checkout", reason: entry.reason, target: entry.target });
+  }
+  const recognizedTerminals = dedupeTerminals([
+    ...pages
+      .filter((page) => RECEIPT_PAGE_TYPES.has(pageType(page)) && canonicalHttpUrl(page?.url))
+      .map((page) => ({ kind: "receipt", page_id: page.page_id || null, url: page.url })),
+    ...(entry?.kind === "terminal" ? [entry.terminal] : []),
+    ...terminalPaths.map((candidate) => candidate.terminal),
+  ]);
+
+  return {
+    topology_id: topology?.funnel_id || "default",
+    checkout_page_id: checkout?.page_id || null,
+    checkout_url: checkout?.url || null,
+    // Retain every declared page for diagnostics, including malformed rows.
+    // pageAtUrl still matches only canonical HTTP URLs, but the resolved plan
+    // does not silently erase the topology evidence that explains a miss.
+    route_pages: pages.map((page) => ({
+      page_id: page.page_id || null,
+      page_type: page.page_type || null,
+      url: page.url || null,
+    })),
+    has_offer_entry: entry?.kind === "offer",
+    full_paths: terminalPaths.map((candidate) => candidate.path),
+    terminal_paths: terminalPaths,
+    invalid_paths: invalidPaths,
+    recognized_terminals: recognizedTerminals,
+  };
+}
+
+export function terminalAtUrl(resolvedTopology, value) {
+  const key = canonicalHttpUrl(value);
+  if (!key) return null;
+  return (resolvedTopology?.recognized_terminals || []).find((terminal) => canonicalHttpUrl(terminal?.url) === key) || null;
+}
+
+export function pageAtUrl(resolvedTopology, value) {
+  const key = canonicalHttpUrl(value);
+  if (!key) return null;
+  return (resolvedTopology?.route_pages || []).find((page) => canonicalHttpUrl(page?.url) === key) || null;
+}
+
+export function remainingActionDisposition(resolvedTopology, value, remainingActions = []) {
+  if (!Array.isArray(remainingActions) || !remainingActions.length) return { stop: false };
+  const terminal = terminalAtUrl(resolvedTopology, value);
+  if (!terminal) return { stop: false };
+  return { stop: true, terminal, remaining_actions: [...remainingActions] };
+}
+
+export function fullTestOrderPaths(resolvedTopology) {
+  const invalid = Array.isArray(resolvedTopology?.invalid_paths) ? resolvedTopology.invalid_paths : [];
+  if (invalid.length) {
+    const details = invalid
+      .map((candidate) => `${candidate.path || "checkout"}: ${candidate.reason}${candidate.target ? ` (${candidate.target})` : ""}`)
+      .join("; ");
+    throw new Error(
+      `--test-order full cannot enumerate actual terminal paths for funnel ${resolvedTopology?.topology_id || "default"}: ${details}`,
+    );
+  }
+  return ["checkout", ...(resolvedTopology?.full_paths || [])];
+}
+
+export function commonTestOrderPaths(resolvedTopology) {
+  if (resolvedTopology?.has_offer_entry !== true) return ["checkout"];
+  const paths = ["checkout", "accept", "decline"];
+  const receiptPaths = (resolvedTopology?.terminal_paths || [])
+    .filter((candidate) => candidate?.terminal?.kind === "receipt")
+    .slice()
+    .sort(compareCommonReceiptPaths);
+  const shortest = receiptPaths[0]?.path;
+  if (shortest && !paths.includes(shortest)) paths.push(shortest);
+  return paths;
+}
+
+function compareCommonReceiptPaths(left, right) {
+  const lengthDelta = (left?.steps?.length || 0) - (right?.steps?.length || 0);
+  if (lengthDelta) return lengthDelta;
+  if (left?.path === "accept-decline" && right?.path !== "accept-decline") return -1;
+  if (right?.path === "accept-decline" && left?.path !== "accept-decline") return 1;
+  return compareActionSteps(left?.steps || [], right?.steps || []);
+}
+
+function compareActionSteps(left, right) {
+  const rank = { accept: 0, decline: 1 };
+  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    if (left[index] === right[index]) continue;
+    return (rank[left[index]] ?? 2) - (rank[right[index]] ?? 2);
+  }
+  return left.length - right.length;
+}
+
+function walkOffer(page, steps, visited, pagesByUrl, topologyOrigin, terminalPaths, invalidPaths) {
+  const pageKey = canonicalHttpUrl(page?.url) || `page:${page?.page_id || "unknown"}`;
+  if (visited.has(pageKey)) {
+    invalidPaths.push({ path: steps.join("-"), reason: "cycle", target: page?.url || page?.page_id || null });
+    return;
+  }
+  const nextVisited = new Set(visited).add(pageKey);
+
+  for (const [action, field] of ACTIONS) {
+    const nextSteps = [...steps, action];
+    const target = targetNode(page?.[field], pagesByUrl, topologyOrigin);
+    if (target?.kind === "terminal") {
+      terminalPaths.push({
+        path: nextSteps.join("-"),
+        steps: nextSteps,
+        terminal: target.terminal,
+      });
+    } else if (target?.kind === "offer") {
+      walkOffer(target.page, nextSteps, nextVisited, pagesByUrl, topologyOrigin, terminalPaths, invalidPaths);
+    } else if (target?.kind === "invalid") {
+      invalidPaths.push({ path: nextSteps.join("-"), reason: target.reason, target: target.target });
+    }
+  }
+}
+
+function targetNode(value, pagesByUrl, topologyOrigin) {
+  const key = canonicalHttpUrl(value);
+  if (!key) {
+    return value == null || String(value).trim() === ""
+      ? { kind: "invalid", reason: "missing_route", target: null }
+      : { kind: "invalid", reason: "unresolved_target", target: String(value) };
+  }
+  const page = pagesByUrl.get(key);
+  if (page) {
+    const type = pageType(page);
+    if (RECEIPT_PAGE_TYPES.has(type)) {
+      return {
+        kind: "terminal",
+        terminal: { kind: "receipt", page_id: page.page_id || null, url: page.url || value },
+      };
+    }
+    if (OFFER_PAGE_TYPES.has(type)) return { kind: "offer", page };
+    return { kind: "invalid", reason: "nonterminal_target", target: page.url || value };
+  }
+  if (topologyOrigin && httpOrigin(key) !== topologyOrigin) {
+    return {
+      kind: "terminal",
+      terminal: { kind: "external_handoff", page_id: null, url: value },
+    };
+  }
+  return { kind: "invalid", reason: "unresolved_target", target: value };
+}
+
+function dedupeTerminals(terminals) {
+  const seen = new Set();
+  const deduped = [];
+  for (const terminal of terminals) {
+    const key = canonicalHttpUrl(terminal?.url);
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    deduped.push(terminal);
+  }
+  return deduped;
+}
+
+export function canonicalHttpUrl(value) {
+  if (typeof value !== "string" || !value.trim()) return null;
+  try {
+    const url = new URL(value.trim());
+    if (!/^https?:$/.test(url.protocol)) return null;
+    url.search = "";
+    url.hash = "";
+    url.pathname = url.pathname
+      .replace(/\/index\.html$/i, "/")
+      .replace(/\/+$/, "") || "/";
+    return url.toString();
+  } catch {
+    return null;
+  }
+}
+
+function httpOrigin(value) {
+  try {
+    const url = new URL(String(value || ""));
+    return /^https?:$/.test(url.protocol) ? url.origin : null;
+  } catch {
+    return null;
+  }
+}
+
+function pageType(page) {
+  return String(page?.page_type || "").toLowerCase().replace(/[-_]/g, "");
+}

package/src/qa-url-privacy.mjs

@@ -0,0 +1,13 @@
+// Canonical URL projection for QA evidence and private capture attribution.
+// Query strings and fragments may contain ref/order identifiers, so every
+// caller gets the same conservative projection, including malformed inputs.
+export function redactUrlQuery(value) {
+  if (value === null || value === undefined) return null;
+  const text = String(value);
+  try {
+    const url = new URL(text);
+    return `${url.origin}${url.pathname}`;
+  } catch {
+    return text.split(/[?#]/)[0] || null;
+  }
+}