@nextcommerce/campaigns-os 1.33.0

package/src/private-template-source.mjs

@@ -0,0 +1,237 @@
+// Private template family resolution: campaigns-os recognizes/certifies a
+// private template family (its design, selectors, and business logic owned
+// by a third-party repo, not this one) without that family's description
+// ever being committed here. The public repo holds only a thin allowlist —
+// contracts/private-template-sources.json — naming which families are
+// private and which repo/path to fetch their contract fragment from. The
+// fragment is resolved in-memory per run and never written back to disk.
+//
+// v1 resolves only from a local sibling checkout (matches this environment's
+// worktree convention: sibling repos share a parent directory). A hosted CI
+// runner without that checkout simply cannot certify a private family today —
+// that's an intentional v1 boundary, not an oversight; see the transfer
+// packet this module implements.
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadTemplateBrandContract, resolveContractExtendsChain } from "./template-brand-contract.mjs";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+export const PRIVATE_TEMPLATE_SOURCE_SCHEMA = "private-template-source/v0";
+export const PRIVATE_TEMPLATE_SOURCE_FRAGMENT_SCHEMA = "private-template-source-fragment/v0";
+
+// One JSON read + parse path for every file this module reads, so a malformed
+// file surfaces as a structured parse_error (with the syntax error preserved
+// as `cause`) instead of a bare SyntaxError — the same convention the on-disk
+// brand-contract loader uses. Callers that want to swallow it (e.g.
+// certifiedTemplateFamilies) still catch a throw; callers that surface
+// diagnostics get a code to key on.
+function readJsonFile(path, what) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    throw privateTemplateSourceError(
+      "parse_error",
+      `${what} ${path} failed to parse: ${error instanceof Error ? error.message : String(error)}.`,
+      error,
+    );
+  }
+}
+
+export function defaultCommerceCatalogPath() {
+  return join(ROOT, "contracts", "commerce-surface-catalog.json");
+}
+
+export const COMMERCE_CATALOG_FILE_NAME = "commerce-surface-catalog.json";
+
+// The commerce catalog a packet reads. `assembly.commerce_catalog.path` is
+// null when the packet was prepared against the toolkit's own catalog: that
+// file ships with every install of the toolkit, so the packet does not record
+// where one particular checkout kept it. A recorded path is an operator's
+// explicit --commerce-catalog, resolved against the packet. A recorded path
+// that no longer exists but names the catalog file is the pre-null shape:
+// packets prepared before the catalog stopped being recorded wrote the
+// toolkit's own file relative to the packet (a chain of ../ into the checkout
+// that ran prepare-build), which is dead on any other machine or with the
+// toolkit installed as a package. Readers resolve that to the running
+// toolkit's catalog, and `source` says which of the four cases applied
+// (toolkit_default, packet, stale_packet_path, missing_packet_path) so doctor
+// can tell the operator without blocking.
+export function resolvePacketCommerceCatalogPath(packetPath, catalogInfo = {}) {
+  const recorded = typeof catalogInfo?.path === "string" && catalogInfo.path.length > 0 ? catalogInfo.path : null;
+  if (!recorded) {
+    return { path: defaultCommerceCatalogPath(), source: "toolkit_default", recorded: null };
+  }
+  const resolved = resolve(dirname(resolve(packetPath)), recorded);
+  if (existsSync(resolved)) {
+    return { path: resolved, source: "packet", recorded };
+  }
+  if (basename(recorded) === COMMERCE_CATALOG_FILE_NAME) {
+    return { path: defaultCommerceCatalogPath(), source: "stale_packet_path", recorded };
+  }
+  // The operator named a file that is not there and is not the toolkit
+  // catalog: keep the resolved path so the caller's missing-file check names
+  // it, and say plainly that nothing resolved.
+  return { path: resolved, source: "missing_packet_path", recorded };
+}
+
+// Overridable so tests can sandbox the allowlist against a fixture private
+// source instead of mutating (or depending on) the real production file.
+function privateTemplateSourcesPath() {
+  return process.env.PRIVATE_TEMPLATE_SOURCES_PATH || join(ROOT, "contracts", "private-template-sources.json");
+}
+
+// No caching, recomputed per call — matches certifiedTemplateFamilies()'s
+// existing convention (cli.mjs) so a long-lived process never serves a stale
+// allowlist after an edit.
+export function loadPrivateTemplateSources() {
+  const path = privateTemplateSourcesPath();
+  if (!existsSync(path)) return {};
+  const parsed = readJsonFile(path, "Private template source allowlist");
+  if (!isPlainObject(parsed) || parsed.schema_version !== PRIVATE_TEMPLATE_SOURCE_SCHEMA) {
+    throw privateTemplateSourceError(
+      "schema_mismatch",
+      `Private template source allowlist ${path} has schema_version "${parsed?.schema_version}"; expected "${PRIVATE_TEMPLATE_SOURCE_SCHEMA}".`,
+    );
+  }
+  return isPlainObject(parsed.sources) ? parsed.sources : {};
+}
+
+// Base directory sibling repos are resolved under. One env var covers every
+// private provider (there will be more than one over time) — mirrors the
+// existing STARTER_TEMPLATES_PATH precedent (scripts/check-template-doctrine.mjs)
+// generalized from "one specific sibling" to "wherever this environment keeps
+// its siblings".
+function privateTemplateSourcesRoot() {
+  return process.env.PRIVATE_TEMPLATE_SOURCES_ROOT || resolve(ROOT, "..");
+}
+
+// The sibling checkout directory for a "org/name" repo string: only the final
+// path segment (the repo name) is used as the directory; the org is metadata.
+// The allowlist is committed in-repo and human-reviewed before merge, so the
+// repo/contract_path fields are trusted input, not attacker-controlled — no
+// shape/traversal guard here by design (see the module header's v1 boundary).
+function siblingRepoDir(repo) {
+  const name = String(repo || "").trim().split("/").pop();
+  return name ? join(privateTemplateSourcesRoot(), name) : null;
+}
+
+// Allowlist miss -> null (family isn't private; caller falls through to its
+// own "unknown family" handling). Allowlist hit but no local checkout ->
+// throws, deliberately: a private family must fail loudly and specifically
+// when it's actually needed, never silently read as "uncertified" — that's a
+// confusing dead end for whoever hits it.
+export function resolvePrivateTemplateSourceFragment(family) {
+  const entry = loadPrivateTemplateSources()[family];
+  if (!entry) return null;
+  const repoDir = siblingRepoDir(entry.repo);
+  const fragmentPath = repoDir && typeof entry.contract_path === "string" ? join(repoDir, entry.contract_path) : null;
+  if (!fragmentPath || !existsSync(fragmentPath)) {
+    throw privateTemplateSourceError(
+      "private_source_not_checked_out",
+      `Template family "${family}" is a private family sourced from ${entry.repo}, but no checkout was found at ` +
+        `${repoDir || "(unresolved)"}. Clone ${entry.repo} as a sibling directory (or set PRIVATE_TEMPLATE_SOURCES_ROOT) to resolve it.`,
+    );
+  }
+  const fragment = readJsonFile(fragmentPath, "Private template source fragment");
+  if (!isPlainObject(fragment) || fragment.schema_version !== PRIVATE_TEMPLATE_SOURCE_FRAGMENT_SCHEMA) {
+    throw privateTemplateSourceError(
+      "schema_mismatch",
+      `Private template source fragment ${fragmentPath} has schema_version "${fragment?.schema_version}"; expected "${PRIVATE_TEMPLATE_SOURCE_FRAGMENT_SCHEMA}".`,
+    );
+  }
+  if (fragment.family !== family) {
+    throw privateTemplateSourceError(
+      "family_mismatch",
+      `Private template source fragment ${fragmentPath} declares family "${fragment.family}"; expected "${family}".`,
+    );
+  }
+  return { catalogFamily: fragment.catalog_family || null, brandContract: fragment.brand_contract || null, fragmentPath };
+}
+
+// Enriches the raw commerce catalog with private family entries. The returned
+// object carries an extra `_private_source_warnings` array (not present in the
+// raw catalog) documenting any private-source fetch errors encountered while
+// building the merged family map — callers that spread or JSON.stringify the
+// result will see this key; callers that only read `.families` are unaffected.
+// Private-source fetch errors are collected as warnings, never thrown here — a
+// public-family run must not fail just because some other private repo isn't
+// checked out locally. Only resolveTemplateBrandContract (below), for that
+// specific family, throws.
+export function resolveCommerceCatalog(catalogPath = defaultCommerceCatalogPath()) {
+  const catalog = existsSync(catalogPath) ? readJsonFile(catalogPath, "Commerce surface catalog") : { families: {} };
+  // Valid JSON that isn't an object (null / array / scalar) would make
+  // `catalog.families` throw a raw TypeError; surface it as the same
+  // structured schema_mismatch the allowlist/fragment reads already use.
+  if (!isPlainObject(catalog)) {
+    throw privateTemplateSourceError(
+      "schema_mismatch",
+      `Commerce catalog ${catalogPath} is not a JSON object.`,
+    );
+  }
+  const families = { ...(catalog.families || {}) };
+  const warnings = [];
+  for (const family of Object.keys(loadPrivateTemplateSources())) {
+    if (Object.prototype.hasOwnProperty.call(families, family)) continue;
+    try {
+      const fragment = resolvePrivateTemplateSourceFragment(family);
+      if (fragment?.catalogFamily) families[family] = fragment.catalogFamily;
+    } catch (error) {
+      warnings.push({ family, code: error.code || "load_error", message: error.message });
+    }
+  }
+  return { ...catalog, families, _private_source_warnings: warnings };
+}
+
+// Drop-in for loadTemplateBrandContract(family): tries the public loader
+// first (zero behavior change for public families), then falls back to a
+// privately-sourced fragment, run through the SAME extends/merge chain
+// template-brand-contract.mjs already uses — `dir` is this repo's own
+// contracts/ directory, since a private family's `extends` (e.g.
+// "template-brand-contract.shared-commerce.v0.json") points at a genuinely
+// shared, public file that lives here, not in the private repo.
+//
+// If a public contract file exists but fails to parse/validate, the error is
+// caught and a private fragment is tried as a fallback (a corrected private
+// fragment resolves even when a stale public stub is still on disk). Error
+// precedence when the public load failed: if the family is NOT privately
+// allowlisted, the original public error is re-thrown so the operator sees the
+// root cause; if it IS allowlisted but fragment resolution itself throws (e.g.
+// the sibling checkout is missing), that more-specific error surfaces instead.
+export function resolveTemplateBrandContract(family) {
+  let publicContract = null;
+  let publicError = null;
+  try {
+    publicContract = loadTemplateBrandContract(family);
+  } catch (err) {
+    publicError = err;
+  }
+  if (publicContract) return publicContract;
+  const fragment = resolvePrivateTemplateSourceFragment(family);
+  if (!fragment?.brandContract) {
+    if (publicError) throw publicError;
+    return null;
+  }
+  const contract = resolveContractExtendsChain(fragment.brandContract, {
+    dir: join(ROOT, "contracts"),
+    label: fragment.fragmentPath,
+  });
+  if (contract.family !== family) {
+    throw privateTemplateSourceError(
+      "family_mismatch",
+      `Private template brand contract ${fragment.fragmentPath} declares family "${contract.family}"; expected "${family}".`,
+    );
+  }
+  return contract;
+}
+
+function privateTemplateSourceError(code, message, cause = undefined) {
+  const error = new Error(message, cause ? { cause } : undefined);
+  error.code = code;
+  return error;
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/src/proof-policy.mjs

@@ -0,0 +1,82 @@
+// Proof policy: the order-path depth a Build Packet declares, the one flag
+// that sets it, and the one text that names the drift between the packet and
+// the Assembly Report's mirror of it.
+//
+// `qa.proof_policy.order_path_depth` is seeded by prepare-build/start and
+// mirrored into `report.proof_policy` at the same moment. The two are compared
+// by `assessPurchaseProofCoverage` (cli.mjs): a disagreement is `unknown`,
+// never one side's value. Doctor, `next` and the coverage reason all describe
+// that state through the single action below, so the command an operator is
+// told to run is spelled once. A leaf: gate-actions only.
+
+import { requiredActionText } from "./gate-actions.mjs";
+
+// The depths the setter accepts. `off` declares an intentional no-order run
+// (`--test-order off` is then a diagnostic that owes no purchase proof);
+// `common` and `full` match the `--test-order` modes of the same name.
+export const ORDER_PATH_DEPTHS = Object.freeze(["off", "common", "full"]);
+
+export const ORDER_PATH_DEPTH_FLAG = "order-path-depth";
+
+export function isOrderPathDepth(value) {
+  return typeof value === "string" && ORDER_PATH_DEPTHS.includes(value);
+}
+
+// The one spelling of "the packet and the report disagree": both present and
+// different once case is ignored. `orderPathDepthDrift` (doctor and the
+// coverage assessment) and the `next` action branch both ask this.
+export function orderPathDepthsDisagree(packetDepth, reportDepth) {
+  return typeof packetDepth === "string" && typeof reportDepth === "string"
+    && packetDepth.trim() !== "" && reportDepth.trim() !== ""
+    && packetDepth.toLowerCase() !== reportDepth.toLowerCase();
+}
+
+// `--order-path-depth <off|common|full>`, validated with the other argv checks
+// of whichever command carries it (`command` names it in the error). A bare
+// flag parses as `true`; that is an operator's explicit intent with no value,
+// so it is refused rather than silently defaulted. Case is ignored on input
+// and the lower-case canonical form is what gets stored (`Off` writes `off`),
+// matching the case-insensitive drift comparison. Returns null when the flag
+// is absent.
+export function parseOrderPathDepthFlag(args, { command = "qa policy set" } = {}) {
+  const raw = args?.[ORDER_PATH_DEPTH_FLAG];
+  if (raw === undefined) return null;
+  const accepted = `Accepted values: ${ORDER_PATH_DEPTHS.join(", ")}.`;
+  if (raw === true || raw === null || String(raw).trim() === "") {
+    throw new Error(`${command}: --${ORDER_PATH_DEPTH_FLAG} needs a value. ${accepted}`);
+  }
+  const typed = String(raw).trim();
+  const value = typed.toLowerCase();
+  if (!isOrderPathDepth(value)) {
+    throw new Error(`${command}: unsupported --${ORDER_PATH_DEPTH_FLAG} ${JSON.stringify(typed)}. ${accepted}`);
+  }
+  return value;
+}
+
+export const ORDER_PATH_DEPTH_DRIFT_CODE = "qa.proof_policy.order_path_depth_drift";
+
+// The one action that reconciles a packet/report depth disagreement: rewrite
+// the depth through the setter, which writes the packet field and refreshes
+// the report mirror in the same run. The packet's value is offered when the
+// setter accepts it (the packet is author intent); a hand-edited value outside
+// the accepted set leaves the choice to the operator.
+export function orderPathDepthReconcileAction({ packetDepth = null, reportDepth = null } = {}) {
+  const depth = isOrderPathDepth(packetDepth) ? packetDepth : `<${ORDER_PATH_DEPTHS.join("|")}>`;
+  return Object.freeze({
+    id: ORDER_PATH_DEPTH_DRIFT_CODE,
+    kind: "command",
+    command: `campaigns-os qa policy set --packet <packet> --${ORDER_PATH_DEPTH_FLAG} ${depth}`,
+    description: `The build packet declares an order-path depth of ${JSON.stringify(packetDepth ?? "unspecified")} while the assembly report's mirror of it reads ${JSON.stringify(reportDepth ?? "unspecified")}; neither is trusted until they agree.`,
+  });
+}
+
+// The text doctor's warning, the coverage reason and the `next` action all
+// carry for that state: the description, then the runnable command with the
+// packet substituted (or the bare template when no packet path is known). A
+// caller that already rendered the command (to publish it as the action's
+// `command`) passes it in, so the prose and the action carry one string.
+export function orderPathDepthDriftText({ packetDepth = null, reportDepth = null, packetPath = null, command = null } = {}) {
+  const action = orderPathDepthReconcileAction({ packetDepth, reportDepth });
+  const rendered = typeof command === "string" && command ? command : requiredActionText(action, { packetPath });
+  return `${action.description} Reconcile them with \`${rendered}\`, which writes the packet field and refreshes the report mirror together.`;
+}

package/src/qa-analytics-correctness.mjs

@@ -0,0 +1,307 @@
+// Analytics CORRECTNESS assessment (single funnel) — the foundation layer the
+// migration parity differ sits on top of. Where parity asks "does candidate
+// match baseline?", correctness has two deliberately separate authorities:
+// campaign-root inventory proves declared providers/tags are present, while
+// receipt evidence from the canonical typed-card order proves Purchase. A
+// campaign-root visit cannot prove (or disprove) a receipt-only event.
+//
+// Driven by the CampaignSpec `analytics` block (campaign-spec AnalyticsContract).
+// When no block is declared the assessment can't know the expected container/
+// pixel ids, so it emits an INFO inventory only — nothing is gated. The contract
+// is what turns observations into pass/fail. (Until the spec authoring tool
+// emits the block, real specs won't carry one — so the no-contract path is the
+// common case today and must stay non-blocking.)
+//
+// Receipt proof is source-aware by construction: it keys on OUTBOUND pixel
+// fires (the network truth), via effectivePurchase, so a campaign that blocks
+// the SDK dl_* event and fires the pixel manually still passes.
+
+import { SEVERITY, STATUS } from "./qa-verdict.mjs";
+import { effectivePurchase } from "./qa-analytics-parity.mjs";
+import { redactUrlQuery } from "./qa-url-privacy.mjs";
+
+// Inventory kinds classifyTagFire can recognize directly. Other declared
+// out-of-band vendors (TriplePixel→triplewhale, etc.) can't be auto-detected
+// without host wiring, so they degrade to manual review rather than false-fail.
+const KNOWN_VENDOR_KINDS = new Set(["gtm", "ga4", "google_ads", "meta", "tiktok", "everflow"]);
+
+// Packet 01 / INV-3(c): when the assessment knows the URL it audited, EVERY
+// emitted assertion — pass and fail alike — carries it, top-level and in
+// evidence, so a reader of a blocked verdict can always tell what was
+// measured (only the sibling :capture assertion used to carry it).
+function correctnessAssertion({ id, status, severity, expected, actual, evidence, waiver, url }) {
+  return {
+    id,
+    family: "analytics-correctness",
+    page: "analytics",
+    status,
+    ...(url ? { url } : {}),
+    ...(severity ? { severity } : {}),
+    ...(waiver ? { waiver } : {}),
+    expected,
+    actual,
+    ...(evidence || url ? { evidence: { ...(url ? { url } : {}), ...(evidence || {}) } } : {}),
+  };
+}
+
+// The ONLY assertion the QA waiver lane covers today (packet 01, ratified
+// I-9/I-16): a recorded `qa waive` decision for purchase-fires. The caller
+// decides eligibility: only a genuine, recognized receipt with no effective
+// Purchase may consume the waiver. Missing/unrecognized paths and capture
+// errors cannot.
+function purchaseFiresWaiver(options, eligible) {
+  if (!eligible) return null;
+  const waiver = options?.waivers?.["analytics-correctness:purchase-fires"];
+  if (!waiver || typeof waiver !== "object" || Array.isArray(waiver)) return null;
+  if (typeof waiver.reason !== "string" || !waiver.reason.trim()) return null;
+  return {
+    reason: waiver.reason.trim(),
+    waived_by: (typeof waiver.waived_by === "string" && waiver.waived_by.trim()) || "operator",
+    waived_at: (typeof waiver.waived_at === "string" && waiver.waived_at.trim()) || null,
+  };
+}
+
+function inventoryHas(inventory, kind, id) {
+  const ids = inventory[kind] || [];
+  return id ? ids.includes(String(id)) : ids.length > 0;
+}
+
+// Assess the campaign-root capture against its declared analytics inventory.
+// `contract` is the spec's `analytics` block (may be undefined/empty).
+// `options.url` is the URL the capture actually visited (the resolved capture
+// target) — stamped on every emitted assertion, pass and fail alike.
+export function assessAnalyticsInventory(capture = {}, contract = {}, options = {}) {
+  const assertions = [];
+  const auditedUrl = (typeof options.url === "string" && options.url.trim()) ? options.url.trim() : null;
+  const emit = (fields) => correctnessAssertion({ url: auditedUrl, ...fields });
+  const inventory = capture.inventory || {};
+  const providers = (contract && contract.providers) || {};
+  const hasContract = !!(contract && (contract.providers || contract.out_of_band_pixels || contract.params || contract.manual_events));
+
+  // No declared contract → can't know expected ids; emit a non-gating inventory
+  // so the run still records what fired, and flag that nothing was validated.
+  if (!hasContract) {
+    assertions.push(emit({
+      id: "analytics-correctness:no-contract",
+      status: STATUS.MANUAL_REVIEW,
+      severity: SEVERITY.INFO,
+      expected: "a declared CampaignSpec analytics block to validate against",
+      actual: "no analytics contract declared — recorded the observed fires, gated nothing",
+      // Counts only — never publish raw container/pixel ids or any Purchase
+      // fields to the QA portal. Root inventory is not Purchase authority.
+      evidence: {
+        inventory: Object.fromEntries(Object.entries(inventory).map(([k, v]) => [k, v.length])),
+      },
+    }));
+    return assertions;
+  }
+
+  // 1. GTM container fires (blocker when declared + enabled).
+  if (providers.gtm && providers.gtm.enabled !== false) {
+    const id = providers.gtm.containerId;
+    const present = inventoryHas(inventory, "gtm", id);
+    assertions.push(emit({
+      id: "analytics-correctness:tag:gtm",
+      status: present ? STATUS.PASS : STATUS.FAIL,
+      severity: SEVERITY.BLOCKER,
+      expected: `GTM ${id || "container"} fires on the page`,
+      actual: present ? "present" : `absent (${(inventory.gtm || []).length} gtm tag(s) fired, none matching)`,
+      evidence: { declared: id || null, observed_count: (inventory.gtm || []).length },
+    }));
+  }
+
+  // 2. Meta pixel fires (blocker when declared + enabled).
+  if (providers.facebook && providers.facebook.enabled !== false) {
+    const id = providers.facebook.pixelId;
+    const present = inventoryHas(inventory, "meta", id);
+    assertions.push(emit({
+      id: "analytics-correctness:tag:meta",
+      status: present ? STATUS.PASS : STATUS.FAIL,
+      severity: SEVERITY.BLOCKER,
+      expected: `Meta pixel ${id || ""} fires on the page`.trim(),
+      actual: present ? "present" : `absent (${(inventory.meta || []).length} meta pixel(s) fired, none matching)`,
+      evidence: { declared: id || null, observed_count: (inventory.meta || []).length },
+    }));
+  }
+
+  // 3. Out-of-band pixels declared as carried (Everflow / TriplePixel / …).
+  for (const [i, pixel] of (contract.out_of_band_pixels || []).entries()) {
+    if (!pixel || !pixel.vendor) continue;
+    const vendor = String(pixel.vendor).toLowerCase();
+    if (KNOWN_VENDOR_KINDS.has(vendor)) {
+      const present = inventoryHas(inventory, vendor, pixel.id);
+      assertions.push(emit({
+        id: `analytics-correctness:oob:${vendor}`,
+        status: present ? STATUS.PASS : STATUS.FAIL,
+        severity: SEVERITY.BLOCKER,
+        expected: `declared out-of-band ${vendor} pixel fires`,
+        actual: present ? "present" : "absent",
+        evidence: { vendor, declared_id: pixel.id || null, observed_count: (inventory[vendor] || []).length },
+      }));
+    } else {
+      // Vendor host not in the classifier (e.g. TriplePixel→triplewhale.com).
+      // Pass its name as --analytics-hosts to capture it; until then, review.
+      assertions.push(emit({
+        id: `analytics-correctness:oob:${vendor}`,
+        status: STATUS.MANUAL_REVIEW,
+        severity: SEVERITY.WARN,
+        expected: `declared out-of-band ${vendor} pixel fires`,
+        actual: `cannot auto-detect "${vendor}" — pass its host via --analytics-hosts to verify`,
+        evidence: { vendor, index: i },
+      }));
+    }
+  }
+
+  return assertions;
+}
+
+// Finalize the one stable Purchase assertion from the private capture envelope
+// returned by the canonical typed-card browser-order run. This function is
+// intentionally pure and emits only a fixed, sanitized evidence projection;
+// raw captures, event payloads, order identifiers, values, currencies, and URL
+// query strings never cross into the verdict.
+//
+// The receipt is the qualification point, not the measurement point (#392).
+// The SDK fires dl_purchase — and the outbound Purchase it drives — on the
+// first `?ref_id=` page that fetched the order, which is the upsell page on a
+// funnel that has one, and then dedupes the transaction so the receipt stays
+// silent. So the reading is the whole post-checkout journey: an attempt's
+// `journeyCapture` is the authority, and the receipt-document `capture` is
+// kept as the diagnostic that says which document fired. An envelope that
+// carries only a receipt capture (no journey reading) is judged on it, so a
+// receipt-only funnel and older callers read exactly as before.
+export function assessReceiptPurchase(receiptAnalytics = {}, options = {}) {
+  const plannedPlanIds = Array.isArray(receiptAnalytics?.plannedPlanIds)
+    ? receiptAnalytics.plannedPlanIds.map(normalizePlanId).filter(Boolean)
+    : [];
+  const attempts = Array.isArray(receiptAnalytics?.attempts) ? receiptAnalytics.attempts : [];
+  const attemptedPlanIds = attempts.map((attempt) => normalizePlanId(attempt?.planId)).filter(Boolean);
+  const receipts = [];
+  const unqualifiedPlanIds = [];
+  const captureErrorPlanIds = [];
+  const noSignalPlanIds = [];
+
+  for (const planId of plannedPlanIds) {
+    const attempt = attempts.find((candidate) => normalizePlanId(candidate?.planId) === planId);
+    if (!attempt) {
+      unqualifiedPlanIds.push(planId);
+      continue;
+    }
+    if (attempt.receiptRecognized !== true) {
+      unqualifiedPlanIds.push(planId);
+      continue;
+    }
+
+    const receiptCaptureAvailable = isCapture(attempt.capture);
+    const journeyCaptureAvailable = isCapture(attempt.journeyCapture);
+    // Journey when the envelope carries one; the receipt document otherwise.
+    // A journey reading that failed to collect is not replaced by the receipt
+    // document: a silent receipt on an upsell funnel is exactly the case a
+    // receipt-only fallback would misread as "no Purchase". And a receipt
+    // capture/settle error stays the explicit blocker it always was — the
+    // journey reading taken beside an unsettled receipt is not a settled one.
+    const scope = journeyCaptureAvailable
+      ? "journey"
+      : (attempt.journeyCaptureError ? null : (receiptCaptureAvailable ? "receipt" : null));
+    const judged = scope === "journey" ? attempt.journeyCapture : scope === "receipt" ? attempt.capture : null;
+    const captureError = !judged || !!attempt.captureError;
+    if (captureError) captureErrorPlanIds.push(planId);
+    const effective = judged ? effectivePurchase(judged) : { fired: false, via: null };
+    if (!captureError && !effective.fired) noSignalPlanIds.push(planId);
+    // #198 is what happens when an unfalsifiable analytics reading is presented
+    // as a measurement. A failed capture and a receipt that genuinely fired
+    // nothing are BOTH blockers, but they are not the same fact, and a reader
+    // of a single receipt entry must be able to tell them apart without
+    // cross-referencing capture_error_plan_ids. Unmeasured entries carry
+    // measured:false and null signals rather than an all-false reading that
+    // looks like evidence.
+    const measured = !captureError;
+    // Which document fired is the diagnostic a reader of an upsell funnel
+    // needs: on a journey-scoped judgement the receipt-document reading is
+    // kept beside the judged one, and `fired_on` names the receipt when it
+    // fired there, `earlier-page` when only the journey did. A receipt-scoped
+    // judgement has no earlier page and no second reading to keep, so
+    // `receipt_signals` is null there. `scope` is null on an unmeasured entry.
+    const receiptFired = receiptCaptureAvailable && !attempt.captureError
+      ? effectivePurchase(attempt.capture).fired
+      : null;
+    receipts.push({
+      plan_id: planId,
+      receipt_url: redactUrlQuery(attempt.receiptUrl),
+      measured,
+      scope: measured ? scope : null,
+      purchase_fired: measured && !!effective.fired,
+      via: measured ? (effective.via || null) : null,
+      signals: measured ? purchaseSignalsOf(judged) : null,
+      receipt_signals: measured && scope === "journey" && receiptFired !== null ? purchaseSignalsOf(attempt.capture) : null,
+      fired_on: !measured || !effective.fired ? null : receiptFired ? "receipt" : "earlier-page",
+    });
+  }
+
+  const hasBlockingCaptureError = captureErrorPlanIds.length > 0;
+  const hasNoSignalReceipt = noSignalPlanIds.length > 0;
+  const failed = hasBlockingCaptureError || hasNoSignalReceipt;
+  const needsReview = !plannedPlanIds.length || unqualifiedPlanIds.length > 0;
+  const waiver = purchaseFiresWaiver(options, hasNoSignalReceipt && !hasBlockingCaptureError);
+  const status = failed ? STATUS.FAIL : needsReview ? STATUS.MANUAL_REVIEW : STATUS.PASS;
+  const severity = status === STATUS.FAIL
+    ? (waiver ? SEVERITY.WARN : SEVERITY.BLOCKER)
+    : status === STATUS.MANUAL_REVIEW ? SEVERITY.WARN : undefined;
+  const evidence = {
+    attempted_plan_ids: attemptedPlanIds,
+    receipts,
+    unqualified_plan_ids: unique(unqualifiedPlanIds),
+    capture_error_plan_ids: unique(captureErrorPlanIds),
+  };
+
+  return correctnessAssertion({
+    id: "analytics-correctness:purchase-fires",
+    status,
+    severity,
+    ...(waiver ? { waiver } : {}),
+    expected: "every deterministic receipt-qualified typed-card order emits Purchase via dataLayer, Meta, or GA4 on some page of its post-checkout journey.",
+    actual: receiptPurchaseActual({
+      plannedCount: plannedPlanIds.length,
+      receiptCount: receipts.length,
+      firedCount: receipts.filter((receipt) => receipt.purchase_fired).length,
+      unqualifiedCount: unique(unqualifiedPlanIds).length,
+      captureErrorCount: unique(captureErrorPlanIds).length,
+      waiver,
+    }),
+    evidence,
+  });
+}
+
+function normalizePlanId(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function unique(values) {
+  return [...new Set(values)];
+}
+
+function isCapture(value) {
+  return !!value && typeof value === "object";
+}
+
+function purchaseSignalsOf(capture) {
+  const signals = capture?.purchaseSignals || {};
+  return {
+    dataLayer: !!(capture?.purchase?.present || signals.dataLayer),
+    meta: !!signals.meta,
+    ga4: !!signals.ga4,
+  };
+}
+
+function receiptPurchaseActual({ plannedCount, receiptCount, firedCount, unqualifiedCount, captureErrorCount, waiver }) {
+  if (!plannedCount) return "no canonical typed-card browser order was planned; Purchase requires receipt-qualified order evidence";
+  if (captureErrorCount) return `${captureErrorCount} planned order capture(s) failed; Purchase could not be verified`;
+  if (firedCount < receiptCount) {
+    const suffix = waiver
+      ? ` — blocker waived by ${waiver.waived_by}${waiver.waived_at ? ` at ${waiver.waived_at}` : ""}: ${waiver.reason}`
+      : "";
+    return `${receiptCount - firedCount} receipt-qualified order(s) emitted no Purchase via dataLayer, Meta, or GA4 on any page of the journey${suffix}`;
+  }
+  if (unqualifiedCount) return `${unqualifiedCount} of ${plannedCount} planned order(s) did not reach a recognized receipt`;
+  return `${firedCount} of ${plannedCount} receipt-qualified order(s) emitted Purchase`;
+}

package/src/qa-analytics-errors.mjs

@@ -0,0 +1,38 @@
+const ANALYTICS_CAPTURE_ERROR_DEFINITIONS = Object.freeze({
+  attach: Object.freeze({
+    code: "analytics_capture_attach_failed",
+    message: "analytics capture could not be attached",
+  }),
+  unreadable: Object.freeze({
+    code: "analytics_capture_unreadable",
+    message: "analytics capture could not be read from the settled page",
+  }),
+  settle: Object.freeze({
+    code: "analytics_settle_failed",
+    message: "analytics settle window could not complete",
+  }),
+  settleDeadline: Object.freeze({
+    code: "analytics_settle_deadline_exhausted",
+    message: "analytics settle window exceeded the typed-order deadline",
+  }),
+  collectionDeadline: Object.freeze({
+    code: "analytics_capture_collection_deadline_exhausted",
+    message: "analytics capture collection exceeded the typed-order deadline",
+  }),
+});
+
+export function analyticsCaptureError(kind) {
+  const definition = ANALYTICS_CAPTURE_ERROR_DEFINITIONS[kind]
+    || ANALYTICS_CAPTURE_ERROR_DEFINITIONS.unreadable;
+  return { ...definition };
+}
+
+// Only project errors from the fixed private vocabulary. Browser/Playwright
+// detail can contain live URLs, query strings, and page-controlled text, so it
+// must never cross into a verdict or parity bundle.
+export function projectAnalyticsCaptureError(value, { fallbackKind = null } = {}) {
+  const definition = Object.values(ANALYTICS_CAPTURE_ERROR_DEFINITIONS)
+    .find((candidate) => candidate.code === value?.code);
+  if (definition) return { ...definition };
+  return fallbackKind ? analyticsCaptureError(fallbackKind) : null;
+}