@nextcommerce/campaigns-os 1.43.1 → 1.46.0

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

@@ -1,5 +1,13 @@
 # QA And Test Orders
 
+For packet-based partial builds, QA honors the Assembly Report's recorded
+`stages.prepare_build.declared_out_of_scope` declarations together with the
+packet's skip mappings. Unbuilt declared pages emit `skipped` evidence with
+reason `out_of_build_scope`; HTTP, browser and commercial checks do not request
+those routes, and entry URLs come from the remaining pages. A materialized
+stock page rejoins QA. Missing in-scope pages still fail normally. A raw skip
+mapping without a recorded declaration does not suppress checks.
+
 The public v0 QA runner is Node/npm-based and does not require access to a private runtime repo.
 
 > **Commerce QA requires network; it cannot run in a no-outbound sandbox.** The SDK, product images, fonts, the Netlify preview, and the Playwright typed-card test order all need outbound network. A build environment without it can only validate markup/build/CSS — the commerce runtime and the typed-card test order (the Campaigns OS control) must be deferred to a deployed preview. Always run the QA runner against a `--base-url` preview/production origin (e.g. `npm run campaigns-os -- qa run --packet campaign-runtime.build.json --base-url https://deploy-preview-7--your-site.netlify.app/ --browser --test-order common`); never report commerce-runtime QA as passed from an offline build.
@@ -238,12 +246,18 @@ before QA with the relevant gate ID:
 ```bash
 campaigns-os checkpoint waive \
   --packet campaign-runtime.build.json \
-  --gate <page_kit.store_profile|page_kit.sdk_version|polish.hidden_eager_media|built_output.upsell_selector_scope> \
+  --gate <page_kit.store_profile|page_kit.sdk_version|polish.hidden_eager_media|built_output.upsell_selector_scope|source_html.producer_provenance> \
+  [--page <page_id>] \
   --reason "<why>" \
   --waived-by "<named human>" \
   --review-condition "<specific re-evaluation trigger>"
 ```
 
+`--page` is required for `source_html.producer_provenance`, which is waived one
+Figma-typed page at a time (see the
+[Design Source Package](./design-source-package.md) hand-written HTML route),
+and refused for the other gates.
+
 Legacy source/theme/QA waiver commands and artifact lanes remain in place until
 those gates are registered. Store Profile evidence includes only the governed
 nine-field matrix plus status, normalized slug, relative target path,
@@ -424,7 +438,8 @@ work that lands with the receiver's connection contract. This section
 documents the semantics of the stamps the receiver already applies.
 
 Add `--browser --test-order common` for the normal proof pass: first-party
-Playwright browser checks plus the default typed-card order sample. If the
+Playwright browser checks plus the default `common` typed-card orders
+(described under "Test Orders" below). If the
 browser binary is missing, the CLI will prompt you to run
 `npm run qa:install-browser`:
 
@@ -444,6 +459,30 @@ machine-checkable `agentContract.qaStructure` selectors in the commerce surface
 catalog. If the family contract is silent, the assertion returns
 `manual_review`, not `pass`; if declared required structure is missing, it
 soft-fails with warning severity so the verdict becomes `ready_with_exceptions`.
+The checkout wrapper and page composition are source-owned, so QA checks what
+the checkout does rather than family class names. Family shell is a fixed list:
+`.checkout-wrapper`, `.checkout-layout__left`, `.checkout-layout__right`,
+`.checkout__layout`, `.checkout__column--left`, `.checkout__column--right` and
+the family include's `[data-next-component="shipping-field-row"]` marker. When
+family shell is all that is missing, the row is `warn` if the checkout also
+passes three behaviour checks: a `<form data-next-checkout="form">` exists;
+`email`, `fname`, `lname`, `country`, `address1`, `city`, `province` and
+`postal` are each an input, select or textarea carrying that
+`data-next-checkout-field` inside the form, not a `type="hidden"` input or a
+disabled control (visibility is not required, so a field hidden until a country
+is chosen still counts); and a cart-summary total
+(`[data-next-display="cart.total"]` or
+`[data-next-cart-summary] .order-totals__value--total`) is visible with text.
+If any behaviour check fails, or no checkout form is found, the row stays
+`fail`. Any other missing selector is always `fail`: the SDK selectors
+(`[data-next-checkout="form"]`, `[os-checkout-payment]`,
+`[data-next-cart-summary]`, `[data-next-bundle-slots-for]`) and any class the
+list does not name, such as a hosted payment field class. `evidence.behaviour` records
+the three checks and each `evidence.checks[]` entry carries `kind`
+(`family_shell` or `sdk_wiring`).
+The upsell and checkout bundle price checks count the SDK's
+`[data-next-bundle-display*='price']` alongside the contract's price rows; a
+hidden, zero-size or empty bundle-display node does not count.
 Promoted template families must also have
 `contracts/template-brand-contract.<family>.v0.json`; QA emits a blocker if the
 selected family is missing its brand/residue/pricing contract instead of
@@ -793,9 +832,12 @@ retire that guard once #36 ships and `cartLines` is populated.
 Analytics correctness has two deliberately separate evidence phases in one QA
 run:
 
