@nextcommerce/campaigns-os 1.54.0 → 1.57.0

package/campaign-spec/dist/checkout-flow.js

@@ -0,0 +1,229 @@
+/**
+ * checkout-flow — which page takes payment, and the pages that lead to it.
+ *
+ * From CampaignSpec v5 a page's `type` says which page takes payment
+ * (campaigns-os#641). Three types carry the shopper into a payment:
+ *
+ *   | Type            | Checkout form | Places order | Forward field |
+ *   |-----------------|---------------|--------------|---------------|
+ *   | `select`        | no            | no           | `next_page`   |
+ *   | `checkout_step` | yes           | no           | `next_page`   |
+ *   | `checkout`      | yes           | yes          | `success_url` |
+ *
+ * All three render as SDK page type `checkout`. A campaign may hold several
+ * Checkouts (one per split-test path); each path reaches exactly one.
+ *
+ * Every consumer that asks "which page on this path takes payment" asks here,
+ * never "the first page typed checkout". The one place the payment page is
+ * worked out from links rather than read from `type` is `upgradeCampaignSpec`,
+ * which retypes a v4 spec on read.
+ */
+import { forwardRouteTarget, outgoingEdgeIds } from "./routing.js";
+/** The CampaignSpec lineage this module writes when it upgrades a v4 spec. */
+export const CURRENT_SCHEMA_VERSION = '5.0';
+/** The page that takes payment. */
+export const PAYMENT_PAGE_TYPE = 'checkout';
+/** A checkout form that collects details and moves on without placing an order. */
+export const CHECKOUT_STEP_PAGE_TYPE = 'checkout_step';
+/** Pages that lead into a Checkout without taking payment themselves. */
+export const PRE_PAYMENT_PAGE_TYPES = Object.freeze(['select', 'checkout_step']);
+/**
+ * Every page type the SDK renders as `checkout`: the pre-payment pages and the
+ * Checkout itself. Payment-page features (exit intent, promo code input,
+ * checkout theme gates) apply to all of them.
+ */
+export const CHECKOUT_FLOW_PAGE_TYPES = Object.freeze(['select', 'checkout_step', 'checkout']);
+/** Where a Checkout may send the shopper once payment succeeds. */
+export const POST_PAYMENT_PAGE_TYPES = Object.freeze(['upsell', 'downsell', 'thankyou']);
+/** Post-purchase offer pages: reaching one means an order was already placed. */
+export const POST_PURCHASE_OFFER_PAGE_TYPES = Object.freeze(['upsell', 'downsell']);
+function typeOf(page) {
+    const type = page?.type;
+    return typeof type === 'string' ? type.trim().toLowerCase() : '';
+}
+export function isPaymentPage(page) {
+    return typeOf(page) === PAYMENT_PAGE_TYPE;
+}
+export function isCheckoutStepPage(page) {
+    return typeOf(page) === CHECKOUT_STEP_PAGE_TYPE;
+}
+export function isPrePaymentPage(page) {
+    return PRE_PAYMENT_PAGE_TYPES.includes(typeOf(page));
+}
+export function isCheckoutFlowPage(page) {
+    return CHECKOUT_FLOW_PAGE_TYPES.includes(typeOf(page));
+}
+/**
+ * Strip surrounding slashes and a `.html` suffix so a route target, a page ID
+ * and a `page_url` compare on equal terms. The corpus writes targets in all
+ * three dialects (`shipping`, `shipping.html`, `/shipping/`). Case is kept, as
+ * in RouteTargetResolves: intake's lookup is case-sensitive.
+ */
+function routeish(value) {
+    const trimmed = value.trim().replace(/^\/+|\/+$/g, '');
+    return trimmed.toLowerCase().endsWith('.html') ? trimmed.slice(0, -'.html'.length) : trimmed;
+}
+/**
+ * The page a route target names within `pages`, or null when it names none
+ * (an absolute URL, a fragment, a route outside this funnel, or a typo that
+ * RouteTargetResolves reports). Page IDs win over `page_url` matches.
+ */
+export function resolveRouteTargetPage(pages, target) {
+    if (typeof target !== 'string' || !target.trim())
+        return null;
+    const raw = target.trim();
+    if (raw.startsWith('#') || /^[a-z][a-z0-9+.-]*:/i.test(raw))
+        return null;
+    const key = routeish(raw);
+    if (!key)
+        return null;
+    for (const page of pages) {
+        if (page?.id === raw || (typeof page?.id === 'string' && routeish(page.id) === key))
+            return page;
+    }
+    for (const page of pages) {
+        const route = page?.page_url;
+        if (typeof route === 'string' && route.trim() && routeish(route) === key)
+            return page;
+    }
+    return null;
+}
+/** The page this page's forward link resolves to, within `pages`. */
+export function forwardTargetPage(pages, page) {
+    return resolveRouteTargetPage(pages, forwardRouteTarget(page));
+}
+function enabledPages(funnel) {
+    return (funnel?.pages ?? []).filter((page) => page && page.enabled !== false);
+}
+/**
+ * The pages from `start` forward to the Checkout that takes payment, both
+ * included, following each page's forward link. Null when the walk leaves the
+ * funnel, loops, ends, or meets a post-payment page before any Checkout.
+ *
+ * `start` may itself be the Checkout (the path is then that page alone).
+ */
+export function checkoutPathFrom(pages, start) {
+    const path = [];
+    const seen = new Set();
+    let page = start;
+    while (page && !seen.has(page)) {
+        seen.add(page);
+        path.push(page);
+        if (isPaymentPage(page))
+            return path;
+        if (POST_PAYMENT_PAGE_TYPES.includes(typeOf(page)))
+            return null;
+        page = forwardTargetPage(pages, page);
+    }
+    return null;
+}
+/** The Checkout reached by walking forward from `start`, or null. */
+export function paymentPageFrom(pages, start) {
+    const path = checkoutPathFrom(pages, start);
+    return path ? path[path.length - 1] : null;
+}
+/**
+ * The funnel's entry pages: those flagged `is_entry`, or when none is flagged,
+ * those no other page routes to apart from orphaned upsell, downsell and
+ * thank-you pages (falling back to the lowest `order` when that leaves none). Order and names are never consulted beyond that
+ * last-resort tie-break.
+ */
+export function entryPages(funnel) {
+    const pages = enabledPages(funnel);
+    const flagged = pages.filter((page) => page.is_entry === true);
+    if (flagged.length)
+        return flagged;
+    const targeted = new Set();
+    for (const page of pages) {
+        for (const target of outgoingEdgeIds(page)) {
+            const hit = resolveRouteTargetPage(pages, target);
+            if (hit && hit !== page)
+                targeted.add(hit);
+        }
+    }
+    // A post-payment page nothing routes to is an orphan, not where a shopper
+    // starts: no unflagged journey begins on an upsell or a receipt.
+    const roots = pages.filter((page) => !targeted.has(page) && !POST_PAYMENT_PAGE_TYPES.includes(typeOf(page)));
+    if (roots.length)
+        return roots;
+    const first = [...pages].sort((a, b) => (a.order ?? 0) - (b.order ?? 0))[0];
+    return first ? [first] : [];
+}
+/**
+ * The Checkout on the path through `page`'s funnel that starts at an entry
+ * page, for callers that hold a funnel rather than a starting page. When the
+ * funnel has several entry paths with different Checkouts, returns the first
+ * entry's; use `paymentPagesForFunnel` to see all of them.
+ */
+export function paymentPageForFunnel(funnel) {
+    return paymentPagesForFunnel(funnel)[0] ?? null;
+}
+/** Every distinct Checkout reached from the funnel's entry pages, in entry order. */
+export function paymentPagesForFunnel(funnel) {
+    const pages = enabledPages(funnel);
+    const out = [];
+    for (const entry of entryPages(funnel)) {
+        const checkout = paymentPageFrom(pages, entry);
+        if (checkout && !out.includes(checkout))
+            out.push(checkout);
+    }
+    // A funnel whose entry is a landing page that links into checkout through a
+    // CTA (no forward field) still has a Checkout; fall back to every Checkout
+    // the funnel declares, in declaration order (funnel.pages), so a lookup never
+    // reports "none" for a real one. No entry path reaches these, so there is no
+    // path order to follow; QA's topology walker falls back the same way.
+    if (!out.length)
+        for (const page of pages)
+            if (isPaymentPage(page))
+                out.push(page);
+    return out;
+}
+/**
+ * Upgrade a CampaignSpec to the v5 page vocabulary. Returns a new object; the
+ * input is never mutated, so callers that hash or persist the raw bytes keep
+ * the bytes they read.
+ *
+ * v5 specs pass through unchanged. For any other lineage, each `checkout` page
+ * whose resolved forward target is also a `checkout` is retyped
+ * `checkout_step` — the v4 `checkout → checkout` chain was the only way to say
+ * "this form moves on without taking payment". A supported v4 `schema_version`
+ * becomes `5.0`; a missing or unsupported one is left for SchemaVersion to
+ * report.
+ */
+export function upgradeCampaignSpec(input) {
+    if (input == null || typeof input !== 'object' || Array.isArray(input))
+        return input;
+    const spec = input;
+    const version = typeof spec.schema_version === 'string' ? spec.schema_version.trim() : '';
+    if (version.startsWith('5.') || version === '5')
+        return input;
+    if (!Array.isArray(spec.funnels))
+        return input;
+    let changed = false;
+    const funnels = spec.funnels.map((funnel) => {
+        if (!funnel || !Array.isArray(funnel.pages))
+            return funnel;
+        const pages = funnel.pages;
+        const retype = new Set();
+        for (const page of pages) {
+            if (!isPaymentPage(page))
+                continue;
+            if (isPaymentPage(forwardTargetPage(pages, page)))
+                retype.add(page);
+        }
+        if (!retype.size)
+            return funnel;
+        changed = true;
+        return {
+            ...funnel,
+            pages: pages.map((page) => (retype.has(page) ? { ...page, type: CHECKOUT_STEP_PAGE_TYPE } : page)),
+        };
+    });
+    const upgradeVersion = version === '4.2' || version === '4.3';
+    if (!changed && !upgradeVersion)
+        return input;
+    const out = { ...spec, funnels };
+    if (upgradeVersion)
+        out.schema_version = CURRENT_SCHEMA_VERSION;
+    return out;
+}

