@nextcommerce/campaigns-os 1.55.0 → 1.57.0

package/CHANGELOG.md

@@ -2,6 +2,70 @@
 
 Notable supported-surface changes are recorded here.
 
+## [1.57.0] - 2026-10-08
+
+### Changed
+
+- Publishes the untagged `1.56.0` changes: CampaignSpec 5.0, checkout steps, and the updated build and QA contracts.
+- Publishes `1.56.0+agent.1`: `--version` and `-v`, and the Git ignore entry for runtime progress records.
+- Publishes `1.56.0+agent.2`: hosted all-template previews carry missing Polish and page-load evidence forward as warnings.
+- Publishes `1.56.0+agent.3`: doctor and QA find an entry page at Page Kit's emitted route when the declared root is absent.
+- Publishes `1.56.0+agent.5`: doctor warns when a variant and quantity checkout does not fit the selected template family.
+- Publishes `1.56.0+agent.6`: committed handoff artifacts retain repository-relative paths.
+
+## [1.56.0+agent.6] - 2026-10-08
+
+### Fixed
+
+Committed Build Packet and `.campaign-runtime/` handoff artifacts now retain filesystem paths in relative form after `doctor --write`, `next`, and stage updates. Packet input fields resolve from the packet file's directory, output paths from the target repository, source page paths from the source root, package references from their context or report file, and normalized brief input paths from the brief file. Other committed sidecar paths and stored commands resolve from the target repository root. Outside inputs use ordinary relative paths from those bases, including source manifest paths in decision evidence. Machine-local ignored run state keeps its existing path behavior. `doctor --strip-paths` remains available for older packets. QA verdict discovery resolves recorded outputs from the target root.
+
+## [1.56.0+agent.5] - 2026-10-08
+
+### Fixed
+
+Doctor warns once per checkout path when selectable packages form a variant and quantity matrix but the selected certified template family declares one main package and no configurable variant-slot checkout surface. The matrix requires at least two variants, with at least one offered at multiple quantities. Variant identity comes from attributes shared by every selectable row carrying a quantity, or from variant names shared by those rows; rows with missing or blank quantities are ignored when detecting the matrix. SKUs, order bumps, upsells, pack-size rows, and quantity tiers of one variant do not trigger the warning. Paths follow CampaignSpec route targets, including `.html` and `page_url` routes. If any checkout path has a `select` or `checkout_step` page, every warning ranks multi-step families first. Each warning names the matching certified variant-slot families in ranked order, preferring the selected family's base. It says the family is chosen at intake with `--template-family`; after stage evidence is recorded, it explains that changing the family requires destructive intake with `--force`. The warning does not block intake or change the selected family.
+
+## [1.56.0+agent.3] - 2026-10-08
+
+### Fixed
+
+Doctor recognizes an entry page declared at the campaign root when Page Kit emitted its recorded page file at a different route and the root output is absent. Root declarations include `page_url` empty, `/`, `/<slug>/`, and `<slug>`. A template-stock entry counts as built instead of "not built yet"; one warning names the unserved root, the emitted route, and the concrete redirect or `permalink: /<slug>/` repair. The warning uses the public route (`/` or `/<slug>/`), while built-page and previewable routes retain their relative Page Kit format. `qa resolve` prints the locally emitted entry URL under its existing slug-prefixed `base_url`; `base_url` and non-entry page URLs keep their previous resolution, including a `--base-url` subpath. An explicit non-root permalink on the entry source wins over a root output or stale file-route output for QA, and doctor warns if the root output is absent. When files named for both the page ID and page type exist, doctor and QA prefer the page ID file's permalink or built file route, then the page type file's. Without a permalink, a present root output keeps the entry at `base_url` and suppresses the warning. Neither doctor nor QA substitutes an unrelated built page.
+
+## [1.56.0+agent.2] - 2026-10-08
+
+### Changed
+
+When every mapped page is template stock, a non-loopback hosted preview at `deploy.preview_url` carries missing Polish and hidden eager-media page-load evidence forward as warnings if its origin or campaign route path differs from `deploy.production_url` after QA composes the campaign slug onto each URL; a query or fragment alone does not qualify. Doctor and `next` move past Polish, and QA records warning rows with a verdict no better than `ready_with_exceptions`. QA against the production campaign page and hosted campaigns with a capturable design route retain strict evidence gates. If the preview URL is missing or resolves to the production campaign page, `next` names `qa policy set --packet <packet> --preview-url <url>` even when a production URL is set. Once recorded, `next` names browser and typed-card QA with `qa run --packet <packet> --base-url <preview-url> --browser --test-order common`. The hosted preview satisfies the deploy handoff without a deploy record; after a current-build QA verdict, `next` reaches closeout. `record deploy` remains local-only. The Polish prompt and actions do not suggest a capture when no design route exists. Bundled skills advance to `1.56.0+skills.2`.
+
+## [1.56.0+agent.1] - 2026-10-08
+
+### Fixed
+
+- `campaigns-os --version` and `campaigns-os -v` print only the installed package version, with no campaign runtime writes (campaigns-os#644).
+- Campaign runtime progress snapshots and their remit records are ignored by Git. A target with an older managed `.gitignore` block gains `.campaign-runtime/progress/` on its next `start`, `prepare-build`, `install-agent-context` or `run start`. A rule does not untrack files already committed; remove those with `git rm -r --cached .campaign-runtime/progress/` (campaigns-os#645).
+
+## [1.56.0] - 2026-10-08
+
+### Added
+
+CampaignSpec 5.0 (`schemas/campaign-spec.v5.schema.json`, also a package export) makes `checkout` mean the page that takes payment and adds the `checkout_step` page type: a page with a checkout form that collects details and moves on through `next_page` without placing an order. `select` stays the bundle picker before checkout. All three render as SDK page type `checkout`. A 4.2 or 4.3 spec, including a Map saved before this release, still validates against the v4 schema and is upgraded when read: each `checkout` page whose resolved forward target is another `checkout` becomes `checkout_step`. The input is never rewritten, so spec hashes still cover the bytes as written. A campaign may hold several Checkouts, one per split-test path (campaigns-os#641).
+
+Four new spec rules run in doctor through `spec.validation`. Each has a fixture under `campaign-spec/fixtures/`, and none of them reads page order or page names:
+
+- `CheckoutForwardTarget` (error): a Checkout's resolved forward target is not an upsell, downsell or thank-you page.
+- `PrePaymentForwardTarget` (error): a `select` or `checkout_step` page forwards straight to an upsell, downsell or thank-you page.
+- `OneCheckoutPerPath` (error): a path from an entry page reaches an upsell or downsell without passing exactly one Checkout. In partial build scope, the case with no Checkout is a warning.
+- `CheckoutStepReachesCheckout` (error): a `checkout_step` page is not on a path to a Checkout.
+
+`RouteFieldIgnoredForPageType` now also warns about a `success_url` or `on_accept` on a `checkout_step`.
+
+### Changed
+
+- Build: `prepare-build` projects `checkout_step` pages to Page Kit `page_type: checkout`, with the default route `checkout-step/`. Page Kit frontmatter in the Build Packet and Build Context gains two keys. `success_url` goes on every page that feeds a Checkout and holds that Checkout's post-payment destination, for the `next-success-url` meta tag the SDK reads for express orders. `step_number` goes on each `checkout_step` and is its position on its path, for the step form's `data-next-step-number`. The build prompt and the `next-campaigns-build` skill now describe the select-page handoff the templates use: the swap-mode bundle selector writes the cart, the SDK persists it, and a checkout button or link moves on. `forcePackageId` is only for a page with no selector. Step forms carry `data-next-checkout-step` and `data-next-step-number`.
+- QA: test orders drive the Checkout on the tested path instead of the first page typed `checkout`. On a multi-step path the runner enters the cart on the select page or the first step. It submits each `checkout_step` form and checks the page lands on the step's declared next page, recording one `checkout_step_submitted` ladder rung per step. The order is submitted only on the Checkout. On a page with bundle cards, the cards plus a checkout button now count as a cart-entry control (`control_kind: checkout_button`), and `--select-package` clicks the matching `data-next-bundle-card`. `tiers` plans read tiers and bumps from every page of each Checkout's path. The legacy API test order takes its success URL from the Checkout. The theme gate covers `select` and `checkout_step` pages.
+- Doctor and the Build Brief treat exit intent, promo-code input and order bumps on `select` and `checkout_step` pages like those on a Checkout. The payment-method residue scan also reads built `select` and `checkout_step` pages, where express buttons render. The commercial journey summary prices the cart on the checkout-flow page that carries it.
+- The runtime recipe enumerates the five new `campaign-spec` sources (revision `1.0.3`).
+
 ## [1.55.0] - 2026-10-07
 
 ### Changed

package/CONTEXT.md

@@ -37,6 +37,17 @@ applied brand tokens, and pricing-surface modes. QA reads it to fail "still
 visually the starter template" deterministically.
 _Avoid_: style guide, design tokens doc, theme report
 
+**Checkout (payment page)**:
+The page on a checkout path that takes payment: CampaignSpec `type: "checkout"`
+(campaigns-os#641). It forwards to an upsell, downsell or thank-you page, and
+every path from an entry page to an upsell passes exactly one. Pages ahead of
+it render the same SDK checkout surface without placing an order: a `select`
+page (the bundle picker) and `checkout_step` pages (a split checkout's
+information and shipping forms). A campaign may hold several Checkouts, one
+per split-test path; every consumer asks for "the Checkout on this path"
+(`campaign-spec/checkout-flow.ts`), never for the first page typed checkout.
+_Avoid_: first checkout, checkout page (for a step), final step
+
 **Template Reference**:
 The canonical baseline for a template family: its safe runtime structure,
 expected screenshots or render references, default assets, starter residue

package/campaign-spec/README.md

@@ -16,7 +16,9 @@ rules are pure TypeScript over a normalized spec with no heavy dependencies.
 campaign-spec/
   index.ts                 # public interface
   types.ts                 # CampaignSpec, Rule, Violation, Tag, Severity
-  normalize.ts             # v4.3 authoring → canonical v4.2 funnels[] shape
+  normalize.ts             # authoring → canonical funnels[] shape; upgrades v4.2/v4.3 to v5
+  checkout-flow.ts         # which page takes payment; v4 → v5 upgrade; path helpers
+  routing.ts               # a page's outgoing edges
   rules/
     index.ts               # preset RuleSet constants
     cycle-detection.ts     # one file per rule
@@ -131,6 +133,18 @@ IIFE) and expose the public interface on `window` to run export-time validation
 client-side. The rules have no Node-only or live-data dependencies, so the same
 registry that backs the CLI doctor runs unchanged in the browser.
 
+## CampaignSpec 5.0: the page that takes payment
+
+`checkout` is the page that takes payment; `checkout_step` is a checkout form
+that collects details and moves on through `next_page`; `select` is the bundle
+picker before them. `normalize()` upgrades a 4.2/4.3 spec to that vocabulary
+on read (each `checkout` whose resolved forward target is another `checkout`
+becomes `checkout_step`) and never mutates its input. Four rules hold the
+shape — `CheckoutForwardTarget`, `PrePaymentForwardTarget`,
+`CheckoutStepReachesCheckout` and `OneCheckoutPerPath` — and none of them
+reads page order or page names. `paymentPageFrom`, `checkoutPathFrom` and
+`paymentPagesForFunnel` answer "which Checkout is on this path".
+
 ## See also
 
 - `../CONTEXT.md` — domain vocabulary.

package/campaign-spec/dist/checkout-flow.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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 type { Funnel, Page } from './types.ts';
+/** The CampaignSpec lineage this module writes when it upgrades a v4 spec. */
+export declare const CURRENT_SCHEMA_VERSION: "5.0";
+/** The page that takes payment. */
+export declare const PAYMENT_PAGE_TYPE: "checkout";
+/** A checkout form that collects details and moves on without placing an order. */
+export declare const CHECKOUT_STEP_PAGE_TYPE: "checkout_step";
+/** Pages that lead into a Checkout without taking payment themselves. */
+export declare const PRE_PAYMENT_PAGE_TYPES: readonly ["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 declare const CHECKOUT_FLOW_PAGE_TYPES: readonly ["select", "checkout_step", "checkout"];
+/** Where a Checkout may send the shopper once payment succeeds. */
+export declare const POST_PAYMENT_PAGE_TYPES: readonly ["upsell", "downsell", "thankyou"];
+/** Post-purchase offer pages: reaching one means an order was already placed. */
+export declare const POST_PURCHASE_OFFER_PAGE_TYPES: readonly ["upsell", "downsell"];
+export declare function isPaymentPage(page: Page | null | undefined): boolean;
+export declare function isCheckoutStepPage(page: Page | null | undefined): boolean;
+export declare function isPrePaymentPage(page: Page | null | undefined): boolean;
+export declare function isCheckoutFlowPage(page: Page | null | undefined): boolean;
+/**
+ * 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 declare function resolveRouteTargetPage(pages: readonly Page[], target: string | null | undefined): Page | null;
+/** The page this page's forward link resolves to, within `pages`. */
+export declare function forwardTargetPage(pages: readonly Page[], page: Page | null | undefined): Page | null;
+/**
+ * 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 declare function checkoutPathFrom(pages: readonly Page[], start: Page | null | undefined): Page[] | null;
+/** The Checkout reached by walking forward from `start`, or null. */
+export declare function paymentPageFrom(pages: readonly Page[], start: Page | null | undefined): Page | 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 declare function entryPages(funnel: Funnel | null | undefined): Page[];
+/**
+ * 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 declare function paymentPageForFunnel(funnel: Funnel | null | undefined): Page | null;
+/** Every distinct Checkout reached from the funnel's entry pages, in entry order. */
+export declare function paymentPagesForFunnel(funnel: Funnel | null | undefined): Page[];
+/**
+ * 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 declare function upgradeCampaignSpec<T>(input: T): T;

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;