-1. The campaign-root visit inventories declared providers, containers, pixels,
-   and other observable tags. It does not prove or disprove Purchase, even if a
-   stray Purchase-shaped event appears there.
+1. The inventory visit inventories declared providers, containers, pixels,
+   and other observable tags on one page: the campaign root, or a built entry
+   when the root cannot be captured (see
+   [Which page the inventory captures](#which-page-the-inventory-captures)).
+   It does not prove or disprove Purchase, even if a stray Purchase-shaped
+   event appears there.
 2. The existing canonical typed-card order run supplies Purchase evidence. For
    each planned order, the topology classifier must recognize the final URL as
    that plan's receipt, then the runner waits the full `--analytics-settle`
@@ -839,6 +881,98 @@ analytics block to gate. The SDK's own data layer is a separate, always-on
 reading taken on the same order — see [Purchase data layer](#purchase-data-layer-dl_purchase)
 under Test Orders.
 
+### Which page the inventory captures
+
+The inventory starts at the campaign root composed from the campaign identity
+(`public_route_slug` plus `route_root`). A partial build (a topology with a
+partial build scope, or pages excluded from the build) may have no page there:
+the root is then whatever the host answers, such as a directory index or a
+generic fallback. So the root is visited only when it is in scope. On a full
+build it always is; on a partial build it is in scope only when a built,
+in-scope topology page is served at the root. When the root is out of scope,
+answers non-2xx, or fails to load (a timeout, a refused connection), the leg
+tries each funnel's built entry in turn: the first in-scope page on a partial
+build (the same entry the partial-scope planner selects), otherwise the first
+entry-like page. It captures the first page that answers 2xx. A response with no
+HTTP status counts as an answer. A closed page or a disconnected browser is not
+a per-page failure: it is the `analytics-correctness:runner` blocker.
+
+`analytics-correctness:capture` records the page it used:
+`evidence.capture_page` holds `url` (the URL requested, query redacted),
+`source` (`campaign_root` or `built_entry`), `page_id`, `funnel_id` and
+`http_status`. `evidence.final_url` is the page URL after redirects and
+settling. When a built entry was used, `evidence.root_fallback` says why the
+root was not: `reason` is `out_of_built_scope`, `non_2xx` (with the root's
+`http_status`), or `navigation_error` (with its `error_code`).
+
+When no page is captured, the leg emits `analytics-correctness:capture` alone,
+with no per-vendor assertion measured against an empty page. There are two
+outcomes, and `evidence.attempts` lists each page tried:
+
+| `evidence.reason` | When | Result |
+|---|---|---|
+| `no_in_scope_page_captured` | The root is out of the built scope and no built entry other than the root is left to try, so nothing was loaded | `skipped`: there is no page whose tags could be measured |
+| `no_capture_page_answered` | At least one page was tried, and every one answered non-2xx or failed to load | `FAIL`/`BLOCKER`: the declared analytics went unmeasured, so a later passing order cannot report the run ready |
+
+Step routing is path-based in every certified family. Page-kit builds each
+page to its own `<route>/index.html`, and QA strips the query string from a
+CampaignSpec route. So `/campaign`, `/campaign/` and `/campaign/index.html` are
+one page, and a query string does not name a different page. A topology page
+whose own URL declares a query (for example `/campaign/?step=checkout`) is
+still never merged into the root on its path alone. Unless its query is
+exactly the root's own (parameter order aside), it does not put the root in
+scope, it is captured as its own entry, and its `capture_page` carries
+`query_routed: true`, since the redacted URL alone would read as the root. An
+entry on a different path is never marked `query_routed`, whatever query it
+carries. A URL with no query of its own names the page at that path whatever
+query the other URL carries.
+
+### Local-serve review (`manual_review`)
+
+A local proof run renders the development environment on purpose (see
+[Local proof mode](#local-proof-mode-deploytarget-local-serve)), and the
+starter templates gate every vendor loader out of that render. A pixel that
+did not fire there is the render's design, not a campaign defect. So on a
+local-serve run, a failing fire-dependent check becomes `manual_review` at
+`warn` instead of a blocker. The fire-dependent checks are
+`analytics-correctness:tag:*`, `analytics-correctness:oob:*` and
+`analytics-correctness:purchase-fires`.
+
+The run qualifies only when all of these hold:
+
+- the packet's `deploy.target` is `local-serve`;
+- the analytics capture target (else the base URL) is a loopback URL;
+- the Assembly Report records the development render:
+  `stages.assembly.evidence.build_environment` is `development`. A production
+  build served on localhost, or a build whose environment was never recorded,
+  keeps its blockers.
+
+Each failing check is then downgraded only when the page it measured is on
+record as loopback. For `tag:*` and `oob:*`, the check's own URL, the passing
+capture's `capture_page.url` and its `final_url` must all be loopback, so a
+built-entry fallback on a remote host, or a localhost root that redirected to
+a production host, keeps the blocker. For `purchase-fires`, there must be at
+least one judged receipt, and every one needs a loopback `receipt_url` and
+`receipt_document_url` (the page URL read after the receipt analytics
+settled). A missing or unparseable URL keeps the blocker.
+
+What always stays a blocker:
+
+- `analytics-correctness:data-layer-purchase:<path>`. It counts the SDK's own
+  `dl_purchase`, which the development render still pushes, so a miss on
+  localhost can be a real defect.
+- A capture or runner failure: `analytics-correctness:runner`, a check whose
+  evidence carries an `error_code`, and a `purchase-fires` reading whose
+  `capture_error_plan_ids` is missing or not empty. The environment explains a
+  silent pixel, not an unmeasured one.
+
+A downgraded check keeps its evidence and adds `reason:
+local_serve_development_render`, `local_serve_status: fail`, the recorded
+`build_environment`, the recorded `production_parity` (`status:
+not_recorded` when none is on the report, with a note unless it passed), and a
+`follow_up`: re-run `qa run` against the PR preview (a production render) with
+`--base-url <preview-url>`. That run gates these checks.
+
 ## Analytics parity (dataLayer / GTM)
 
 The analytics-parity leg proves the live **dataLayer event stream + GTM/pixel
@@ -858,14 +992,22 @@ npm run campaigns-os -- qa run \
 ```
 
 This receipt-to-receipt parity example names `--analytics-candidate`
-explicitly. When that flag is omitted, the candidate is the campaign identity's
-composed root (`public_route_slug` plus `route_root`), not the raw
-`--base-url` value.
+explicitly, and that URL is captured as given. When that flag is omitted, the
+candidate is chosen the same way as the correctness inventory (see
+[Which page the inventory captures](#which-page-the-inventory-captures)): the
+campaign identity's composed root (`public_route_slug` plus `route_root`), not
+the raw `--base-url` value, when it is in scope and answers 2xx, else the first
+built entry that does. `analytics-parity:capture` then records the same
+`capture_page` and `root_fallback` evidence. The candidate is captured before
+the baseline, and when no candidate page is captured the leg emits
+`analytics-parity:capture` alone, without loading the baseline:
+`no_in_scope_page_captured` (skipped) or `no_capture_page_answered`
+(`FAIL`/`BLOCKER`).
 
 | Flag | Meaning |
 |---|---|
 | `--analytics-baseline <url>` | Legacy funnel URL to capture as the parity baseline (enables the leg) |
-| `--analytics-candidate <url>` | Migrated URL to capture; defaults to the identity-composed campaign root |
+| `--analytics-candidate <url>` | Migrated URL to capture as given; defaults to the identity-composed campaign root, or the first built entry when that root is out of the built scope or does not answer |
 | `--analytics-hosts a,b` | Extra host substrings to treat as analytics tag-fires (Everflow is built in) |
 | `--analytics-settle <ms>` | Wait after analytics page loads and after a recognized typed-order receipt for async tags to fire (default 5000); receipt settling must fit inside the order deadline |
 
@@ -996,13 +1138,64 @@ npm run campaigns-os -- qa run \
   --test-order common
 ```
 
-The default mode is **`common`** (also what bare `--test-order` runs): at most
-four shapes from the selected checkout's declared topology — the checkout
-baseline, first-offer `accept` and `decline` when `expected_next_url` reaches an
-upsell/downsell, and the shortest declared path that actually reaches a
-receipt/thank-you page. The receipt path is deduplicated when it is already
-`accept` or `decline`; Campaigns OS never invents a receipt path from offer
-count alone. This is the everyday QA sample.
+The default mode is **`common`** (also what bare `--test-order` runs). It
+starts from the selected checkout's declared topology:
+
+- When every actual terminal path (the `full` set, checkout baseline included)
+  fits under the flood cap (`--max-test-orders`, default `6`), `common` runs
+  them all. The run says so on stderr, and on a funnel with offer pages the
+  coverage row below records
+  `order_path_depth_effective: "full"` with `order_path_depth_reason:
+  "under_cap"`.
+- Above the cap, or when the topology cannot be walked exhaustively, `common`
+  runs the sample: the checkout baseline, first-offer `accept` and `decline`
+  when `expected_next_url` reaches an upsell/downsell, and the shortest
+  declared path that actually reaches a receipt/thank-you page (deduplicated
+  when it is already `accept` or `decline`; Campaigns OS never invents a
+  receipt path from offer count alone). It then adds, for each offer or
+  downsell page whose decline no planned path clicks yet, the shortest actual
+  terminal path that clicks it, until the plan reaches the cap. Pages still
+  left out are named on stderr and in the coverage row. The sample itself is
+  never trimmed, so a `--max-test-orders` below it is refused before launch as
+  before.
+
+A page counts as covered only when a path clicks its **decline** control.
+Reaching a page, or clicking only its accept, does not count: a broken decline
+link strands the shopper even when accept works.
+
+Every browser test-order run whose funnels include offer pages records
+`browser-test-order:upsell-action-coverage`, read from the clicks the runner
+actually made in orders it placed, not from the plan. It lists the offer pages
+of every funnel in the run, including funnels the orders do not drive, and a
+click credits only the funnel whose order made it, never another funnel's page
+at the same URL. The row is conservative: it is `pass` or `warn` only when
+coverage is certain, and `manual_review` in every other case.
+
+Coverage is certain when all of these hold: at least one order was placed;
+every funnel lists its pages; every page is either a known non-offer type
+(checkout, landing, thank-you and the like) or an upsell/downsell page with its
+own absolute http(s) URL that no other page shares; every planned order belongs
+to exactly one funnel (its checkout is that funnel's checkout and it was
+planned over that funnel's page list); and every click an order recorded lands
+on a declared offer page of that order's own funnel. Then the row is `warn`
+(severity `warn`) naming each page whose decline no order of its funnel
+clicked, and each funnel no order ran through, or `pass` when every page's
+decline was clicked.
+
+Otherwise the row is `manual_review` (severity `warn`) naming the pages not
+proved clicked through, with `evidence.reason`: `test_orders_off` for a
+`--test-order off` run, `no_order_recorded` when no order was placed (an
+attempt that failed before an order reference counts as none), `no_topology`
+when no funnel topology reached the check, or `not_assessable` for the rest.
+`evidence.not_assessable[]` names each page that cannot be matched to a click,
+with a reason: `no_url` or `unresolvable_url`, `shared_url` (the URL belongs to
+another page too), `unknown_page_type` (neither an offer type nor a known
+non-offer type), or `no_pages` (a funnel with no page list).
+`evidence.uncertainty[]` lists the run-level reasons: `unattributed_plan` (a
+plan that does not match exactly one funnel's checkout and page list),
+`unattributed_click` (a click with no usable URL, or from such a plan's order)
+and `undeclared_click` (an order clicked a page its funnel does not declare).
+`evidence.pages[]` gives `accept_clicked` / `decline_clicked` per page.
 
 Other modes: `checkout` (base order redirect only), `accept`/`decline` (click the
 rendered control on the first upsell page), `both` (two fresh orders for those
@@ -1436,8 +1629,11 @@ npm run campaigns-os -- qa run \
 ```
 
 `--max-test-orders` (default `6`) is an **accidental-flood guard, not a permission
-gate**. A single checkout's `common` sample always stays under it, though tier
-expansion can exceed it. If `full` expands past the cap, the command stops before
+gate**. A single checkout's `common` plan always keeps its checkout,
+first-offer accept/decline and shortest-receipt sample. If that sample alone
+exceeds the cap (a `--max-test-orders` below it), the run is refused before
+browser launch, as before. Otherwise the added decline paths stop at the cap.
+Tier expansion can exceed it. If `full` expands past the cap, the command stops before
 browser launch, prints the planned count, lists the planned paths (up to 40 ids;
 past that the remainder is counted, never cut silently, and `--select-package
 <ref[:qty]>` lists one tier's paths), and names the exact `--max-test-orders <count>` raise. For example, a linear three-offer graph has
@@ -1618,8 +1814,9 @@ use the declared topology instead of a single happy path:
 
 1. Checkout-only with the base cart.
 2. Checkout-only with the base cart plus bump when the bump is in scope.
-3. Base cart through the checkout/first-action sample plus the shortest real
-   receipt path (`--test-order common` covers up to four deduplicated shapes).
+3. Base cart through `--test-order common`: every actual terminal path when
+   they fit under the cap, otherwise the checkout/first-action sample, the
+   shortest real receipt path and one decline path per uncovered offer page.
 4. Base plus bump cart through the same sample matrix when bump behavior is
    launch-relevant.
 5. Use `full` when you want every actual terminal path, raising the flood cap to
@@ -1690,6 +1887,19 @@ review. Nested Google Maps/payment keys and inert HTML do not count as campaign
 credentials. This small static grammar deliberately leaves many real pages
 unknown; a literal inside arbitrary code is not proof of effective configuration.
 
+A page script that does not parse is not treated as dynamic. The browser throws
+a `SyntaxError` on it and nothing in it runs, so the binding reads its
+declarations as unavailable (`script_unavailable_or_limit`) and QA adds a
+separate `script-parse:<page_id>` blocker in the same `api-metadata` family.
+Its `actual` names each script by path (inline scripts as `inline script`)
+with the line and column, and its evidence lists a fixed diagnostic category
+per script, never text from the script. Classic scripts are parsed as scripts
+and `type="module"` scripts as modules, with the type stripped of surrounding
+ASCII whitespace and compared case-insensitively as the browser does; classic
+`nomodule` scripts are not fetched or parsed (a module script ignores
+`nomodule` and is parsed), and script srcs resolve against the page's first `<base href>`. Doctor runs the same parse over the built output before deploy; see
+`built_output.script_syntax` in [the Build Packet doc](build-packet.md).
+
 External executable scripts other than the recognized jsDelivr Campaign Cart
 loader/index are inspected only on the page's origin. Each page admits at most
 6 such references; each run fetches at most 24 distinct URLs (deduplicated),

package/docs/release-ledger-authoring-guide.md

@@ -118,7 +118,8 @@ be recorded without the bytes actually moving somewhere.
 ### Fixes that touch only policy-ignored paths
 
 A fix living entirely in paths the policy ignores — `src/` other than
-`src/cli.mjs`, `scripts/`, tests and fixtures — carries a same-surface CHANGELOG
+`src/cli.mjs`, `src/agent/` and `src/doctor/`, `scripts/`, tests and
+fixtures — carries a same-surface CHANGELOG
 section (`X.Y.Z+agent.N`) and **no ledger entry**. There is nothing for an entry
 to claim: every change item must map to a classified changed path in the range,
 and an ignored path is never classified, so an entry written for such a PR is
@@ -127,9 +128,10 @@ path-less item fails the same way, because no classified change of its class
 exists in the range. The ignore list and its stated reasons are in
 [`contracts/agent-relevant-change-policy.v1.json`](../contracts/agent-relevant-change-policy.v1.json).
 
-The dividing line inside `src/` is `src/cli.mjs`: an explicit rule classifies it
-as `cli_surface`, so any change to it is agent-relevant and owes an entry, even
-when the behaviour change originates in a helper module beside it.
+The classified paths inside `src/` are `src/cli.mjs`, `src/agent/` and
+`src/doctor/`: an explicit rule classifies each as `cli_surface`, so any change
+there is agent-relevant and owes an entry, even when the behaviour change
+originates in a helper module beside it.
 
 ### Amendments
 
@@ -144,7 +146,7 @@ incomplete, append a correction:
   "amends": "RL-0007",
   "amendment_reason": "RL-0007 was recorded as compatible; it removed a documented guarantee.",
   "surface_version": null,
-  "changelog_section": "1.15.0+agent.1",
+  "changelog_section": "1.16.0+agent.1",
   "compatibility": "breaking",
   "migration": "Stop relying on the removed guarantee; see docs/build-packet.md.",
   "agent_impact": "Treat the 1.15.0 packet doc change as breaking, not compatible.",
@@ -152,6 +154,10 @@ incomplete, append a correction:
 }
 ```
 
+The amendment corrects a 1.15.0 entry, but its own section is a new one at the
+very top of `CHANGELOG.md`, numbered on the release on top when it is written
+(`1.16.0` here). It is never inserted under the older release it corrects.
+
 An amendment is the only entry kind whose change items may map to no changed
 path in its own range, because it corrects meaning rather than moving bytes.
 
@@ -169,13 +175,25 @@ entry currently holding the link, may re-link a section; any other second link
 still fails the one-to-one rule. Say in `amendment_reason` what changed in the
 section and why.
 
+This works only for a section still in the live `CHANGELOG.md`. An archived
+section cannot be corrected in place: archive files are never edited, and each
+is pinned by its SHA-256 in `baseline_floor.archives`, so any change to one
+fails the gate. Correct archived history with a new live amendment entry that
+links its own new section at the top of `CHANGELOG.md`, and say in
+`amendment_reason` what is wrong in the archived section.
+
 `scripts/check-changelog-structure.mjs` (part of `npm run check`) refuses the
 marker lines outright, in `CHANGELOG.md` and under `docs/`, and also holds the
 section layout: identifiers unique, `+agent.N` sections in one run directly
 above their release with N descending (newest first), and every ledger
-`changelog_section` naming a section that exists. Insert a new `+agent.N`
-section at the top of its release's run, not directly above the release
-heading.
+`changelog_section` naming a section that exists.
+
+A new section always goes at the very top of `CHANGELOG.md`: either a new
+release, or a `+agent.N` section numbered on the current top release (one above
+its highest N, or `+agent.1` if it has none). Never add a `+agent.N` section
+under an older release. Given `--base`, both `check-changelog-structure.mjs` and
+the release-ledger gate refuse any new section that sits below a section base
+already had.
 
 ## Running the gate
 
@@ -272,3 +290,47 @@ a quiet raise.
 
 Raising a limit is a reviewed policy change: advance `limits_version`, and the
 change owes its own ledger entry like anything else.
+
+## Rotating the baseline
+
+When the live ledger and changelog approach a bound, rotate them at a reviewed
+cut instead of raising a limit. The first rotation (2026-09-30, `RL-0190`)
+moved `RL-0001` through `RL-0124`; the ledger's `baseline_floor` records it.
+
+1. Pick the cut: the last entry to archive. Everything up to it moves, and so
+   does the changelog from the first section those entries link down to the end
+   of the file, including sections no entry links. If a kept entry amends an
+   archived one, or links a section in that tail, move the cut earlier until the
+   pair is on one side. Never later.
+2. Run the rotation through `rotateLedger` in `scripts/orientation-contract.mjs`
+   with a new dated pair under `contracts/archive/`, e.g.
+   `release-ledger.<date>.json` and `CHANGELOG.<date>.md`. It writes the entries
+   byte-for-byte (original `sequence` and hashes kept) and the changelog tail
+   verbatim, appends the pair and its SHA-256 to `baseline_floor.archives`, and
+   moves `last_archived_id`, `last_archived_sequence` and `first_kept_id`. It
+   refuses a cut that splits a pair.
+3. Never edit an existing archive file, and never reuse a date: each rotation
+   adds a new pair. Add both new files to `named` in
+   `contracts/supported-surface.json`.
+4. Record the rotation as its own entry, named in `baseline_floor.rotation_entry`,
+   with a change item for each new archive file and a CHANGELOG section of its
+   own. Its `agent_impact` tells consumers which baseline is now too old.
+
+The gate accepts a base entry missing from the live ledger only when the head
+floor covers it, the new archive holds it canonical-JSON-identical, and the floor
+moved with a new rotation entry in the same range. Any other deletion, an
+archive copy that differs from base, a floor that moves without a rotation
+entry, a floor that moves back or is rewritten, an edited archive file, and a
+cut that archives an entry while an entry that was live at base stays live and
+amends it (the same refusal `rotateLedger` gives) all fail. A new entry added
+after the rotation may still amend an archived entry, linking its own section
+in the live changelog: that is how archived history is corrected. The live changelog and each archive changelog must each be well-formed on
+their own, a section id may appear in only one of them, a section present
+at base must still be in one of them, and the live changelog followed by the
+archives, newest rotation first, must read as the base's sections in order
+with new sections only at the top of the live file. So every live section is
+newer than every archived one, and an archived section never moves back
+(`check-changelog-structure.mjs --base` and the `--base` release-ledger gate).
+The archive files are not mandatory
+orientation reads and are not measured; a consumer whose reviewed baseline is older than the floor refuses
+with `baseline_below_floor` and adopts a newer reviewed baseline.

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.43.1`.
+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.46.0`.
 
 ## What this is
 

package/docs/sdk-storage-compatibility.md

@@ -8,7 +8,7 @@ npx --no-install campaigns-os sdk storage-check --target . --target-sdk 0.4.38 -
 
 Omit `--json` for the concise human report. Exit 0 means source-compatible; exit 2 means incompatible or unknown; invalid arguments or manifests exit 1. No merchant files or pins are rewritten. This is independent of doctor's built HTML markup check.
 
-The manifest is generated and owned by Campaign Cart, from its storage registry. The scanner has no independent SDK key list and fetches no remote code. Supply the generated `storage-migrations.v1.json` from the SDK contract change (campaign-cart #102); until that change is published, this command does **not** imply a released SDK tag contains that file. The report records the full file SHA-256, SDK version, supported target range, registry/extractor/input digest, and Git provenance. When the supplied bytes equal their repository HEAD blob, provenance is `verified-git-blob` with commit and repository path. Proposed, modified, or copied manifests are labeled `unverified-local-file`; the label never certifies a release. Review/pin SDK provenance separately before acting on findings. Targets outside the manifest's supported SDK range report unknown.
+The manifest is generated and owned by Campaign Cart, from its storage registry. The scanner has no independent SDK key list and fetches no remote code. Supply `docs/compatibility/storage-migrations.v1.json` from an unmodified checkout of a Campaign Cart release tag, v0.4.40 or later. The report records the full file SHA-256, SDK version, supported target range, registry/extractor/input digest, and Git provenance. When the supplied bytes equal their repository HEAD blob, provenance is `verified-git-blob` with commit and repository path. Proposed, modified, or copied manifests are labeled `unverified-local-file`; the label never certifies a release. Review/pin SDK provenance separately before acting on findings. Targets outside the manifest's supported SDK range report unknown.
 
 `--target` must name the Git root. `--scope` is mandatory: comma-separated literal repository-relative directory/file paths; use `.` only when the complete repository is intended. Add shared JavaScript directories explicitly. `--exclude` uses the same syntax and records explicit exclusions. Archives receive no implicit exemption. Only Git-tracked `.html`, `.htm`, `.js`, `.mjs`, and `.cjs` files in the selected scope are scanned, using current working-tree bytes and per-file digests; untracked files and built dependencies are outside this evidence. A selected HTML page's local script outside the selected files reports unknown. Relative scripts affected by an HTML `<base href>` also report unknown; review their actual dependency paths. Remote SDK and third-party scripts are not fetched or analyzed.
 

package/docs/skills-revision.md

@@ -16,7 +16,7 @@ that the copy on disk moved.
 `skills.json` carries one top-level field:
 
 ```json
-"bundle_revision": "1.43.1+skills.1"
+"bundle_revision": "1.46.0+skills.1"
 ```
 
 The spelling is `<package version>+skills.<n>`:
@@ -25,7 +25,7 @@ The spelling is `<package version>+skills.<n>`:
   skills ship with (`check-skill-versions.mjs` fails if the two disagree);
 - `<n>` is a plain counter, not a semver component. It says "this is the *n*th
   skill-text revision published against that package version" and it **resets
-  with the prefix**. `1.43.1+skills.1` is therefore ahead of `1.40.0+skills.7`.
+  with the prefix**. `1.46.0+skills.1` is therefore ahead of `1.40.0+skills.7`.
 
 It is one identity for the bundle as a whole, on purpose. Per-skill versions
 still exist and still gate per-skill changes, but an agent that loaded one skill
@@ -37,7 +37,7 @@ The first body line of every bundled `SKILL.md`, immediately after the
 frontmatter, is exactly:
 
 ```
-Bundle revision: 1.43.1+skills.1
+Bundle revision: 1.46.0+skills.1
 ```
 
 followed by a short paragraph telling the agent to run the check below at the
@@ -48,7 +48,7 @@ text the agent is actually reading, not from a file it would have to go and open
 ## The check
 
 ```bash
-npx --no-install campaigns-os tooling status --skills-revision 1.43.1+skills.1
+npx --no-install campaigns-os tooling status --skills-revision 1.46.0+skills.1
 ```
 
 The value is compared against the bundle revision of the **CLI the command runs
@@ -90,20 +90,20 @@ reports the choice as `skills.scope` (`requested`, `installed_platforms`, or
 "revision_check": "match",
 "skills_revision": {
   "status": "match",
-  "requested": "1.43.1+skills.1",
+  "requested": "1.46.0+skills.1",
   "spelling": "bundle",
-  "on_disk": "1.43.1+skills.1",
+  "on_disk": "1.46.0+skills.1",
   "on_disk_skill": null,
-  "message": "match (1.43.1+skills.1)"
+  "message": "match (1.46.0+skills.1)"
 }
 ```
 
 The text view prints one named line, as a header above the rest of the status:
 
 ```
-Skills revision: match (1.43.1+skills.1)
-Skills revision: mismatch: loaded 1.39.0+skills.1, on disk 1.43.1+skills.1 — start a fresh session
-Skills revision: unchecked (on disk 1.43.1+skills.1)
+Skills revision: match (1.46.0+skills.1)
+Skills revision: mismatch: loaded 1.39.0+skills.1, on disk 1.46.0+skills.1 — start a fresh session
+Skills revision: unchecked (on disk 1.46.0+skills.1)
 ```
 
 `unchecked` is the state when the flag is absent. It is not an error — an

package/docs/supported-surface.md

@@ -14,7 +14,7 @@ implementation detail, however stable it looks.
 | Surface | Contract | Change discipline |
 |---|---|---|
 | `schemas/*.schema.json` (all of them) | The portable contract catalog: CampaignSpec, Design Source Package, Build Packet, Build Context, Assembly Report, Doctor Output, sidecar-bundle conformance, Run Record, Workflow Finding, Build Brief, Source-HTML Manifest, Tooling Orientation, Release Ledger, QA Verdict, the QA Verdict sidecar projection, Runtime Recipe, and the legacy-migration inventory/plan/receipt trio. | Hashed. Any content change requires updating the recorded hash **and** bumping `surface_version` in the same PR. A shape change that alters meaning gets a new schema-version const — one version identifier must never cover two shapes (the 2026-08 assembly-report drift is the incident this rule encodes). Additions to an open `v0` schema are expected and consumers must tolerate unknown fields; the security-sensitive legacy-migration schemas are closed, so additions there require a new lineage. 1.28.0 (RL entry `surface_version: 1.28.0`, breaking) removed the two required Build Packet booleans `qa.test_orders_allowed` and `qa.sandbox_test_card_confirmed` (nothing read them; test orders run from `--test-order <mode>` alone), added `local-serve` to the `deploy.target` enum, and added the optional `remit_result` / `remit_base_kind` fields to the Run Record. 1.30.0 (additive) added the optional `data_layer` record to the QA Verdict's `test_orders[]` entries — the order's `dl_purchase` reading (#325). 1.33.0 (additive) added the optional `qa_verdict_publish` block to the Run Record — which verdict was posted to the QA portal, by `qa run` or `qa publish`, and what the portal answered, in the `remit_result` vocabulary (#328). |
-| CLI commands: `start`, `prepare-build`, `build`, `polish`, `checkpoint`, `page-kit`, `spec`, `doctor`, `bundle`, `next`, `theme`, `tooling`, `install-skills`, `install-agent-context`, `validate-assembly-report`, `telemetry`, `standardize`, `qa`, `findings`, `run-record`, `run`, `sdk`, `demo`, `login`, `logout` | Scriptable entry points. The founding list (1.0.0) was the argv surface Campaigns Agent's remit fixture pins; 1.25.0 adds the partner entry path the public guides instruct — `install-skills` (skill install), `tooling status` (preflight), `next --packet` (the runtime cursor) — plus `theme`, `install-agent-context`, `validate-assembly-report`, and `telemetry`, since consent is part of the partner contract. `validate-build-packet`, formerly an undocumented and unsupported alias of `doctor`, was removed in 1.25.0+agent.7 (RL-0036) and now gets the unknown-command error; use `doctor`. `standardization-report`, a supported but redundant second spelling of `standardize` — same flags, same output, same exit codes — was removed in 1.27.0 and now gets the same unknown-command error; use `standardize`. Removing a supported command is a breaking change and is why that release moved the minor. `bundle check` validates the canonical JSON readback set and makes QA required only under `--require-qa`. `polish capture` owns page-load evidence production. `checkpoint waive` currently accepts four registered gates: `page_kit.store_profile`, `page_kit.sdk_version`, `polish.hidden_eager_media`, and `built_output.upsell_selector_scope`. `page-kit sync` (added in 1.29.0) writes the CampaignSpec's Store Profile fields and SDK pin into the target's `_data/campaigns.json` entry — the repair the first two gates name — and is the only `page-kit` subcommand. `spec derive` (added in 1.31.0) is the reverse write for the repo-derived field class (#432): the target's SDK pin, page routes and analytics ids into the packet's local CampaignSpec; it is the only `spec` subcommand, and the `page_kit.sdk_version.repo_newer` advisory names it; its `--write-map` flag (1.33.0+agent.2) also records the derived pin in the saved Map's Build hints field through the proxy Worker, never moving a Map pin backwards. `qa publish` (added in 1.33.0) posts an already-stored verdict to the QA portal without a re-run or an order, refusing a stale `spec_hash` or a verdict its Run Record already records as published (#328). Within Polish, only the broader Source Freshness waiver remains on its existing report lane; theme and QA decisions also retain their existing lanes. | Any change to this list — adding, renaming, or removing a command — bumps `surface_version` in the same PR, and since 1.25.0 `check-supported-surface.mjs --base` enforces that (before, only hashed and named entries owed a bump, so `checkpoint` landed unbumped). Subcommands, registered gates, and flags may grow freely beneath a listed command. Removing a listed command from dispatch fails the gate outright. Do not infer support for an unregistered checkpoint from the top-level command. |
+| CLI commands: `start`, `prepare-build`, `build`, `polish`, `checkpoint`, `page-kit`, `spec`, `doctor`, `bundle`, `next`, `theme`, `tooling`, `install-skills`, `install-agent-context`, `validate-assembly-report`, `telemetry`, `standardize`, `qa`, `findings`, `run-record`, `run`, `sdk`, `demo`, `login`, `logout` | Scriptable entry points. The founding list (1.0.0) was the argv surface Campaigns Agent's remit fixture pins; 1.25.0 adds the partner entry path the public guides instruct — `install-skills` (skill install), `tooling status` (preflight), `next --packet` (the runtime cursor) — plus `theme`, `install-agent-context`, `validate-assembly-report`, and `telemetry`, since consent is part of the partner contract. `validate-build-packet`, formerly an undocumented and unsupported alias of `doctor`, was removed in 1.25.0+agent.7 (RL-0036) and now gets the unknown-command error; use `doctor`. `standardization-report`, a supported but redundant second spelling of `standardize` — same flags, same output, same exit codes — was removed in 1.27.0 and now gets the same unknown-command error; use `standardize`. Removing a supported command is a breaking change and is why that release moved the minor. `bundle check` validates the canonical JSON readback set and makes QA required only under `--require-qa`. `polish capture` owns page-load evidence production. `checkpoint waive` currently accepts five registered gates: `page_kit.store_profile`, `page_kit.sdk_version`, `polish.hidden_eager_media`, `built_output.upsell_selector_scope`, and `source_html.producer_provenance` (per page, with `--page <page_id>`). `page-kit sync` (added in 1.29.0) writes the CampaignSpec's Store Profile fields and SDK pin into the target's `_data/campaigns.json` entry — the repair the first two gates name — and is the only `page-kit` subcommand. `spec derive` (added in 1.31.0) is the reverse write for the repo-derived field class (#432): the target's SDK pin, page routes and analytics ids into the packet's local CampaignSpec; it is the only `spec` subcommand, and the `page_kit.sdk_version.repo_newer` advisory names it; its `--write-map` flag (1.33.0+agent.2) also records the derived pin in the saved Map's Build hints field through the proxy Worker, never moving a Map pin backwards. `qa publish` (added in 1.33.0) posts an already-stored verdict to the QA portal without a re-run or an order, refusing a stale `spec_hash` or a verdict its Run Record already records as published (#328). Within Polish, only the broader Source Freshness waiver remains on its existing report lane; theme and QA decisions also retain their existing lanes. | Any change to this list — adding, renaming, or removing a command — bumps `surface_version` in the same PR, and since 1.25.0 `check-supported-surface.mjs --base` enforces that (before, only hashed and named entries owed a bump, so `checkpoint` landed unbumped). Subcommands, registered gates, and flags may grow freely beneath a listed command. Removing a listed command from dispatch fails the gate outright. Do not infer support for an unregistered checkpoint from the top-level command. |
 | `sdk storage-check` and `docs/sdk-storage-compatibility.md` | Read-only AST compatibility report for explicitly scoped tracked campaign HTML/JS before an SDK bump; consumes the supplied SDK-owned manifest and records its SHA-256 and verified or unverified local Git provenance. Incompatible and unknown findings exit 2; a clean scan is static source evidence only. | Additive supported CLI and named documentation; no automatic merchant integration repair. |
 | `bin/campaigns-os.mjs` (`campaigns-os`) | The CLI entry itself. | Declared in `package.json` `bin`; the gate fails if it disappears. |
 | Package export `./campaign-spec` | The versioned campaign-spec rule registry, consumed as `@nextcommerce/campaigns-os` (pinned by consumers' lockfiles; lockstep policy — ADR-003 in the ops repo). | Behavior-guarded from the consumer side by their contract tests; the export path itself is gated here. |
@@ -24,7 +24,7 @@ implementation detail, however stable it looks.
 | Contract docs: `CONTEXT.md`, `docs/campaigns-os-build-flow.md`, `docs/build-packet.md`, `docs/migration-sidecar-bundle.md`, `docs/design-source-package.md`, `docs/campaign-build-brief.md`, `docs/campaign-standardization-report.md`, `docs/brand-theme-bridge.md`, `docs/qa-and-test-orders.md`, `docs/legacy-migration.md`, `docs/versioning.md`, `docs/workflow-findings-sidecar.md`, this file | Named entry points consumers pin for context. | Content evolves freely; the path must keep existing. |
 | `skills.json` + `skills/` + `skills.sh` | Versioned skill packages and their installer. | Governed by `check-skill-versions.mjs` (parity + bump gate + reserved external names). `skills.json` ships in the npm pack as of surface 1.0.0. As of 1.40.0 the manifest also carries `bundle_revision` (`<package version>+skills.<n>`), one identity for the bundle that every `SKILL.md` states on its first body line and that `campaigns-os tooling status --skills-revision <value>` checks against the bundle on disk; it must advance whenever any bundled skill changes (`--base` mode), and `docs/skills-revision.md` is its prose. |
 | `compatibility.json` | The published compatibility statement. | Named; must keep existing. |
-| Orientation contract: `AGENTS.md`, `CHANGELOG.md`, `contracts/release-ledger.json`, `contracts/agent-relevant-change-policy.v1.json`, `contracts/orientation-limits.v1.json`, `contracts/orientation-reason-codes.v1.json`, `docs/orientation-contract-reference.md`, `docs/release-ledger-authoring-guide.md`, `contracts/fixtures/orientation/canonicalization/v1.json` | The declarative data a consumer reads from Git objects to decide whether a commit is safe to work against, without executing anything from this repository. Schema `campaigns-os-tooling-orientation/v1`; ledger schema `campaigns-os-release-ledger/v1`. The canonicalization fixture gives independent implementations exact ledger and changelog bytes plus their expected SHA-256 digests. Entry point: [`AGENTS.md`](../AGENTS.md). | Named. The ledger is append-only: a correction ships as a new amendment entry, never an edit. `scripts/check-release-ledger.mjs` enforces the two-way gate; `docs/orientation-contract-reference.md` and the canonicalization fixture are generated together, and CI fails if either is stale. |
+| Orientation contract: `AGENTS.md`, `CHANGELOG.md`, `contracts/release-ledger.json`, `contracts/archive/release-ledger.2026-09-30.json`, `contracts/archive/CHANGELOG.2026-09-30.md`, `contracts/agent-relevant-change-policy.v1.json`, `contracts/orientation-limits.v1.json`, `contracts/orientation-reason-codes.v1.json`, `docs/orientation-contract-reference.md`, `docs/release-ledger-authoring-guide.md`, `contracts/fixtures/orientation/canonicalization/v1.json` | The declarative data a consumer reads from Git objects to decide whether a commit is safe to work against, without executing anything from this repository. Schema `campaigns-os-tooling-orientation/v1`; ledger schema `campaigns-os-release-ledger/v1`. The canonicalization fixture gives independent implementations exact ledger and changelog bytes plus their expected SHA-256 digests. Entry point: [`AGENTS.md`](../AGENTS.md). | Named. The ledger is append-only: a correction ships as a new amendment entry, never an edit. A baseline rotation moves older entries and changelog sections unchanged into dated files under `contracts/archive/`, which never change once merged and are not mandatory orientation reads. `scripts/check-release-ledger.mjs` enforces the two-way gate; `docs/orientation-contract-reference.md` and the canonicalization fixture are generated together, and CI fails if either is stale. |
 | Orientation fixtures: `contracts/fixtures/orientation/envelope/*.json`, `contracts/fixtures/orientation/hostile-target/**` (as named) | The bytes a consumer's parser validates against: one envelope per terminal outcome, plus a hostile target carrying Git hooks, an executable file, and npm lifecycle scripts for proving a reader executes nothing. The hostile target carries a second invariant for the runtime recipe: preparing it must run the recipe's own two steps and no lifecycle script reachable from them. | Named. Regenerate the envelopes with `npm run generate:orientation-docs`. Fixtures under `contracts/fixtures/` that are **not** named here — including the legacy-migration conformance corpus — are this repo's own test data and are not supported. |
 | Runtime recipe: `contracts/runtime-recipe.campaigns-os-node-v1.json` | The declarative description of how a checkout at one commit becomes a usable installed runtime: exact commands, accepted tool ranges, per-step network policy, the enumerated input set, the mandatory output checks, and the enforced bounds. This repository publishes it; the consumer bootstrap executes it. Guide: [`docs/runtime-readiness.md`](runtime-readiness.md). | **Hashed**, deliberately unlike the orientation policy contracts beside it. Any change to commands, network policy, tool versions, inputs, or output verification is an agent-relevant release event, and only a hashed entry makes such a change require `surface_version` to advance in the same PR. A recipe whose commands can change without a version bump is not a contract. |
 | Runtime-recipe fixtures: `contracts/fixtures/runtime-recipe/**` (as named), `docs/runtime-readiness.md` | Accept and single-mutation reject documents a consumer's parser validates against, the prepared-runtime states its output checks must distinguish, and the generated guide. | Named. All of it is generated — regenerate with `npm run generate:runtime-docs`; CI fails on a stale copy. |

package/docs/versioning.md

@@ -42,7 +42,10 @@ consumer needs to know about an agent-relevant change even when
 `CHANGELOG.md` narrates them, and the two are checked against each other in both
 directions. Reason codes and semantic classes are append-only vocabularies —
 renaming or removing one is a breaking change. Raising a limit advances
-`limits_version` and owes its own ledger entry.
+`limits_version` and owes its own ledger entry. Rotating the baseline (moving
+old entries and their sections into a dated `contracts/archive/` pair under the
+ledger's `baseline_floor`) changes no limit and no schema id; it is recorded as
+its own ledger entry.
 
 The runtime recipe carries two version identifiers because they gate different
 things. The **kind** names what an installed consumer must already understand in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextcommerce/campaigns-os",
-  "version": "1.43.1",
+  "version": "1.46.0",
   "description": "Toolkit for agent-assisted NEXT campaign builds.",
   "license": "Apache-2.0",
   "repository": {