@nextcommerce/campaigns-os 1.55.0 → 1.59.0

package/CHANGELOG.md

@@ -2,6 +2,130 @@
 
 Notable supported-surface changes are recorded here.
 
+## [1.59.0] - 2026-10-09
+
+### Changed
+
+- Publishes the untagged `1.58.0` change: multi-step checkout frontmatter follows the starter-template `next_step` contract (campaigns-os#641).
+- Publishes `1.58.0+agent.2`: doctor warns `template_contract.select_step_missing` for a two-step family with no select page before checkout, and the phone scan skips comments and `<style>` content (campaigns-os#658, campaigns-os#660).
+- Publishes `1.58.0+agent.3`: a stale build fingerprint names the extra, missing and changed files and flags sync conflict copies (campaigns-os#659).
+- Publishes `1.58.0+agent.4`: QA verdicts separate planned order paths from retry attempts (campaigns-os#661).
+- Publishes `1.58.0+agent.6`: QA cart entry chooses each slot's variant on a select page before Next (campaigns-os#667).
+- Publishes `1.58.0+agent.7`: the starter catalog is re-synced to campaign-cart-starter-templates `d5ff501` (campaign-cart-starter-templates#223, SDK 0.4.42).
+- Bundled skills advance to `1.59.0+skills.1`.
+
+### Added
+
+`record deploy` records a hosted deploy. On a packet whose `deploy.target` is not `local-serve` it takes an https `--base-url` naming the campaign's route root (plain http only on a loopback host), requests every built page there, and requires each to answer HTTP 200. It then requests every script and stylesheet the built pages load from that origin and compares each one's sha256 with the file in the built output, following redirects only within that origin and reading no more bytes than the built file holds; a missing, larger or different asset refuses the record, naming the URL and the built file. A `record build` of other output between the probe and the write refuses the record, on a `local-serve` packet too. A response with no readable body refuses as a transport failure, not as a byte mismatch. HTML is not compared, because hosts inject toolbars and other markup. A passing probe writes what the loopback path writes: `deploy.preview_url` on the packet, and `stages.deploy` completed with the URL in `outputs`, one evidence line per page and per matched asset, and the build fingerprint it probed, so a later `record build` of other output makes deploy owed again. `local-serve` packets keep the loopback-only rules. The hosted all-template preview no longer skips the deploy stage: `next` hands off `record deploy` for the recorded preview URL and then QA, and the hosted deploy prompt names `record deploy` in place of hand-editing `stages.deploy` (campaigns-os#657).
+
+## [1.58.0+agent.7] - 2026-10-09
+
+### Changed
+
+The vendored starter catalog is re-synced to campaign-cart-starter-templates `d5ff501`, which carries the multi-step checkout contract from campaign-cart-starter-templates#223 and the Campaign Cart SDK 0.4.42 pin. Builds made with 1.58.0's `next_step` frontmatter now take templates whose step forms and select links read `next_step` and whose `next-success-url` is the Checkout's post-payment destination. Every certified family records 0.4.42 verification evidence (`sdk-0.4.42-2026-10-09`), and the eight agent CampaignSpec fixtures pin `sdk_version` 0.4.42. The certified-family fixtures are regenerated at the pin, and the payment-chrome asset pin moves to `d5ff501`; the five asset hashes are unchanged.
+
+The SDK attribute index moves to v0.4.42 with the same recipe; it returns the same 149 names as at v0.4.41. 0.4.42 joins the cart-placeholder verified pins: the ten renderer and enhancer files the placeholder lists come from have the same git blob ids at v0.4.38 and v0.4.42. The checkout field-name mapping is unchanged at v0.4.42. The SDK support policy names 0.4.42 as `latest_known_release`; `minimum_supported` and `preferred_minimum` are unchanged.
+
+## [1.58.0+agent.6] - 2026-10-09
+
+### Fixed
+
+On a select page whose bundle slots each need a variant (size, colour) before Next, `qa run --test-order` now chooses one per slot before clicking the checkout control. It does this after revealing the second step and after any bundle card click, one field at a time, over the visible, enabled slot variant selects (`[data-next-variant-selectors] select` or `.next-slot-variant-field select`, counted visible when the field is). When a field shows a dropdown UI (`os-dropdown` with a `.os-card__variant-dropdown-toggle` and `os-dropdown-item` rows, as the olympus-mv-two-step starter renders), the runner clicks the toggle and a row like a shopper, even when the SDK has already filled the select, because a page may count a field as chosen only when a row was clicked. It clicks the row matching the select's current value when that row is in stock, so the cart stays what the SDK chose, and otherwise the first in-stock row. After the toggle click it finds the field again by slot identity and the row again by its value, and waits up to 2 seconds for that row to show. A field with no dropdown UI gets its first in-stock option only when its select is empty, with `input` and `change` dispatched. Each choice is recorded on the `entered_via_landing` evidence as `variant_selections: [{ bundle_id, slot, variant_code, value, via }]`, with `via` set to `dropdown` or `select`, so the ordered variants can be checked against the cart lines. A field with no in-stock row or option, or a row that does not show or cannot be clicked, fails the path before Next with the new code `cart_entry_variant_unfilled`, naming the slot, instead of `cart_entry_no_navigation` after the navigation timeout. It classifies as `not_created` like the other cart-entry codes. A page whose filled selects have no dropdown UI is left untouched and `variant_selections` is omitted. Before this, every path on a page that blocks Next until a variant is picked failed with `cart_entry_no_navigation` (campaigns-os#667).
+## [1.58.0+agent.4] - 2026-10-09
+
+### Fixed
+
+A QA run that re-ran failed order paths no longer reads as more paths than it planned. Each `test_orders[]` entry in the verdict now carries `attempt` (1 for the first try, 2 for the re-run) beside the `plan_id` of the planned path it belongs to, and `qa run` prints a summary line that keeps paths, attempts and created orders apart, such as `Test orders: 5 paths, 10 attempts, 0 orders created`. Before this, a run capped at five paths where every path was re-run once showed ten entries and nothing to say which were retries. The Assembly Report's `stages.qa.purchase_proof` gains `test_order_attempts`, and `order_paths_executed` now counts planned paths rather than attempts. Verdicts written before `attempt` existed count each entry as a path, as they did before. The array keeps one entry per attempt and no existing field changed shape.
+
+## [1.58.0+agent.3] - 2026-10-09
+
+### Fixed
+
+When the built output no longer matches the recorded build fingerprint, doctor's `built_output.fingerprint_stale` and the `polish capture` refusal now name the paths that are extra, missing, or changed, at most 20 per list followed by `(+N more)`. Before, both reported only the recorded and current hashes, so finding the files behind a mismatch took a manual diff of `_site/`. `record build` keeps the path and SHA-256 list behind the fingerprint on `stages.assembly.build_manifest` to make the comparison possible; the field is additive and the fingerprint value is unchanged. A file or folder named like a macOS or iCloud sync conflict copy (`<name> 2.<ext>` beside `<name>.<ext>`) is marked as one, with a hint to remove the copies and rebuild. A build recorded before this change carries no manifest: the refusal is unchanged and says to run `record build` again to record one (campaigns-os#659).
+
+## [1.58.0+agent.2] - 2026-10-09
+
+### Fixed
+
+- Doctor, and so `start` and `build`, warns `template_contract.select_step_missing` before build when the selected template family puts package selection on its own `select` page and its checkout carries no selector, but no enabled `select` page in the Map leads to a Checkout. The certified family affected today is `olympus-mv-two-step`. Without the select page, QA resolves the landing as the entry page, finds no add-to-cart control, and every order path fails after build, polish and deploy. The warning names the Checkout and funnel and the fix: add a Select page between the entry page and checkout in Map Builder. It stays silent when a `select` page routes to that Checkout, when the family's checkout carries its own selector, and for a Checkout pinned to another family through `sdk_hints.template_family`. The family's shape is read from the commerce surface catalog's `selectStep` and `mainSelector` surfaces. The warning does not block intake (campaigns-os#658).
+- `copy.hardcoded_phone` no longer reads digit runs inside HTML comments, `<style>` blocks or CSS comments as phone numbers, such as a design-export frame name like `Group 1000003339`. Visible phone numbers still warn, at their original line numbers (campaigns-os#660).
+
+## [1.58.0] - 2026-10-09
+
+### Changed
+
+Page Kit frontmatter for multi-step checkout paths follows the starter-template contract adopted in NextCommerceCo/campaign-cart-starter-templates#223. On a `select` or `checkout_step` page on a path to a Checkout, `next_url` is now the Checkout's post-payment destination, the meaning `next_url` has on every checkout page; the layouts render it as `next-success-url`, which the SDK reads for express orders. The page's forward link moves to the new `next_step` key, which the templates render as the step form's `data-next-checkout-step` and the select page's checkout link. `step_number` is unchanged. `success_url` is no longer emitted as a frontmatter key; it stays a CampaignSpec field on `checkout` pages, and the Build Context and Build Packet schemas still accept it so packets written by 1.56.0 and 1.57.0 validate. A landing page that feeds a Checkout keeps `next_url` as its call-to-action target, because every certified family's landing call-to-action reads it; it no longer carries `success_url`, and the build prompt takes an express landing page's `next-success-url` from the Checkout's own `next_url`. The build prompt and the `next-campaigns-build` skill describe the new keys. Bundled skills advance to `1.58.0+skills.1` (campaigns-os#641).
+
+## [1.57.0+agent.1] - 2026-10-08
+
+### Fixed
+
+Reading a 4.2 or 4.3 spec no longer turns a `checkout → checkout` chain linked through `success_url` into Checkout Steps with no way forward. A page retyped `checkout_step` keeps the link it followed as a checkout: the resolved forward target is written to `next_page` and `success_url` is dropped, because routing ignores `success_url` on a step. Before this, the upgraded spec failed `CheckoutStepReachesCheckout` and warned `RouteFieldIgnoredForPageType` on every step. A `next_page` the checkout never took (shadowed by `success_url`) is replaced by the followed link. Chains already linked through `next_page`, and 5.x specs, read as before.
+
+## [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,97 @@
+/**
+ * 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.
+ *
+ * A retyped page keeps the link it followed as a checkout. A `checkout_step`
+ * moves on through `next_page` only (routing.ts ignores `success_url` on it),
+ * so a v4 chain linked through `success_url` would otherwise upgrade into a
+ * step with no way forward and fail CheckoutStepReachesCheckout. The resolved
+ * forward target is written to `next_page` and `success_url` is dropped; a
+ * `next_page` the checkout shadowed (never taken) is replaced by it.
+ */
+export declare function upgradeCampaignSpec<T>(input: T): T;

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

@@ -0,0 +1,245 @@
+/**
+ * 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.
+ *
+ * A retyped page keeps the link it followed as a checkout. A `checkout_step`
+ * moves on through `next_page` only (routing.ts ignores `success_url` on it),
+ * so a v4 chain linked through `success_url` would otherwise upgrade into a
+ * step with no way forward and fail CheckoutStepReachesCheckout. The resolved
+ * forward target is written to `next_page` and `success_url` is dropped; a
+ * `next_page` the checkout shadowed (never taken) is replaced by it.
+ */
+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) => {
+                if (!retype.has(page))
+                    return page;
+                const step = { ...page, type: CHECKOUT_STEP_PAGE_TYPE };
+                const forward = forwardRouteTarget(page);
+                if (forward === null)
+                    return step;
+                const { success_url: _ignoredOnStep, ...rest } = step;
+                return forward === page.next_page ? rest : { ...rest, next_page: forward };
+            }),
+        };
+    });
+    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.