package/campaign-spec/dist/index.d.ts

@@ -15,6 +15,7 @@ export type { CampaignSpec, Rule, RuleSet, Violation, Tag, Severity, Fixture, Pa
 export { normalize, NormalizeError } from './normalize.ts';
 export { FORWARD_ROUTE_FIELDS, ACCEPT_ROUTE_FIELD, DECLINE_ROUTE_FIELD, ROUTE_FIELDS, PAYMENT_BEARING_PAGE_TYPES, OFFER_BEARING_PAGE_TYPES, forwardRouteTarget, acceptRouteTarget, declineRouteTarget, hasForwardRoute, applicableForwardFields, inapplicableForwardFields, describeForwardField, outgoingEdgeIds, } from './routing.ts';
 export type { ForwardFieldApplicability } from './routing.ts';
+export { CURRENT_SCHEMA_VERSION, PAYMENT_PAGE_TYPE, CHECKOUT_STEP_PAGE_TYPE, PRE_PAYMENT_PAGE_TYPES, CHECKOUT_FLOW_PAGE_TYPES, POST_PAYMENT_PAGE_TYPES, POST_PURCHASE_OFFER_PAGE_TYPES, isPaymentPage, isCheckoutStepPage, isPrePaymentPage, isCheckoutFlowPage, resolveRouteTargetPage, forwardTargetPage, checkoutPathFrom, paymentPageFrom, entryPages, paymentPageForFunnel, paymentPagesForFunnel, upgradeCampaignSpec, } from './checkout-flow.ts';
 export { allRules, fastRules, specOnlyRules } from './rules/index.ts';
 export { SUPPORTED_SCHEMA_VERSIONS } from './rules/schema-version.ts';
 export { RELEASED_SDK_VERSION_PATTERN, parseSdkVersion, isReleasedSdkVersion, describeSdkVersionRejection, } from './sdk-version-parse.ts';

package/campaign-spec/dist/index.js

@@ -17,10 +17,15 @@ export { normalize, NormalizeError } from "./normalize.js";
 // page go". Source intake, cycle detection and the QA topology extractor all
 // consume these rather than keeping their own page-type tables.
 export { FORWARD_ROUTE_FIELDS, ACCEPT_ROUTE_FIELD, DECLINE_ROUTE_FIELD, ROUTE_FIELDS, PAYMENT_BEARING_PAGE_TYPES, OFFER_BEARING_PAGE_TYPES, forwardRouteTarget, acceptRouteTarget, declineRouteTarget, hasForwardRoute, applicableForwardFields, inapplicableForwardFields, describeForwardField, outgoingEdgeIds, } from "./routing.js";
+// Which page takes payment, and the pages leading to it (campaigns-os#641).
+// Every "the Checkout on this path" lookup asks here; upgradeCampaignSpec is
+// the v4 → v5 read-time upgrade normalize() applies.
+export { CURRENT_SCHEMA_VERSION, PAYMENT_PAGE_TYPE, CHECKOUT_STEP_PAGE_TYPE, PRE_PAYMENT_PAGE_TYPES, CHECKOUT_FLOW_PAGE_TYPES, POST_PAYMENT_PAGE_TYPES, POST_PURCHASE_OFFER_PAGE_TYPES, isPaymentPage, isCheckoutStepPage, isPrePaymentPage, isCheckoutFlowPage, resolveRouteTargetPage, forwardTargetPage, checkoutPathFrom, paymentPageFrom, entryPages, paymentPageForFunnel, paymentPagesForFunnel, upgradeCampaignSpec, } from "./checkout-flow.js";
 export { allRules, fastRules, specOnlyRules } from "./rules/index.js";
 // Supported schema_version matrix — single source for the SchemaVersion rule
 // and any consumer that needs to present or gate on the supported lineages.
-// A sync test pins it to the schemas/campaign-spec.v4.schema.json enum.
+// A sync test pins it to the schema_version enums of
+// schemas/campaign-spec.v4.schema.json and schemas/campaign-spec.v5.schema.json.
 export { SUPPORTED_SCHEMA_VERSIONS } from "./rules/schema-version.js";
 // Strict released-SDK-version parser — shared with the downstream Page Kit
 // SDK-version checkpoint (src/page-kit-sdk-version.mjs) so authoring-time

package/campaign-spec/dist/normalize.d.ts

@@ -2,8 +2,9 @@
  * normalize — the single phase that takes an authoring CampaignSpec and emits
  * the canonical v4.2 funnels[] shape that rules operate on.
  *
- * Today this is near-empty: v4.3 already uses funnels[]. The phase exists so
- * future authoring evolutions have one place to land their migration.
+ * v4.2/v4.3 specs are upgraded to the v5 page vocabulary here (a `checkout`
+ * that forwards to another `checkout` becomes `checkout_step`), so every rule
+ * sees one vocabulary. Future authoring evolutions land here too.
  *
  * v4.1 (funnel_pages[]) is intentionally NOT supported — see
  * ../docs/adr/002-drop-v41-spec-support.md. Inputs without `funnels[]` fail

package/campaign-spec/dist/normalize.js

@@ -2,13 +2,15 @@
  * normalize — the single phase that takes an authoring CampaignSpec and emits
  * the canonical v4.2 funnels[] shape that rules operate on.
  *
- * Today this is near-empty: v4.3 already uses funnels[]. The phase exists so
- * future authoring evolutions have one place to land their migration.
+ * v4.2/v4.3 specs are upgraded to the v5 page vocabulary here (a `checkout`
+ * that forwards to another `checkout` becomes `checkout_step`), so every rule
+ * sees one vocabulary. Future authoring evolutions land here too.
  *
  * v4.1 (funnel_pages[]) is intentionally NOT supported — see
  * ../docs/adr/002-drop-v41-spec-support.md. Inputs without `funnels[]` fail
  * the structural assertion below.
  */
+import { upgradeCampaignSpec } from "./checkout-flow.js";
 /**
  * Thrown when input is structurally unrecognizable as a CampaignSpec.
  * Distinct from rule violations: a violation means "this spec is wrong";
@@ -35,7 +37,7 @@ export function normalize(input) {
     if (!Array.isArray(obj.funnels)) {
         throw new NormalizeError('CampaignSpec is missing funnels[]. Expected canonical v4.2+ topology.');
     }
-    // Future migrations (v5 → v4, etc.) land here. Today the shape is already
-    // canonical, so pass through.
-    return obj;
+    // v4 → v5: retype each `checkout` that forwards to another `checkout` as
+    // `checkout_step` (campaigns-os#641). Returns a copy; the input is untouched.
+    return upgradeCampaignSpec(obj);
 }

package/campaign-spec/dist/routing.d.ts

@@ -73,9 +73,12 @@ export declare const DECLINE_ROUTE_FIELD: "on_decline";
  * is about one field's MEANING: reading a payment-shaped field on a page with
  * no payment is not respecting the author's intent, it is inventing one.
  *
- * Membership is deliberately narrow. The three-step shop family types its
- * `information` / `shipping` / `billing` pages as `checkout`, so they are
- * already covered; no certified family carries a second payment-bearing type.
+ * Membership is deliberately narrow. From CampaignSpec v5 (campaigns-os#641)
+ * `checkout` means exactly the page that takes payment; the earlier steps of a
+ * split checkout (the three-step shop family's `information` and `shipping`)
+ * are `checkout_step`, which take no payment and advance through `next_page`.
+ * A v4 spec that chained `checkout → checkout` is retyped on read
+ * (checkout-flow.ts), so the billing page alone stays payment-bearing here.
  * An `upsell` takes a one-click payment but expresses its post-purchase branch
  * through `on_accept`, which has its own applicability rule below.
  * Ratified on campaigns-os#234, 2026-08-25.

package/campaign-spec/dist/routing.js

@@ -76,9 +76,12 @@ export const DECLINE_ROUTE_FIELD = 'on_decline';
  * is about one field's MEANING: reading a payment-shaped field on a page with
  * no payment is not respecting the author's intent, it is inventing one.
  *
- * Membership is deliberately narrow. The three-step shop family types its
- * `information` / `shipping` / `billing` pages as `checkout`, so they are
- * already covered; no certified family carries a second payment-bearing type.
+ * Membership is deliberately narrow. From CampaignSpec v5 (campaigns-os#641)
+ * `checkout` means exactly the page that takes payment; the earlier steps of a
+ * split checkout (the three-step shop family's `information` and `shipping`)
+ * are `checkout_step`, which take no payment and advance through `next_page`.
+ * A v4 spec that chained `checkout → checkout` is retyped on read
+ * (checkout-flow.ts), so the billing page alone stays payment-bearing here.
  * An `upsell` takes a one-click payment but expresses its post-purchase branch
  * through `on_accept`, which has its own applicability rule below.
  * Ratified on campaigns-os#234, 2026-08-25.

package/campaign-spec/dist/rules/checkout-forward-target.d.ts

@@ -0,0 +1,17 @@
+/**
+ * CheckoutForwardTarget — a Checkout takes payment, so where it sends the
+ * shopper next must be a post-payment page: an upsell, a downsell or a
+ * thank-you page (campaigns-os#641).
+ *
+ * A `checkout` forwarding to another checkout-shaped page, a landing page or a
+ * select page means one of two things, both wrong: the page is really a step
+ * that collects details and moves on (type it `checkout_step`), or the order
+ * would be placed before the shopper reaches the page meant to take payment.
+ *
+ * Only a target this funnel resolves is judged. An off-graph destination (a
+ * rooted path into an existing downstream campaign, an absolute URL) is the
+ * partial-scope shape and passes; an unresolved typo is RouteTargetResolves';
+ * a Checkout with no forward route at all is CheckoutHasSuccessUrl's.
+ */
+import type { Rule } from '../types.ts';
+export declare const CheckoutForwardTarget: Rule;

package/campaign-spec/dist/rules/checkout-forward-target.js

@@ -0,0 +1,48 @@
+/**
+ * CheckoutForwardTarget — a Checkout takes payment, so where it sends the
+ * shopper next must be a post-payment page: an upsell, a downsell or a
+ * thank-you page (campaigns-os#641).
+ *
+ * A `checkout` forwarding to another checkout-shaped page, a landing page or a
+ * select page means one of two things, both wrong: the page is really a step
+ * that collects details and moves on (type it `checkout_step`), or the order
+ * would be placed before the shopper reaches the page meant to take payment.
+ *
+ * Only a target this funnel resolves is judged. An off-graph destination (a
+ * rooted path into an existing downstream campaign, an absolute URL) is the
+ * partial-scope shape and passes; an unresolved typo is RouteTargetResolves';
+ * a Checkout with no forward route at all is CheckoutHasSuccessUrl's.
+ */
+import { forwardRouteTarget } from "../routing.js";
+import { POST_PAYMENT_PAGE_TYPES, forwardTargetPage, isPaymentPage } from "../checkout-flow.js";
+export const CheckoutForwardTarget = {
+    id: 'CheckoutForwardTarget',
+    severity: 'error',
+    tags: ['fast', 'structure', 'spec-only'],
+    check(spec) {
+        const violations = [];
+        spec.funnels.forEach((funnel, funnelIdx) => {
+            const pages = funnel.pages ?? [];
+            pages.forEach((page, pageIdx) => {
+                if (!isPaymentPage(page))
+                    return;
+                const target = forwardTargetPage(pages, page);
+                if (!target)
+                    return;
+                const targetType = typeof target.type === 'string' ? target.type : '';
+                if (POST_PAYMENT_PAGE_TYPES.includes(targetType))
+                    return;
+                violations.push({
+                    ruleId: 'CheckoutForwardTarget',
+                    severity: 'error',
+                    message: `Checkout "${page.id}" forwards to "${target.id}" (type "${targetType || 'none'}"). ` +
+                        'A Checkout takes payment, so it must forward to an upsell, downsell or thank-you page. ' +
+                        'If this page collects details and moves on without placing an order, type it "checkout_step".',
+                    path: `/funnels/${funnelIdx}/pages/${pageIdx}`,
+                    data: { pageId: page.id, target: forwardRouteTarget(page), targetPageId: target.id, targetType },
+                });
+            });
+        });
+        return violations;
+    },
+};

package/campaign-spec/dist/rules/checkout-step-reaches-checkout.d.ts

@@ -0,0 +1,12 @@
+/**
+ * CheckoutStepReachesCheckout — every `checkout_step` page must lie on a path
+ * to a Checkout. Following its forward links has to arrive at a `checkout`
+ * page; a step that dead-ends, loops, leaves the funnel or reaches an offer
+ * first collects the shopper's details and never takes payment
+ * (campaigns-os#641).
+ *
+ * Forward links only: a step has no decline branch that could carry the
+ * shopper to payment instead.
+ */
+import type { Rule } from '../types.ts';
+export declare const CheckoutStepReachesCheckout: Rule;

package/campaign-spec/dist/rules/checkout-step-reaches-checkout.js

@@ -0,0 +1,37 @@
+/**
+ * CheckoutStepReachesCheckout — every `checkout_step` page must lie on a path
+ * to a Checkout. Following its forward links has to arrive at a `checkout`
+ * page; a step that dead-ends, loops, leaves the funnel or reaches an offer
+ * first collects the shopper's details and never takes payment
+ * (campaigns-os#641).
+ *
+ * Forward links only: a step has no decline branch that could carry the
+ * shopper to payment instead.
+ */
+import { isCheckoutStepPage, paymentPageFrom } from "../checkout-flow.js";
+export const CheckoutStepReachesCheckout = {
+    id: 'CheckoutStepReachesCheckout',
+    severity: 'error',
+    tags: ['structure', 'spec-only'],
+    check(spec) {
+        const violations = [];
+        spec.funnels.forEach((funnel, funnelIdx) => {
+            const pages = funnel.pages ?? [];
+            pages.forEach((page, pageIdx) => {
+                if (!isCheckoutStepPage(page))
+                    return;
+                if (paymentPageFrom(pages, page))
+                    return;
+                violations.push({
+                    ruleId: 'CheckoutStepReachesCheckout',
+                    severity: 'error',
+                    message: `Checkout step "${page.id}" is not on a path to a Checkout. ` +
+                        'Follow its next_page links to the page that takes payment (type "checkout").',
+                    path: `/funnels/${funnelIdx}/pages/${pageIdx}`,
+                    data: { pageId: page.id },
+                });
+            });
+        });
+        return violations;
+    },
+};

package/campaign-spec/dist/rules/exit-intent-validation.js

@@ -19,6 +19,7 @@
  *
  * Message text inherited verbatim from the pre-#110 validator at migration time.
  */
+import { isCheckoutFlowPage } from "../checkout-flow.js";
 function isTruthyString(value) {
     return typeof value === 'string' && value.trim().length > 0;
 }
@@ -55,7 +56,7 @@ export const ExitIntentValidation = {
                 const refOffer = ref ? index.byRefId.get(String(ref)) : null;
                 const codeOffer = code ? index.byCode.get(String(code).toUpperCase()) : null;
                 // 1. Placement
-                if (page.type !== 'checkout') {
+                if (!isCheckoutFlowPage(page)) {
                     violations.push({
                         ruleId: 'ExitIntentValidation',
                         severity: 'warning',

package/campaign-spec/dist/rules/index.d.ts

@@ -31,6 +31,10 @@ export { UpsellHasPackages } from './upsell-has-packages.ts';
 export { UpsellRoutingComplete } from './upsell-routing-complete.ts';
 export { RouteFieldIgnoredForPageType } from './route-field-ignored-for-page-type.ts';
 export { CheckoutHasSuccessUrl } from './checkout-has-success-url.ts';
+export { CheckoutForwardTarget } from './checkout-forward-target.ts';
+export { PrePaymentForwardTarget } from './pre-payment-forward-target.ts';
+export { CheckoutStepReachesCheckout } from './checkout-step-reaches-checkout.ts';
+export { OneCheckoutPerPath } from './one-checkout-per-path.ts';
 export { UpsellWithoutCheckout } from './upsell-without-checkout.ts';
 export { DownsellWithoutUpsell } from './downsell-without-upsell.ts';
 export { PackagePricingSanity } from './package-pricing-sanity.ts';

package/campaign-spec/dist/rules/index.js

@@ -30,6 +30,10 @@ import { UpsellRoutingComplete } from "./upsell-routing-complete.js";
 import { RouteTargetResolves } from "./route-target-resolves.js";
 import { RouteFieldIgnoredForPageType } from "./route-field-ignored-for-page-type.js";
 import { CheckoutHasSuccessUrl } from "./checkout-has-success-url.js";
+import { CheckoutForwardTarget } from "./checkout-forward-target.js";
+import { PrePaymentForwardTarget } from "./pre-payment-forward-target.js";
+import { CheckoutStepReachesCheckout } from "./checkout-step-reaches-checkout.js";
+import { OneCheckoutPerPath } from "./one-checkout-per-path.js";
 import { UpsellWithoutCheckout } from "./upsell-without-checkout.js";
 import { DownsellWithoutUpsell } from "./downsell-without-upsell.js";
 import { CampaignMetadata } from "./campaign-metadata.js";
@@ -61,6 +65,10 @@ export { UpsellHasPackages } from "./upsell-has-packages.js";
 export { UpsellRoutingComplete } from "./upsell-routing-complete.js";
 export { RouteFieldIgnoredForPageType } from "./route-field-ignored-for-page-type.js";
 export { CheckoutHasSuccessUrl } from "./checkout-has-success-url.js";
+export { CheckoutForwardTarget } from "./checkout-forward-target.js";
+export { PrePaymentForwardTarget } from "./pre-payment-forward-target.js";
+export { CheckoutStepReachesCheckout } from "./checkout-step-reaches-checkout.js";
+export { OneCheckoutPerPath } from "./one-checkout-per-path.js";
 export { UpsellWithoutCheckout } from "./upsell-without-checkout.js";
 export { DownsellWithoutUpsell } from "./downsell-without-upsell.js";
 export { PackagePricingSanity } from "./package-pricing-sanity.js";
@@ -102,6 +110,10 @@ export const allRules = [
     RouteTargetResolves,
     RouteFieldIgnoredForPageType,
     CheckoutHasSuccessUrl,
+    CheckoutForwardTarget,
+    PrePaymentForwardTarget,
+    CheckoutStepReachesCheckout,
+    OneCheckoutPerPath,
     UpsellWithoutCheckout,
     DownsellWithoutUpsell,
     PackagePricingSanity,

package/campaign-spec/dist/rules/one-checkout-per-path.d.ts

@@ -0,0 +1,25 @@
+/**
+ * OneCheckoutPerPath — every path from an entry page to an upsell or downsell
+ * passes exactly one Checkout (campaigns-os#641).
+ *
+ * None means the shopper reaches a post-purchase offer with no order placed;
+ * two means the path takes payment twice. A campaign may hold several
+ * Checkouts — split-test paths each reach their own — so the rule counts per
+ * path, never per spec.
+ *
+ * Paths follow both edges a page can traverse (forward and decline, from
+ * routing.ts) and start at the funnel's entry pages (checkout-flow.ts
+ * `entryPages`): pages flagged `is_entry`, else those nothing routes to. No
+ * page order or name is consulted. The search runs, per entry page, over
+ * (page, checkouts passed so far: 0, 1, 2+) states, so each bad page is
+ * reported once per entry and count however many of that entry's paths reach it.
+ *
+ * A spec with no Checkout anywhere is left to UpsellWithoutCheckout, so the
+ * two never report one defect twice.
+ *
+ * With build_scope.mode === 'partial' a path that reaches an offer with no
+ * Checkout is a warning, as in UpsellWithoutCheckout: a partial upsell build
+ * may ship an offer an existing checkout elsewhere routes into.
+ */
+import type { Rule } from '../types.ts';
+export declare const OneCheckoutPerPath: Rule;

package/campaign-spec/dist/rules/one-checkout-per-path.js

@@ -0,0 +1,84 @@
+/**
+ * OneCheckoutPerPath — every path from an entry page to an upsell or downsell
+ * passes exactly one Checkout (campaigns-os#641).
+ *
+ * None means the shopper reaches a post-purchase offer with no order placed;
+ * two means the path takes payment twice. A campaign may hold several
+ * Checkouts — split-test paths each reach their own — so the rule counts per
+ * path, never per spec.
+ *
+ * Paths follow both edges a page can traverse (forward and decline, from
+ * routing.ts) and start at the funnel's entry pages (checkout-flow.ts
+ * `entryPages`): pages flagged `is_entry`, else those nothing routes to. No
+ * page order or name is consulted. The search runs, per entry page, over
+ * (page, checkouts passed so far: 0, 1, 2+) states, so each bad page is
+ * reported once per entry and count however many of that entry's paths reach it.
+ *
+ * A spec with no Checkout anywhere is left to UpsellWithoutCheckout, so the
+ * two never report one defect twice.
+ *
+ * With build_scope.mode === 'partial' a path that reaches an offer with no
+ * Checkout is a warning, as in UpsellWithoutCheckout: a partial upsell build
+ * may ship an offer an existing checkout elsewhere routes into.
+ */
+import { outgoingEdgeIds } from "../routing.js";
+import { POST_PURCHASE_OFFER_PAGE_TYPES, entryPages, isPaymentPage, resolveRouteTargetPage } from "../checkout-flow.js";
+function isOffer(page) {
+    const type = typeof page.type === 'string' ? page.type.trim().toLowerCase() : '';
+    return POST_PURCHASE_OFFER_PAGE_TYPES.includes(type);
+}
+export const OneCheckoutPerPath = {
+    id: 'OneCheckoutPerPath',
+    severity: 'error',
+    tags: ['structure', 'spec-only'],
+    check(spec) {
+        const violations = [];
+        const partial = spec.build_scope?.mode === 'partial';
+        // A spec with no Checkout at all is UpsellWithoutCheckout's to report; this
+        // rule speaks only when Checkouts exist and some path misses or doubles one.
+        const anyCheckout = spec.funnels.some((funnel) => (funnel.pages ?? []).some((page) => isPaymentPage(page)));
+        spec.funnels.forEach((funnel, funnelIdx) => {
+            const pages = (funnel.pages ?? []).filter((page) => page && page.enabled !== false);
+            const indexOf = new Map();
+            (funnel.pages ?? []).forEach((page, idx) => indexOf.set(page, idx));
+            // Searched once per entry page, so every entry whose path misses or
+            // doubles the Checkout is named, not only the first one to reach the page.
+            for (const entry of entryPages(funnel)) {
+                const seen = new Set();
+                const reported = new Set();
+                const stack = [[entry, 0]];
+                while (stack.length) {
+                    const [page, before] = stack.pop();
+                    const passed = Math.min(before + (isPaymentPage(page) ? 1 : 0), 2);
+                    const key = `${indexOf.get(page)}:${passed}`;
+                    if (seen.has(key))
+                        continue;
+                    seen.add(key);
+                    if (isOffer(page) && passed !== 1 && (passed > 1 || anyCheckout)) {
+                        const reportKey = `${indexOf.get(page)}:${passed === 0 ? 0 : 2}`;
+                        if (!reported.has(reportKey)) {
+                            reported.add(reportKey);
+                            const none = passed === 0;
+                            violations.push({
+                                ruleId: 'OneCheckoutPerPath',
+                                severity: none && partial ? 'warning' : 'error',
+                                message: none
+                                    ? `A path from entry page "${entry.id}" reaches "${page.id}" (${page.type}) without passing a Checkout, so no order has been placed.` +
+                                        (partial ? ' Valid for partial upsell builds when an existing checkout routes into this page.' : '')
+                                    : `A path from entry page "${entry.id}" reaches "${page.id}" (${page.type}) after passing more than one Checkout, so it takes payment twice.`,
+                                path: `/funnels/${funnelIdx}/pages/${indexOf.get(page)}`,
+                                data: { pageId: page.id, entryPageId: entry.id, checkoutsPassed: none ? 0 : 2, isPartialScope: partial },
+                            });
+                        }
+                    }
+                    for (const target of outgoingEdgeIds(page)) {
+                        const next = resolveRouteTargetPage(pages, target);
+                        if (next)
+                            stack.push([next, passed]);
+                    }
+                }
+            }
+        });
+        return violations;
+    },
+};

package/campaign-spec/dist/rules/pre-payment-forward-target.d.ts

@@ -0,0 +1,12 @@
+/**
+ * PrePaymentForwardTarget — a `select` or `checkout_step` page takes no
+ * payment, so it must not forward straight to a post-payment page (an upsell,
+ * a downsell or a thank-you page). Doing so skips the Checkout: the shopper
+ * reaches an offer or a receipt with no order placed (campaigns-os#641).
+ *
+ * Only the resolved forward link is judged — routing.ts already ignores a
+ * `success_url` or `on_accept` on these types, and RouteFieldIgnoredForPageType
+ * warns about those separately.
+ */
+import type { Rule } from '../types.ts';
+export declare const PrePaymentForwardTarget: Rule;