@nextcommerce/campaigns-os 1.55.0 → 1.59.0

package/contracts/runtime-recipe.campaigns-os-node-v1.json

@@ -3,7 +3,7 @@
   "_growth_note": "When a bound below is genuinely reached, the answer is to find out why before raising it. A dependency install that exceeds its bound on a warm machine is a supply-chain change, not a slow morning; an output inventory that exceeds its file or byte bound is a build that went wrong, not a package that grew 50x overnight. Raising a bound is the fallback, it advances recipe_revision, and it owes a release-ledger entry. Widening the accepted npm range follows the same path, and its trigger is external and checkable: widen when a Node release line ships that npm major by default, not when a particular machine happens to have it installed.",
   "schema": "campaigns-os-runtime-recipe/v1",
   "recipe_kind": "campaigns-os-node-v1",
-  "recipe_revision": "1.0.2",
+  "recipe_revision": "1.0.3",
   "refusal_reason_code": "runtime_recipe_refused",
   "fail_closed": true,
   "unperformable_check_disposition": "failed",
@@ -106,6 +106,7 @@
     "fingerprint_algorithm": "sha256",
     "files": [
       "campaign-spec/analytics-vocabulary.ts",
+      "campaign-spec/checkout-flow.ts",
       "campaign-spec/index.ts",
       "campaign-spec/normalize.ts",
       "campaign-spec/package.json",
@@ -113,7 +114,9 @@
       "campaign-spec/rules/analytics-contract-shape.ts",
       "campaign-spec/rules/assembly-hints-shape.ts",
       "campaign-spec/rules/campaign-metadata.ts",
+      "campaign-spec/rules/checkout-forward-target.ts",
       "campaign-spec/rules/checkout-has-success-url.ts",
+      "campaign-spec/rules/checkout-step-reaches-checkout.ts",
       "campaign-spec/rules/cycle-detection.ts",
       "campaign-spec/rules/design-source-shape.ts",
       "campaign-spec/rules/downsell-without-upsell.ts",
@@ -124,9 +127,11 @@
       "campaign-spec/rules/funnel-weight-sum.ts",
       "campaign-spec/rules/index.ts",
       "campaign-spec/rules/offer-ref-integrity.ts",
+      "campaign-spec/rules/one-checkout-per-path.ts",
       "campaign-spec/rules/package-pricing-sanity.ts",
       "campaign-spec/rules/page-count.ts",
       "campaign-spec/rules/page-id-uniqueness.ts",
+      "campaign-spec/rules/pre-payment-forward-target.ts",
       "campaign-spec/rules/promo-code-input-validation.ts",
       "campaign-spec/rules/promo-codes-shape.ts",
       "campaign-spec/rules/route-field-ignored-for-page-type.ts",

package/contracts/supported-surface.json

@@ -1,6 +1,6 @@
 {
   "_note": "The downstream contract manifest. Everything listed here is SUPPORTED SURFACE: consumers (campaigns-agent, campaign-builder, the private ops repo, page-kit campaign repos) may depend on it, and changing it is a deliberate act — hashed entries require a surface_version bump in the same change (check-supported-surface.mjs --base, mirroring the skills.json bump gate), named entries must keep existing at their path, cli_commands must keep resolving in the CLI dispatch, package_exports must stay exported, and every entry must ship in the npm pack (files[] coverage). Anything NOT listed here — src/** internals, scripts/** checkers, examples/**, prompts/**, contracts/** other than this file and the entries named[] below (the orientation contract, the release ledger, and the consumer-facing orientation fixtures) — is implementation: consumers may read it for context but must not build on it, and it can change without notice. Rationale and the compatibility promise: docs/supported-surface.md.",
-  "surface_version": "1.55.0",
+  "surface_version": "1.59.0",
   "package_exports": [
     "./commercial-journey",
     "./commercial-parity",
@@ -8,6 +8,7 @@
     "./campaign-spec",
     "./legacy-migration",
     "./schemas/campaign-spec.v4.schema.json",
+    "./schemas/campaign-spec.v5.schema.json",
     "./schemas/campaigns-os-legacy-migration-inventory.v0.schema.json",
     "./schemas/campaigns-os-legacy-provisioning-plan.v0.schema.json",
     "./schemas/campaigns-os-legacy-provisioning-receipt.v0.schema.json",
@@ -51,7 +52,7 @@
       "sha256": "53269453dfdaac4b286124d445b60b0c46205dfbaf8037ac61b30254a32df53a"
     },
     "contracts/runtime-recipe.campaigns-os-node-v1.json": {
-      "sha256": "90aaaaade90cf2525ea1aa05be5cb2d02b57e6e59f9278a946efa8a087946fd3"
+      "sha256": "ab0537a4756310d3a35b400d3932e46695a820f1b8b398f52f6fd0906098bc1d"
     },
     "schemas/campaign-build-brief.v1.schema.json": {
       "sha256": "d524003184131398dc15fdb84385af1be0de0c69d6c5ede7278689a5b6101b81"
@@ -63,14 +64,17 @@
       "sha256": "625a6f2ed6bee726f9cddad750e64a54a7e03744c777f5a70afe4a39afdd9848"
     },
     "schemas/campaign-runtime-build-context.v0.schema.json": {
-      "sha256": "f310c1b7844d9b1994864d15858ff0c6f17efc1e5285ba193d181bdb2dd4be2f"
+      "sha256": "2aa8f652f6bb602cdbadada34b5793da1bb8842223fcae2fd24700aac14f4de6"
     },
     "schemas/campaign-runtime-build-packet.v0.schema.json": {
-      "sha256": "5002529c5979c4d8fef7e298de82ebdf625ffbd11f5284ba684d96d173788d62"
+      "sha256": "e57d31f190a7ddfbf63afb39bc67762a09dff25707c841e84a4e1c6ee9afd9ed"
     },
     "schemas/campaign-spec.v4.schema.json": {
       "sha256": "af56c3de638d3c4e1fd5df8c2d733754d9ad16caa23b5bec92ce3a6f71bd0271"
     },
+    "schemas/campaign-spec.v5.schema.json": {
+      "sha256": "2923382e94ac51f6a19a3f9dfd0993d8c30fab33cd9be3d6901f314e02f5d960"
+    },
     "schemas/campaigns-os-legacy-migration-inventory.v0.schema.json": {
       "sha256": "d6edc4572900d15fdaf6b8c59916b0d885303c1d398bdadeb7c58285522c9049"
     },
@@ -120,7 +124,7 @@
       "sha256": "dfc9abed38d456969e47a21f606d308a03bdf036f3466f7d6e47a602747dacf4"
     },
     "contracts/effects.v1.json": {
-      "sha256": "10a9020aaba5780e2ee2f3ddf6d81127047f6caec0de774c48540d9b664e0a6a"
+      "sha256": "9c1d69e44eab7403ca3ff80f850214d89b0a02fdc51544beef37dbd0a653eeaa"
     },
     "schemas/campaigns-os-effects.v1.schema.json": {
       "sha256": "3eadd22169ab98bc7c2f682af2751267605170581182158d96be035b0cfe44dc"

package/contracts/template-brand-contract.shared-commerce.v0.json

@@ -55,7 +55,7 @@
       },
       "asset_pin": {
         "repo": "NextCommerceCo/campaign-cart-starter-templates",
-        "sha": "783329017c6994a94d11e46580c33bd052aabdb0",
+        "sha": "d5ff501ab57aef160a7108341de8a952006a28a4",
         "path": "src/<family>/assets/<asset>",
         "note": "asset_sha256 is the sha256 of each shipped starter asset at this commit (the commerce-surface-catalog _synced_from_sha pin; the bytes are identical across every family). A served asset whose bytes hash to the shipped value is the untouched starter asset and counts as residue even though its markup names no method; different bytes mean it was edited in place. check-template-doctrine verifies these hashes against the pinned checkout."
       },

package/docs/build-packet.md

@@ -19,7 +19,8 @@ The current schema is `schemas/campaign-runtime-build-packet.v0.schema.json`.
 
 A saved Map is optional for a prepared-HTML build. The coding agent authors an
 ordinary CampaignSpec from the brief, source design and configured campaign's
-real commerce values, following `schemas/campaign-spec.v4.schema.json`. The
+real commerce values, following `schemas/campaign-spec.v5.schema.json` (a 4.2/4.3
+spec still reads, upgraded on read; see `docs/versioning.md`). The
 operator supplies the selected store/campaign, public Campaigns API key, intended
 pages and commercial choices, plus store contact details and policy URLs. Verify
 the store/campaign binding, and read the package, offer and shipping references
@@ -827,7 +828,7 @@ Blockers (not waivable — the markup provably does not do what it says):
 - `CHECKOUT_NOT_FORM` — `data-next-checkout` on an element that is not `<form>`.
 - `WRONG_FIELD_NAME` — `data-next-checkout-field` with a value the SDK does not
   map. The set is vendored from the SDK at a named tag
-  (`src/sdk-attribute-index.mjs`, currently v0.4.41: `email`, `fname`, `lname`,
+  (`src/sdk-attribute-index.mjs`, currently v0.4.42: `email`, `fname`, `lname`,
   `phone`, `address1`, `address2`, `city`, `province`, `postal`, `country`,
   `payment-method`, `accepts_marketing`, `cc-number`, `cc-month`, `cc-year`,
   `exp-month`, `exp-year`, `cvv`, the legacy `card-*` spellings, and any
@@ -1020,13 +1021,25 @@ than hand-adding the field. Note that a committed artifact set always reads
 stale to the readback once HEAD moves past it — freshness proof is a
 regeneration at HEAD, not a property a commit can preserve.
 
-Commit durable packet/context/report artifacts when they represent a real build handoff. The rest of `.campaign-runtime/` is machine-local and is not for the campaign repository: `run-session.json`, `command-lifecycle.jsonl`, `agent-deviations.jsonl`, `workflow-findings.jsonl`, `run-records/`, `fetched-specs/`, `polish-evidence/`, `evidence/`, and `*.log`/`*.tmp` are per-machine, append-only, or carry live URLs and absolute paths, and so are the full QA verdicts `qa run` writes under the target's `qa-output/`. `start`, `prepare-build`, `install-agent-context`, and `run start` write a managed ignore block for exactly that set into the target's `.gitignore` once (keyed on its marker line; edit the list beneath it freely). The readback bundle (`build-context.json`, `assembly-report.json`, `doctor-output.json`, `qa-verdict.json`), `input/`, `theme/`, `agent-context/`, and `setup-handoff.json` are deliberately not ignored. The Campaigns API key is a public, browser-side, domain-allowlisted key and may already be present in the local CampaignSpec as `campaign.campaigns_api_key`; do not duplicate it into the packet unless the spec is unavailable. Do not commit raw private API responses, backend secrets, or temporary media exports.
+Commit durable packet/context/report artifacts when they represent a real build handoff. The rest of `.campaign-runtime/` is machine-local and is not for the campaign repository: `run-session.json`, `command-lifecycle.jsonl`, `agent-deviations.jsonl`, `workflow-findings.jsonl`, `run-records/`, `fetched-specs/`, `progress/`, `polish-evidence/`, `evidence/`, and `*.log`/`*.tmp` are per-machine, append-only, or carry live URLs and absolute paths, and so are the full QA verdicts `qa run` writes under the target's `qa-output/`. `start`, `prepare-build`, `install-agent-context`, and `run start` write a managed ignore block for that set into the target's `.gitignore` (keyed on its marker line; edit the list beneath it freely). An existing block gains `qa-output/` and `.campaign-runtime/progress/` when they are missing, since those hold live URLs, order references and remit records. The readback bundle (`build-context.json`, `assembly-report.json`, `doctor-output.json`, `qa-verdict.json`), `input/`, `theme/`, `agent-context/`, and `setup-handoff.json` are deliberately not ignored. The Campaigns API key is a public, browser-side, domain-allowlisted key and may already be present in the local CampaignSpec as `campaign.campaigns_api_key`; do not duplicate it into the packet unless the spec is unavailable. Do not commit raw private API responses, backend secrets, or temporary media exports.
 
 Packet-mode `doctor` is inspection-only by default and preserves retained evidence and active run journals, even when lifecycle capture is configured. Use `--write` to intentionally record fresh evidence; `--no-write` takes precedence. Inspection still reports current blockers and keeps the same exit status.
 
 `campaigns-os doctor --packet <packet> --write` restates its outcome on the Assembly Report's `stages.doctor` (status, command, outputs, blockers, warnings, `checked_at`). A re-run that reaches the same outcome leaves the report's bytes unchanged rather than refreshing the timestamp alone, so a digest taken of the report — a Run Record's `assembly_report` sha256 — keeps verifying across repeated doctor runs; a changed outcome still rewrites the file.
 
-`campaigns-os start` / `campaigns-os prepare-build` writes packet, context, report, and generated doctor-output paths as relative paths by default, including sibling CampaignSpec/source directories such as `../campaign-source`. `campaigns-os doctor` continues to accept older absolute-path packets; use `campaigns-os doctor --packet <packet> --write --strip-paths` when regenerating a commit-ready doctor output from an older packet. Committed handoff artifacts should not contain machine-local absolute paths unless no relative form is possible.
+`campaigns-os start` / `campaigns-os prepare-build` writes portable packet, context, report, and generated doctor-output paths. Resolve each path from its reader's base:
+
+| Field | Base | Writer |
+|---|---|---|
+| Build Packet `spec.local_path`, `design_source_package.path`, `source_html.root`, `build_brief.input_path`, `build_brief.normalized_path`, `assembly.target_repo`, `assembly.commerce_catalog.path` | Build Packet file's directory, including when `--out` places it under `config/` | `start` / `prepare-build`; `record brief` and stage records retain this base for older absolute values |
+| Build Packet `source_html.pages[].path`; Build Context `page_map[].source_path` | Source HTML root | `start` / `prepare-build`; later context writes retain it |
+| Build Packet and Build Context `source_html.pages[].page_kit.target_path` / `page_map[].page_kit.target_path` | Page Kit output directory | `start` / `prepare-build`; later packet/context writes retain it |
+| Build Packet `assembly.output_dir` and `source_html.pages[].page_kit.output_path`; Build Context `page_map[].output_path` and `page_map[].page_kit.output_path` | Target repository root | `start` / `prepare-build`; later packet/context writes retain it |
+| Build Context and Assembly Report `design_source_package.path` | Directory of that context or report file (normally `.campaign-runtime/`) | `start` / `prepare-build`; later report writes retain it |
+| Normalized Campaign Build Brief `_meta.input_path` | Directory of the normalized brief file | `start` / `prepare-build`; `record brief` and `record spec` retain it |
+| Other listed Build Context, Assembly Report, and doctor-output filesystem paths | Target repository root | Intake, `doctor --write`, `next`, and stage writes |
+
+Outside source inputs use ordinary relative paths from the applicable base; keep them at the recorded locations when moving the repository. Manifest paths embedded in decision evidence use relative paths from the target repository root. A stored command such as `next.command` uses a relative packet path and runs from the target repository root. `campaigns-os doctor` continues to accept older absolute-path packets; `--strip-paths` remains available when inspecting an older packet. Machine-local run sessions and journals remain ignored and may use absolute paths.
 
 `start` / `prepare-build` also run the [Brand Theme Bridge](./brand-theme-bridge.md)
 in `inspect_only` mode. The optional theme evidence lives in `context.theme`,
@@ -1194,6 +1207,20 @@ recorded build). `polish capture` refuses by name when the built route root is
 missing, unreadable, or drifted; symbolic links are never build output and are
 skipped by the walk.
 
+`record build` also keeps the manifest itself on `stages.assembly.build_manifest`,
+a sorted list of `{ "path", "sha256" }` entries that hashes to `build_fingerprint`.
+When the output drifts, `built_output.fingerprint_stale` and the `polish capture`
+refusal name the paths that are extra, missing, or changed against it, at most 20
+per list followed by `(+N more)`; doctor's issue `detail.drift` carries the counts
+and the same capped lists. An extra path shaped like a macOS or iCloud sync
+conflict copy (`<name> 2.<ext>`, `<name> 3.<ext>`, ...) whose unsuffixed original
+also exists is marked `[sync conflict copy]` with a hint to remove those copies and
+rebuild; a trailing number alone (`chapter 12.html`) is not flagged. A record
+made before build kept a manifest, or a manifest that does not hash to the recorded
+fingerprint, refuses as before and says the manifest is unavailable; run
+`record build` again to record one. Cleaning `_site/` before a build is Page Kit's
+job, not this check's.
+
 A stale or missing Assembly Source Package Fingerprint is waivable only as an
 exceptional Source Freshness Waiver. The waiver must be structured in
 `waivers[]`, with `scope: "assembly_source_package_freshness"` or an
@@ -1463,10 +1490,29 @@ Fresh `prepare-build` output also writes `source_html.pages[].page_kit` for mapp
 - `target_path` is the page file relative to `assembly.output_dir` (`checkout.html`, `receipt.html`, etc.).
 - `output_path` is the same target file relative to `assembly.target_repo`.
 - `public_route` is the rendered campaign-rooted route Page Kit should produce.
-- `page_type` is the CPK runtime/analytics vocabulary (`product`, `checkout`, `upsell`, `receipt`), not the richer CampaignSpec or producer page type. CampaignSpec `select` pages project as CPK `checkout` because they are pre-checkout runtime selection surfaces.
-- `frontmatter` names the Page Kit frontmatter fields the build should write or preserve.
+- `page_type` is the CPK runtime/analytics vocabulary (`product`, `checkout`, `upsell`, `receipt`), not the richer CampaignSpec or producer page type. CampaignSpec `select` and `checkout_step` pages project as CPK `checkout` because they render the SDK checkout surface ahead of the page that takes payment.
+- `frontmatter` names the Page Kit frontmatter fields the build should write or preserve. Beside `page_type`, `permalink`, `next_url` and `decline_url`, multi-step checkout paths follow the starter-template contract. On a `select` or `checkout_step` page on a path to a Checkout, `next_url` is that Checkout's post-payment destination, the meaning `next_url` has on every checkout page, and feeds the page's `next-success-url` meta tag, which the SDK reads for express orders; `next_step` is the page's forward link, rendered as the step form's `data-next-checkout-step` or the select page's checkout link; `step_number`, on a `checkout_step` only, is its position on its path from 1, for the step form's `data-next-step-number`. A landing page keeps `next_url` as its call-to-action target, so an express landing page takes its `next-success-url` from the Checkout's `next_url`. `success_url` is no longer emitted; the schema still accepts it so packets written by 1.56.0 and 1.57.0 validate.
 - `permalink_required` is true when Page Kit's filename-derived route would not match `public_route`.
 
+An entry page (`is_entry: true`) declares the campaign root when `page_url` is
+empty, `/`, `/<slug>/`, or `<slug>`.
+If Page Kit emits its mapped target file, or a materialised template-stock
+family page, at that file's route without a root output, doctor recognizes the
+built page and warns that the root is unserved. The warning names both routes:
+add a redirect from the root to the emitted route or set
+`permalink: /<slug>/` on the entry page, the campaign root as Page Kit emits it.
+It uses `campaign.route_root`: a root-served campaign names `/` and
+`/<file-route>/`; a slug-served campaign names `/<slug>/` and
+`/<slug>/<file-route>/`. The built files stay under `_site/<slug>/` in both cases.
+`qa resolve --packet campaign-runtime.build.json --base-url <preview-url>` then
+prints the locally emitted entry route. An explicit permalink on that entry's
+Page Kit source file takes precedence, even if stale output remains at the
+file route. Doctor still warns if that permalink serves a non-root route and
+the root output is absent. With no permalink, a root `index.html` takes
+precedence over the recorded file route; with a non-root permalink, a present
+root output suppresses the warning while QA keeps the permalink Entry URL.
+Another page's `index.html` cannot stand in for the entry.
+
 The Design Source Package should reference this projection without confusing it
 with Surface Identity. Surface Identity is the campaign-facing join key; Page Kit
 `page_type`, public routes, output paths, CampaignSpec/Map Builder page IDs,
@@ -1754,14 +1800,26 @@ hand-editing `.campaign-runtime/` JSON:
 | `campaigns-os record build --packet <p> [--build-environment <development\|production>] [--adapter-decision <key>=<value>[,<key>=<value>...]]` | `stages.assembly` completed with `build_fingerprint` = doctor's `derived.build_output_fingerprint.value`, `source_package_material_fingerprint` = the report's Design Source Package material fingerprint when present, `evidence.build_environment` = the `--build-environment` value when given (kept from the last record otherwise), and the specified scalar `report.adapter_decisions`; all recordable decisions go in one comma-separated flag (a repeated flag keeps only the last list); `wrapper_policy` stays an intake choice. `stages.polish` resets to `required` (`required_by` build, `required_for` qa) unless its evidence is bound to this exact output; a completed `stages.deploy` whose `source_build_fingerprint` names other output resets to `required` the same way, without the old probe's `outputs` and `evidence`, and its prior record is kept in `stages.deploy.history` (a deploy with no `source_build_fingerprint`, recorded before deploy stamped it, is kept) | doctor cannot compute the fingerprint (no `_site/<public_route_slug>/`), setup is still required, `stages.setup` is not terminal, or an adapter decision key/value is invalid |
 | `campaigns-os record polish --packet <p> --evidence <file>` | `stages.polish` from the file (`docs/polish-evidence.md` §7: completed, blocked or skipped), bound to doctor's current fingerprint; `report.theme.repair_loop_defect` when the file sets it | build is not recorded for the current output, the file has a shape error (named by field), or, for a completed status, the polish gate doctor evaluates would not pass on the result |
 | `campaigns-os record theme --packet <p>` | `report.theme`: status `applied`, `load_order` `after-next-core`, `css_path`, `commerce_pages` and per-page evidence read from each built commerce page's stylesheet links; any earlier theme waiver is cleared | build is not recorded for the current output, the campaign ships no commerce pages, a built commerce page that loads `next-core.css` does not load `brand-theme.css` (or `checkout-brand.css`) after it or links one missing from the built output, or no built commerce page loads `next-core.css` |
-| `campaigns-os record deploy --packet <p> --base-url <url>` | the packet's `deploy.preview_url` and `stages.deploy` completed with the URL in `outputs`, one evidence line per built page that answered (each page is requested under the URL first), and `source_build_fingerprint` = the recorded `stages.assembly.build_fingerprint` it probed, so a later `record build` of different output makes deploy owed again and `next` routes back to `record deploy` before QA; a byte-identical rebuild keeps it current | the packet is not `local-serve`, the URL is not a loopback origin naming the campaign's route root, a built page does not answer 2xx, polish is not recorded, the built output changed since build was recorded, or the theme gate is blocked |
+| `campaigns-os record deploy --packet <p> --base-url <url>` | the packet's `deploy.preview_url` and `stages.deploy` completed with the URL in `outputs`, one evidence line per built page that answered (each page is requested under the URL first) and, on a hosted target, one per script or stylesheet served as built, and `source_build_fingerprint` = the recorded `stages.assembly.build_fingerprint` it probed, so a later `record build` of different output makes deploy owed again and `next` routes back to `record deploy` before QA; a byte-identical rebuild keeps it current | the URL does not name the campaign's route root; on a `local-serve` packet, the URL is not a loopback origin or a built page does not answer 2xx; on any other deploy target, the URL is not https (plain http only on a loopback host), a built page does not answer 200, or a script or stylesheet the built pages load from that origin is missing or served with other bytes (sha256) than the built output (each one named; HTML is not compared, since hosts inject markup); polish is not recorded, the built output changed since build was recorded, or the theme gate is blocked |
 
 Each command also refuses a stage `next` has not reached: while doctor's
 prepare-build gate is set (`next` answers prepare-build) or while an earlier
 stage in the order below is not terminal. The exception is the one `next`
 makes: on the local preview, a polish doctor carries forward (never recorded
 for this build) does not hold `record deploy` back, as it does not hold `next`;
-polish stays owed and QA reports it.
+polish stays owed and QA reports it. If every mapped page is template stock on
+a hosted preview, doctor carries the same missing-evidence shape forward.
+On a hosted target, record an unset hosted preview URL with
+`campaigns-os qa policy set --packet <p> --preview-url <url>`, then record the
+deploy with `campaigns-os record deploy --packet <p> --base-url <preview url>`. The hosted preview must be a non-loopback
+HTTP(S) URL whose origin or QA-resolved campaign route path differs from `deploy.production_url`;
+query and fragment text does not make the production page a preview. With
+`deploy.preview_url` recorded, run `campaigns-os next qa --packet <p>` and
+`campaigns-os qa run --packet <p> --base-url <preview-url> --browser
+--test-order common`. The recorded hosted preview satisfies the deploy step
+for this all-template shape. After QA records a verdict for the current build,
+`campaigns-os next --packet <p>` reaches closeout without a hosted deploy
+record. QA against the packet's production URL retains the strict gate.
 
 Each command reads the same packet, Build Context and Assembly Report `next`
 reads (`--context` / `--report` override them the same way), validates what it
@@ -1791,7 +1849,7 @@ build` after every page-kit build; a rebuild that changes the output needs
 rebuilt output, `next` asks for QA again if the last QA record names the
 previous build fingerprint, even while its stage status still says completed.
 
-Stage order: `setup → build → polish → deploy → qa`. The picker walks this list and returns the first stage whose recorded status isn't terminal (`completed`, `completed_with_warnings`, `skipped`). During Polish, install the package-owned browser first, then run `campaigns-os polish capture` against the served current build before recording a terminal `stages.polish.status` or proceeding to deploy/QA; the producer attaches package-owned `visual_review.page_load` evidence and never marks the stage complete itself.
+Stage order: `setup → build → polish → deploy → qa`. The picker walks this list and returns the first stage whose recorded status isn't terminal (`completed`, `completed_with_warnings`, `skipped`). During Polish, when a design route exists, install the package-owned browser first, then run `campaigns-os polish capture` against the served current build before recording a terminal `stages.polish.status` or proceeding to deploy/QA; the producer attaches package-owned `visual_review.page_load` evidence and never marks the stage complete itself. Template-stock campaigns with no design route have no capture to run and follow the preview policy above.
 
 | Stage | Report key | Owner |
 |---|---|---|
@@ -1824,7 +1882,7 @@ Result shape (with `--json`):
 Terminal states:
 
 - **`stage: "doctor-blocked"`** — doctor returned errors. Resolve the blockers and re-run `campaigns-os doctor` to confirm before calling `next` again.
-- **`stage: "done"`** — every stage is in a terminal status. Pipeline is complete. To repeat build work, do the work and use `record build`; it makes downstream stages owed as needed. Use `record setup` or `record polish` after repeating those stages, and `qa run` for QA. `record deploy` records a local-serve target; for a hosted deploy, record the URL and stage outcome as the deploy prompt describes. Then call `next` again.
+- **`stage: "done"`** — every stage is terminal. Pipeline is complete. To repeat build work, do the work and use `record build`; it makes downstream stages owed as needed. Use `record setup` or `record polish` after repeating those stages, and `qa run` for QA. `record deploy` records the served deploy, a loopback URL for a local-serve target or an https URL for a hosted one. Then call `next` again.
 - **`stage_blocked: true`** — the picker returned a stage whose recorded status is `blocked`. Don't run the prompt as-is; clear the blocker first.
 
 The legacy form `campaigns-os next <stage>` (e.g. `next build`) still works and is the way to force a specific stage when you want to override the picker.

package/docs/local-setup.md

@@ -3,7 +3,7 @@
 For a new campaign, create an empty working folder and run this from it:
 
 ```sh
-npm init -y && npm install --save-exact next-campaign-page-kit@0.2.0 && npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.55.0 && npx --no-install campaigns-os tooling setup --target . --platform claude
+npm init -y && npm install --save-exact next-campaign-page-kit@0.2.0 && npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.59.0 && npx --no-install campaigns-os tooling setup --target . --platform claude
 ```
 
 `npm init -y` gives the folder its own `package.json`. Without one, npm

package/docs/orientation-contract-reference.md

@@ -26,7 +26,7 @@ Ledger schema id: `campaigns-os-release-ledger/v1`
 Change policy version: `1.0.0`  
 Reason-code vocabulary version: `1.0.0`  
 Limits version: `1.0.0`  
-Supported surface at generation time: `1.55.0`
+Supported surface at generation time: `1.59.0`
 
 ## Forward compatibility
 

package/docs/qa-and-test-orders.md

@@ -101,7 +101,7 @@ recapture. A hosted target (`netlify`, `cloudflare-pages`, …) is unaffected:
 its build stage renders production as before and `page-kit parity` refuses the
 packet (`local_proof.parity.not_local_serve`).
 
-### Missing evidence carried forward on the local preview
+### Missing evidence carried forward on previews
 
 On a `local-serve` packet served from a loopback host (`localhost`,
 `127.0.0.1`, `[::1]`, for both `deploy.preview_url` and `--base-url`), some
@@ -110,20 +110,27 @@ loop. The campaign must still prove its commerce there: store and campaign
 binding, routes, SDK loading, prices and a typed-card order. Only these
 checks are carried forward:
 
-| Check | When |
-| --- | --- |
-| `polish.evidence_missing`, `polish.report_missing` | Polish was never recorded for this build. |
-| `polish.hidden_eager_media.no_capturable_routes` | Every mapped page is template stock (`skip_reason`), so polish capture has no design route to capture. |
-| `polish.hidden_eager_media.capture_malformed` | Only when no page-load capture was recorded at all. |
-| Template-residue severity | With `theme_gate.nothing_generatable`, the starter template is the design, so residue findings are warnings rather than blockers. |
+| Check | Local loopback preview | Hosted preview |
+| --- | --- | --- |
+| `polish.evidence_missing`, `polish.report_missing` | Carried when Polish was never recorded. | Carried only with the all-template `no_capturable_routes` checkpoint. |
+| `polish.hidden_eager_media.no_capturable_routes` | Carried when every mapped page is template stock (`skip_reason`). | Carried when every mapped page is template stock and QA uses the packet's non-loopback `deploy.preview_url`, distinct from `deploy.production_url` by origin or QA-resolved campaign route path. |
+| `polish.hidden_eager_media.capture_malformed` | Carried only when no page-load capture was recorded at all. | Blocked. |
+| Template-residue severity | With `theme_gate.nothing_generatable`, residue findings warn. | Unchanged. |
 
 A carried-forward gate has status `carried_forward`. Doctor reports it as a
-warning starting "Carried forward on the local preview"; `next` moves past
+warning starting "Carried forward on the local preview" or "Carried forward on the hosted preview"; `next` moves past
 polish to deploy and QA; QA records it as a `warn` row, so the verdict is at
 best `ready_with_exceptions`. The evidence is reported as missing, never as
-passed. Any other check keeps its meaning. A hosted preview or production
-packet, and a `local-serve` packet served from any other host, gets the strict
-gates. `record polish` and the waiver commands also keep them strict. Progress
+passed. On a hosted all-template preview, first record an unset preview URL
+with `campaigns-os qa policy set --packet <packet> --preview-url <url>`, then
+record the deploy with `campaigns-os record deploy --packet <packet> --base-url <preview-url>`
+(on a hosted target it takes an https URL, requires every built page to answer
+200, and compares the served scripts and stylesheets with the build by sha256),
+then run `campaigns-os qa run --packet <packet> --base-url <preview-url> --browser --test-order common`. After QA records the current-build verdict, run `campaigns-os next --packet <packet>` for closeout. The hosted exception
+requires a distinct packet `deploy.preview_url`; a query or fragment on the production page does not count as distinct. QA with `--base-url` equal to
+the packet's `deploy.production_url` stays blocked. A `local-serve` packet
+served from any other host also gets strict gates. `record polish` and the
+waiver commands keep them strict. Progress
 snapshots record a carried-forward gate as `not_applicable`, because their
 schema has no carried-forward state.
 
@@ -179,8 +186,9 @@ line and the printed per-URL rows say which URLs those were rather than leaving
 an operator to infer it from `counts.unreachable`. It is `null` only when every
 probed URL resolved, or when nothing was probed at all.
 
-Resolve appends `campaign.public_route_slug` unconditionally — the packet is
-the authority on where a campaign is served, and no flag overrides it. When
+Resolve appends `campaign.public_route_slug` to the preview base for `base_url`
+and page URLs, including when `campaign.route_root` is `/`. A subpath on
+`--base-url` stays ahead of the slug. When
 every derived route is dead, one extra probe of the host without that slug
 separates the two causes and says which it found:
 `route_probe.route_root_mismatch` (the host serves the campaign under a
@@ -308,6 +316,21 @@ for that entry URL. If Entry URLs are empty, still point at a deleted preview, o
 fail their own HTTP assertion, fix `--base-url` or the packet deploy URL before
 continuing.
 
+For an `is_entry` page with `page_url` empty, `/`, `/<slug>/`, or `<slug>`, `qa resolve` uses that page's
+explicit Page Kit permalink first, then the campaign root when
+`_site/<slug>/index.html` exists. If neither applies and Page Kit emitted the
+entry at its recorded page-file route, the printed Entry URL uses that locally
+emitted route. Doctor warns that the Map still points at the unserved root;
+add a redirect from the root to the emitted route or set `permalink: /<slug>/`
+on the entry page. A non-root permalink also gets the warning when root output
+is absent; QA keeps that permalink as its Entry URL. A present root output
+suppresses the warning. The default
+probe checks the printed URL on the host. For either `campaign.route_root: "/"`
+or the default route root, the file route is joined under `base_url` as
+`/<slug>/<file-route>/` (after any preview subpath). The root output, when
+present, uses `base_url` itself. The route-root declaration still determines
+the public route named in doctor's unserved-root warning.
+
 `--base-url` can be either the deploy host or the campaign root. If the Build Packet says `campaign.public_route_slug = "roadside-ready"`, both of these resolve pages under `/roadside-ready/`:
 
 ```bash
@@ -1321,6 +1344,7 @@ Assembly Report's `stages.qa`:
   "declared_order_path_depth": "common",
   "declared_typed_card_depth": "common",
   "order_paths_executed": 3,
+  "test_order_attempts": 3,
   "orders_created": 3,
   "orders_verified": 3,
   "all_orders_test_mode": true
@@ -1333,7 +1357,9 @@ readback bundle, where the verdict's own order arrays are deliberately emptied
 (see the committed verdict sidecar above) — so the signal that a purchase
 happened has to be numbers, not the orders themselves. `all_orders_test_mode` is
 `null`, not `false`, when nothing ran: "no order left test mode" and "no order
-ran" are different facts.
+ran" are different facts. `order_paths_executed` counts planned paths and
+`test_order_attempts` counts every attempt, so a re-run adds an attempt and not a
+path.
 
 Beside it, `stages.qa.evidence` carries the build the verdict judged and the
 outcome of the gates doctor's static scan can only approximate:
@@ -1446,7 +1472,21 @@ timeout still leaves the ladder up to the point of failure. Ladder entries carry
 object. Evidence is resolved even when the step fails or times out, because the
 failing path is the one worth reading.
 
-Four steps write structured evidence today.
+Five steps write structured evidence today.
+
+**Multi-step checkout paths (campaigns-os#641).** The ladder drives the
+Checkout — the page that takes payment (`type: "checkout"`) — on the tested
+path, never the first page typed checkout. When `checkout_step` pages lead
+into it, the runner lands on the first step: through a `select` page ahead of
+it when there is one (`entered_via_landing` with `control_kind:
+checkout_button`), otherwise the step fills the cart itself.
+`customer_fields_filled` fills only the fields that step renders, one
+`checkout_step_submitted` rung per step follows, and the order is submitted
+only on the Checkout. With
+split-test paths in one campaign, each Checkout reached from an entry page is
+its own path; `tiers` plans read declared tiers and bumps from every page of
+that path (the select page or first step declares the cart), and coupons from
+its steps and Checkout.
 
 **`entered_via_landing` — cart entry.** The first rung of the ladder, before
 `opened_checkout`. A checkout renders its customer form whether or not the SDK
@@ -1490,7 +1530,13 @@ checkout — never a receipt or an offer page), navigates there, waits for the
 SDK, and clicks the cart-entry control: an SDK add-to-cart control
 (`[data-next-action="add-to-cart"]`, the only attribute the SDK activates the
 feature on), or a link into the checkout URL carrying `?forcePackageId=`,
-which is what the certified `shop-single-step` landing renders. A control
+which is what the certified `shop-single-step` landing renders, or, on a
+page with bundle cards (`[data-next-bundle-card]`, a `select` page), a checkout
+button: the SDK's `[data-next-action="checkout"]` or a plain link into the
+checkout URL. There the swap-mode selector already wrote the cart and the SDK
+persists it, so the runner keeps the pre-selected card, or with
+`--select-package <ref>` clicks the bundle card carrying that ref first,
+strictly, before the button. A control
 spelled any other way is not a cart entry, so a page that offers nothing else
 fails the step by name (`cart_entry_control_missing`) rather than clicking a
 control the SDK never wired and waiting out the navigation budget. A visible
@@ -1508,17 +1554,51 @@ cart away. `opened_checkout` then records the arrival instead of re-opening.
 
 Evidence: `landing_url`, `landing_page_id`, `landing_page_type`,
 `landing_resolution` (`routes_into_checkout`, `entry_page_fallback`,
-`first_page_fallback`), `control_text`, `control_kind` (`add_to_cart` or
-`checkout_link`), `package_id`, `sdk_ready`, `arrived_url`, the
+`first_page_fallback`), `control_text`, `control_kind` (`add_to_cart`,
+`checkout_link`, or `checkout_button`), `package_id`, `bundle_card_selection`
+when `--select-package` clicked a bundle card, `variant_selections` when the
+runner chose slot variants (below), `sdk_ready`, `arrived_url`, the
 `checkout_selection_surface` probe result, `selection_surface_probe`
 (`loaded`, `reused`, or `failed`), and `selection_surface_probe_error` when it
 failed. The failure codes are
 `cart_entry_unresolved` (no selection surface on checkout and no entry page
 resolves from the topology), `cart_entry_control_missing` (the entry page
 renders no control, or none carrying the requested ref), and
-`cart_entry_no_navigation` (the click did not reach the checkout URL). Each
-fails the path inside the step budget with the code as the first word of the
-error, never as a step timeout.
+`cart_entry_no_navigation` (the click did not reach the checkout URL), and
+`cart_entry_variant_unfilled` (a bundle slot's variant control has no in-stock
+option or row, or its row could not be clicked, named by slot). Each fails the path inside the step budget with the
+code as the first word of the error, never as a step timeout.
+
+On a select page whose bundle slots each need a variant (size, colour) before
+Next, the runner chooses one per slot after any bundle card click and before
+the checkout control, one field at a time. It looks at every visible, enabled
+slot variant select (`[data-next-variant-selectors] select` or
+`.next-slot-variant-field select`, the native select the SDK renders, counted
+visible when its field is):
+
+- When the field shows a dropdown UI (an `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 then a
+  row, like a shopper, even when the select is already filled. 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 s for that row to show, so a menu that opens late or re-renders
+  its rows is handled.
+- With no dropdown UI, an empty select gets its first in-stock option, with
+  `input` and `change` dispatched. A filled native select is left alone.
+
+In stock means enabled, not hidden, and with a non-empty value. For a row it
+also means not `[disabled]`, `aria-disabled`, `.next-oos`,
+`.next-variant-unavailable` or `data-available="false"`, and that the row's
+native option is not disabled. Each choice is recorded in
+`variant_selections` as `{ bundle_id, slot, variant_code, value, via }`, where
+`via` is `dropdown` or `select`, so the ordered variants can be checked against
+the cart lines. A field with nothing to choose, or a row that does not show
+or cannot be clicked, fails the path with `cart_entry_variant_unfilled` before Next is
+clicked. A page whose filled selects have no dropdown UI is left untouched and
+`variant_selections` is omitted.
 
 Which page a funnel enters the cart from is still inferred from topology and
 the rendered checkout. Recording it authoritatively on the spec is the open
@@ -1545,6 +1625,21 @@ own 30s default, so a caller-supplied budget only ever tightens the ceiling. A
 stuck required field fails as that field rather than as an anonymous step
 timeout; a slow-but-working funnel waits no longer than it did before.
 
+**`checkout_step_submitted` — one rung per `checkout_step`.** On a path whose
+Checkout is preceded by `checkout_step` pages, each step's rung checks the page
+is on that step, clicks the submit control of its
+`form[data-next-checkout-step]` (the SDK validates the step's fields, keeps the
+answers and navigates), and waits for the page to land on the step's declared
+next page (`expected_next_url`). It then fills whatever fields the arrived page
+renders. A step whose form carries no `data-next-checkout-step`, or whose
+submit never reaches the declared next page (usually a required field the
+step validates), fails the rung by name; nothing is reserved or submitted, so
+the creation classifier reads it as `not_created`. Evidence: `step_page_id`,
+`step_number`, `expected_next_url`, `arrived_url` and the arrived page's
+`fields` trace. A path that starts on its first step, with no page routing into
+it, skips `entered_via_landing`: the step page fills the cart and the guard
+before submit checks it.
+
 **`cart_created` — cart-API observation.** The step reports what the cart API
 actually returned: the most recent `POST /api/v1/carts/` response's `status`, an
 `ok` flag, `line_count` when the response body exposes lines, `response_count`,
@@ -1780,7 +1875,7 @@ deciding what to do next, it classifies what the attempt did to the store:
 
 | Classification | What it means | What the runner does |
 |---|---|---|
-| `not_created` | The path failed before the checkout was submitted (including the runner's own named refusals: `cart_entry_unresolved`, `cart_entry_control_missing`, `cart_entry_no_navigation`, `cart_empty_before_submit`), or the platform rejected every order create it saw. Nothing reached the store. | Re-runs the path once, if the creation budget has a slot no still-unrun planned path needs. This is the bounded retry for a transient miss; the re-run decides the assertion. |
+| `not_created` | The path failed before the checkout was submitted (including the runner's own named refusals: `cart_entry_unresolved`, `cart_entry_control_missing`, `cart_entry_no_navigation`, `cart_entry_variant_unfilled`, `cart_empty_before_submit`), or the platform rejected every order create it saw. Nothing reached the store. | Re-runs the path once, if the creation budget has a slot no still-unrun planned path needs. This is the bounded retry for a transient miss; the re-run decides the assertion. |
 | `created` | An order exists and was read back — the failure happened after the purchase (most often a receipt that did not render its line items). | Runs a **read-only recovery pass**: reloads the receipt the order already produced, re-reads the persisted order, and re-checks the buyer-visible receipt surface and the voucher read-back. It clicks nothing, applies nothing, and submits nothing. |
 | `ambiguous` | The submit may have created an order this runner cannot see: a ref id with an unusable read-back, a lost create response, a network-failed create, or a 4xx that follows an earlier 2xx on the same endpoint. | Stops. It never resubmits, and the assertion names the check an operator should run — look for an existing order against the run's QA email or the observed ref id. |
 
@@ -1805,6 +1900,13 @@ is not re-run and its assertion records why under
 re-runs for those paths. A re-run that stops on the budget never becomes the
 deciding result: it proved nothing, so the first attempt's real failure stands.
 
+Every attempt is its own `test_orders[]` entry, because a re-run can place its
+own real order. Each entry carries `plan_id`, the planned path it belongs to,
+and `attempt`, 1 for the first try and 2 for the re-run, so a run with five
+planned paths that each re-ran once holds ten entries for five paths. The
+`qa run` summary prints the three counts apart, for example
+`Test orders: 5 paths, 10 attempts, 0 orders created`.
+
 Recovery may only clear a failure on evidence it actually re-read. If the
 receipt reload's persisted-order read-back fails or never happens, the pass stops
 honestly: the read-back failure is itself a remaining failure, and the receipt

package/docs/runtime-readiness.md

@@ -8,7 +8,7 @@
 
 How a checkout of this repository at one commit becomes a usable installed runtime, and how a consumer decides whether a prepared one is still trustworthy. Everything below is generated from `contracts/runtime-recipe.campaigns-os-node-v1.json`, which is the only authority for these values.
 
-Recipe kind `campaigns-os-node-v1`, revision `1.0.2`, validated by `schemas/campaigns-os-runtime-recipe.v1.schema.json` (`Campaigns OS Runtime Recipe v1`). Supported surface at generation time: `1.55.0`.
+Recipe kind `campaigns-os-node-v1`, revision `1.0.3`, validated by `schemas/campaigns-os-runtime-recipe.v1.schema.json` (`Campaigns OS Runtime Recipe v1`). Supported surface at generation time: `1.59.0`.
 
 ## What this is
 
@@ -81,9 +81,10 @@ Not redundant with the install step. Because install runs with lifecycle scripts
 
 The complete input set, enumerated explicitly rather than globbed. The compiler's configured include globs are NOT the input set: two root modules enter the compilation transitively through imports from the entry module and are emitted, so a fingerprint derived from the globs would cover 36 of the 38 compiled sources and miss one of the larger emitted surfaces. Test fixtures and the package's own tests are not inputs; nothing under them is emitted. A checker resolves the compiler's actual file list and asserts it equals this enumeration, so this list cannot rot silently.
 
-Fingerprint algorithm `sha256`, over 42 enumerated files:
+Fingerprint algorithm `sha256`, over 47 enumerated files:
 
 - `campaign-spec/analytics-vocabulary.ts`
+- `campaign-spec/checkout-flow.ts`
 - `campaign-spec/index.ts`
 - `campaign-spec/normalize.ts`
 - `campaign-spec/package.json`
@@ -91,7 +92,9 @@ Fingerprint algorithm `sha256`, over 42 enumerated files:
 - `campaign-spec/rules/analytics-contract-shape.ts`
 - `campaign-spec/rules/assembly-hints-shape.ts`
 - `campaign-spec/rules/campaign-metadata.ts`
+- `campaign-spec/rules/checkout-forward-target.ts`
 - `campaign-spec/rules/checkout-has-success-url.ts`
+- `campaign-spec/rules/checkout-step-reaches-checkout.ts`
 - `campaign-spec/rules/cycle-detection.ts`
 - `campaign-spec/rules/design-source-shape.ts`
 - `campaign-spec/rules/downsell-without-upsell.ts`
@@ -102,9 +105,11 @@ Fingerprint algorithm `sha256`, over 42 enumerated files:
 - `campaign-spec/rules/funnel-weight-sum.ts`
 - `campaign-spec/rules/index.ts`
 - `campaign-spec/rules/offer-ref-integrity.ts`
+- `campaign-spec/rules/one-checkout-per-path.ts`
 - `campaign-spec/rules/package-pricing-sanity.ts`
 - `campaign-spec/rules/page-count.ts`
 - `campaign-spec/rules/page-id-uniqueness.ts`
+- `campaign-spec/rules/pre-payment-forward-target.ts`
 - `campaign-spec/rules/promo-code-input-validation.ts`
 - `campaign-spec/rules/promo-codes-shape.ts`
 - `campaign-spec/rules/route-field-ignored-for-page-type.ts`
@@ -132,7 +137,7 @@ The output directory is a build product. It is untracked and git-ignored, no com
 
 Directory `campaign-spec/dist`. Committed: `false`. Type entry `campaign-spec/dist/index.d.ts`.
 
-Expected inventory is derived, never listed twice. For every enumerated input under module_source_root whose path ends in .ts, the build is expected to emit campaign-spec/dist/<path relative to module_source_root, with .ts replaced> once per entry in emitted_extensions. The expected inventory is exactly that set: nothing missing, nothing extra. Emitted extensions: `.js`, `.d.ts`. At this revision that derivation yields 76 files.
+Expected inventory is derived, never listed twice. For every enumerated input under module_source_root whose path ends in .ts, the build is expected to emit campaign-spec/dist/<path relative to module_source_root, with .ts replaced> once per entry in emitted_extensions. The expected inventory is exactly that set: nothing missing, nothing extra. Emitted extensions: `.js`, `.d.ts`. At this revision that derivation yields 86 files.
 
 ### Mandatory checks