@nextcommerce/campaigns-os 1.43.1 → 1.43.2

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.43.1",
+  "surface_version": "1.43.2",
   "package_exports": [
     "./commercial-journey",
     "./commercial-parity",
@@ -119,7 +119,7 @@
       "sha256": "dfc9abed38d456969e47a21f606d308a03bdf036f3466f7d6e47a602747dacf4"
     },
     "contracts/effects.v1.json": {
-      "sha256": "121779835c14d8d48390c57268b50a60fe808f5d9ba91ea2dde5df22a64f8aaf"
+      "sha256": "1dae66e70bb5d167ca407d4ad03e70a1e2e761407b8ad7b85c8a7a51456df858"
     },
     "schemas/campaigns-os-effects.v1.schema.json": {
       "sha256": "3eadd22169ab98bc7c2f682af2751267605170581182158d96be035b0cfe44dc"

package/docs/build-packet.md

@@ -783,6 +783,64 @@ advisories, `unknown_attributes[]`, `pages_scanned`,
 It passes, with no advisory, on the canonical rendered output of every
 certified starter family (`fixtures/certified-families/`).
 
+### Built-output script syntax gate (`built_output.script_syntax`)
+
+Every doctor run that sees built output (the packet path and `doctor --built`
+alike) parses each campaign-owned `.js` file a built page loads by a local
+`<script src>`. A script that does not parse throws a `SyntaxError` on every
+load of every page that references it, and nothing it defines runs; every
+HTML-reading gate passes over it. The shape that shipped was a template-family
+checkout script, copied and hand-edited, left with one closing `});` too many.
+
+Parsing uses Acorn at the latest `ecmaVersion`: `sourceType: 'script'` for
+classic scripts and `'module'` for `type="module"`, which is how the browser
+reads each. Remote scripts (an `http(s):` URL, a protocol-relative `//` URL,
+`data:`) are not campaign-owned and are not read, and neither are data blocks
+such as JSON-LD. The type is compared as the browser compares it, with
+surrounding ASCII whitespace stripped and case ignored. A classic `nomodule`
+script is skipped: a module-capable browser never fetches or runs it. A
+`type="module"` script ignores `nomodule` and is still parsed. Each src
+resolves the way the browser resolves it: against the base in effect when the
+parser prepares the script at its end tag, which is the first HTML `<base
+href>` in tree order among those already parsed, or else the page. A `<base>`
+parsed after a script does not move it, whether it is async, deferred or a
+module: its URL is fixed when it is prepared, not when it is fetched. Parse
+order decides, not final tree position, so a base that table foster parenting
+moves ahead of an earlier script still does not apply to it. A `base` inside
+SVG or MathML is not a base element, and only HTML-namespace `<script>`
+elements are read: an SVG `<script>` never loads a `src` attribute. The href is read as the URL parser reads
+it: only leading and trailing ASCII control characters and spaces are
+stripped. A base
+the browser refuses (one that does not parse, or a `data:` or `javascript:`
+URL) falls back to the page, as the HTML "set the frozen base URL" steps
+require. The percent-decoded path maps under the site root first, then the
+campaign directory, never outside either. A base on another origin makes
+relative srcs remote. Imports inside a module are not followed.
+
+A parse failure blocks (not waivable — a script that cannot be parsed cannot be
+intended to ship) under `built_output.script_syntax.parse_failure`, one error
+per file. The message leads with `<file>:<line>:<column>` and a fixed
+diagnostic category (for example `Unexpected token` or `Invalid regular
+expression`), never text from the script, and names the pages that load the
+file. A referenced local script that is not in the built output is a warning,
+not a blocker, under `built_output.script_syntax.missing_script`, one warning
+per src naming the pages that load it: the browser gets a 404 for it and
+nothing it would define runs, but whether the page needs it is not known here.
+The src is also listed in `scripts_unresolved[]`. While a parse failure blocks
+the gate, the missing scripts stay on the gate's `warned[]` rather than also
+surfacing as warnings.
+
+The gate's evidence lands beside the other checkpoint gates at
+`derived.checkpoint_gates[]` (`id: built_output.script_syntax`, status `pass` |
+`blocked` | `not_applicable`, `findings[]` with `file`, `line`, `column`,
+`source_type` and `pages`, `warned[]` with `src` and `pages`,
+`scripts_scanned`, `scripts_unresolved[]`, `pages_scanned`). Fixtures: `fixtures/script-syntax/{good,bad}`. It passes, parsing every
+local script the pages load and with no missing-script warning, on the
+canonical rendered output of every certified starter family
+(`fixtures/certified-families/`). QA applies the same rule to the page scripts
+it reads for credential declarations (`script-parse:<page_id>`; see
+[QA and test orders](qa-and-test-orders.md)).
+
 > **Where does the source HTML come from?** See [docs/entry-points.md](./entry-points.md) for the five recognized entry points (template-stock, Figma-driven, AI-generated, hand-authored, mixed) and how each populates `source_html.pages[]` + `design_source`.
 
 ## Artifact Locations
@@ -1172,6 +1230,7 @@ When `--map-id <id>` is set, the CLI fetches `GET <proxy>/api/spec/<id>` (defaul
 Saved-Map retrieval behavior (`--map-id`):
 
 - **Re-fetch by default.** Every `start` / `prepare-build` invocation re-fetches from KV. KV is the source of truth; the cache file is a debug/inspection artifact, not a performance optimization.
+- **One writer at a time.** The fetch happens first, but the fetched spec is written to the cache file only once the run holds the per-target prepare-build lock. A second run against the same target, fetching a newer Map revision, waits for the lock before replacing the cache, so the run holding it records the hash of the revision it actually parsed.
 - **`--cached-spec`** reuses the cache without a network call. Use for offline iteration or when the proxy is temporarily unreachable.
 - **`--proxy-base <url>`** overrides the default origin. Use for staging environments or local Worker dev (`wrangler dev`). Spec retrieval carries no credential, so any reachable origin works here — but the same flag also aims the credential-bearing rails (Run Telemetry remit, QA verdict publish, `telemetry list`), and those require `https:` unless the host is loopback (`localhost`, `127.0.0.1`, `[::1]`), which is allowed over plain http with a stderr warning. A plain-http remote proxy is refused before the request. See docs/workflow-findings-sidecar.md (Remit Channel).
 - Failure modes (HTTP error, `{ok: false}` response, network timeout) surface as clean CLI errors before any packet is written.
@@ -1180,7 +1239,7 @@ The fetched spec is treated identically to a `--spec`-supplied local file from t
 
 ## Source HTML Manifest Auto-Population
 
-When the source HTML root carries a source-html manifest at `<source>/.campaigns-os/source-html-manifest.json` (schema `source-html-manifest/v0`, published at `schemas/source-html-manifest.v0.schema.json`) — or `--design-manifest <path>` names a manifest of that schema anywhere else, for a source root nobody can write to — `campaigns-os prepare-build` reads it and uses its `pages[]` block to populate `packet.source_html.pages[]` directly — bypassing the legacy filesystem-name slug matching. Wherever the manifest lives, its `pages[].path` entries stay relative to `--source`. A `pages[]` entry with `skip_reason` and no `path` declares a template-stock page: its assembly decision carries `template_stock: true` and the locked family, and intake demands no design source for it ([Template-stock pages](design-source-package.md#template-stock-pages-the-family-decides)).
+When the source HTML root carries a source-html manifest at `<source>/.campaigns-os/source-html-manifest.json` (schema `source-html-manifest/v0`, published at `schemas/source-html-manifest.v0.schema.json`) — or `--design-manifest <path>` names a manifest of that schema anywhere else, for a source root nobody can write to — `campaigns-os prepare-build` reads it and uses its `pages[]` block to populate `packet.source_html.pages[]` directly — bypassing the legacy filesystem-name slug matching. Wherever the manifest lives, its `pages[].path` entries stay relative to `--source`. Each `pages[]` entry carries exactly one of `path` or `skip_reason`: an entry with both is invalid, and an invalid entry makes prepare-build ignore the whole manifest and fall back to filesystem matching. A `pages[]` entry with `skip_reason` and no `path` declares a template-stock page: its assembly decision carries `template_stock: true` and the locked family, and intake demands no design source for it ([Template-stock pages](design-source-package.md#template-stock-pages-the-family-decides)).
 
 The source-html manifest remains a producer/source-HTML adapter input. It is not
 renamed into the Design Source Package. In the normalized source workflow,
@@ -1190,7 +1249,10 @@ contributions, coverage, gaps/TODOs, Surface Identity, references, and readback.
 When source-html data is the available input and the default package path is
 missing, current v0 `prepare-build` synthesizes the package. If a package already
 exists, it is validated against the current material inputs and reused byte for
-byte or refused; it is never silently regenerated. Downstream Build and Polish
+byte or refused; it is never silently regenerated. The one exception is a stale
+package an earlier `prepare-build` synthesized and nobody has changed since:
+`--force` regenerates it from the current inputs
+([Design Source Package: stale packages](design-source-package.md#prepare-build-emit-validate-or-refuse)). Downstream Build and Polish
 consume the package concept rather than branching back to
 `packet.source_html` as a second source model. The emitted package lives at
 `.campaign-runtime/input/design-source-package.json` by default and is referenced

package/docs/campaigns-os-build-flow.md

@@ -84,6 +84,7 @@ the assembly report.
 - **Pre-checkout pages must ship the same SDK bootstrap as the checkout layout.** Presell and landing pages are SDK `page_type: product`; they need `config.js` (before the loader), the `campaign-cart@v{sdk_version}/dist/loader.js` module script, and the `next-funnel` + `next-page-type` meta tags — not just inert `data-next-*` attributes. Without the loader the SDK silently no-ops: `data-next-hide` conditional visibility (`param.banner` / `param.seen`), `utmTransfer` UTM/query carry-through to checkout (top-of-funnel ad attribution), and SDK analytics never fire. Treat `param.banner` / `param.seen` visibility and `utmTransfer` as standard pre-checkout wiring, not per-campaign discoveries. Doctor enforces this with `built_output.pre_checkout_sdk_bootstrap`.
 - **Every page names the same campaign.** A page borrowed from another funnel (a copied upsell or receipt) must not keep the other campaign's `next-api-key` / `config.js` API key, `next-funnel` meta, or `setAttribution({ funnel })` call; the SDK reads these per page and reconciles nothing, so the order lands on or attributes to the wrong campaign with no visible error. Doctor blocks this, unwaivably, with `built_output.campaign_identity` (one error per drift, naming both files and both values).
 - **SDK markup must do what it says.** `data-next-checkout` goes on the `<form>`; `data-next-checkout-field` values are the SDK's fixed names (`fname`, `lname`, `postal` — never `firstName`, `lastName`, `zip`); an `add-to-cart` button linked by `data-next-selector-id` needs a selector with that id and that selector in `select` mode (swap mode plus the button writes the cart twice); one default-selected card per selector; single-brace tokens inside SDK templates. Doctor enforces the first four as blockers and the last two as warnings under `built_output.sdk_markup` (codes `SWAP_WITH_ADD_TO_CART`, `CHECKOUT_NOT_FORM`, `WRONG_FIELD_NAME`, `MISSING_SELECTOR_ID_MATCH`, `DOUBLE_SELECTED`, `TEMPLATE_DOUBLE_BRACE`).
+- **Campaign scripts must parse.** A hand-edited script with a stray or missing bracket throws a `SyntaxError` on every page that loads it, and nothing in it runs. Doctor parses every campaign-owned `.js` file a built page loads by a local `<script src>` and blocks, unwaivably, with `built_output.script_syntax.parse_failure`, naming the file, line and column.
 - Checkout, upsell, downsell, and receipt pages should preserve starter-template SDK contracts while keeping the campaign/source visual language. Treat starter templates as the reference for required `data-next-*` controls and wiring, not as a mandate to carry their visual chrome into the final campaign.
 - If source HTML declares SDK-owned zones such as `data-commerce-zone="checkout-form"` or `data-commerce-zone="order-summary"`, adopt the selected starter-template family shell for that runtime page. Do not build a custom checkout/upsell structure around a few borrowed includes; browser QA will check declared family structure where `agentContract.qaStructure` exists.
 - If `context.theme` names a generated `brand-theme.css`, copy it into campaign assets and load it after `next-core.css` on checkout, upsell, downsell, and receipt pages. Generated brand-theme v0 is root-variable-only; do not use it as permission to edit SDK-owned selectors or runtime structure.

package/docs/design-source-package.md

@@ -335,14 +335,80 @@ If any current campaign, active/mapped page, source material, manifest or crawl
 provenance, coverage, template family/reference, material fingerprint,
 readiness, or readback check fails, `prepare-build` refuses. It leaves the
 existing package and packet/context/report/brief sidecars byte-identical. It
-does not silently regenerate or overwrite the package; source preparation must
-reconcile the package and its references explicitly before retrying.
+does not silently regenerate or overwrite the package. The refusal names the
+package file and says which recovery applies:
+
+- **A package `prepare-build` synthesized itself.** The Assembly Report's
+  `design_source_package` reference records `origin`: `"synthesized"` when
+  `prepare-build` wrote the package bytes (or reused bytes it had written), and
+  `"adopted"` when it validated and reused a package it did not write. When the
+  previous report at this run's report path says `"synthesized"` and the
+  package bytes still hash to that report's `sha256`, the stale package is the
+  producer's own output: rerun with `--force` and `prepare-build` regenerates
+  it from the current inputs (mode `regenerated`), announcing the replacement
+  on stderr. `--force` also resets any stage evidence the Assembly Report
+  carries, exactly as it does for the report alone.
+- **Any other package** — placed by an operator, edited by hand after it was
+  written, adopted by an earlier run, or recorded by a report that predates
+  `origin` — is never overwritten, `--force` or not. Reconcile it with the
+  current inputs, or, if no downstream stage has consumed it, delete it and
+  rerun so `prepare-build` synthesizes a fresh one.
+
+Only the Assembly Report carries `origin`; the packet and context references
+keep their four strict fields.
+
+The package is published before the report that records it. So that a run
+which fails or dies between the two does not leave its own package unprovable,
+`prepare-build` first writes a pending provenance record beside the package
+(`.campaign-runtime/input/.design-source-package.json.pending-provenance.json`)
+naming the sha256 of the bytes it is about to publish, and removes it once the
+Assembly Report is written. A `--force` run that replaces a stale package it
+proved its own keeps that package's sha256 in the record too, so a
+regeneration that fails or dies part way leaves whichever package is on disk
+provable. A run that finds another writer's package at the path and adopts it
+instead of publishing drops its own candidate from the record. A retry that
+finds the record treats a package whose bytes still hash to one of its entries
+as `"synthesized"`, exactly as if the report had recorded it; bytes changed
+since are not vouched for, and a malformed record vouches for nothing. Just
+before the report is published the record is narrowed to what the report
+records (the package's hash when synthesized, nothing when adopted), so no
+unpublished candidate outlives the report. The record's path is
+reserved like the other outputs, so no configurable output may point at it.
+
+Runs against the same target take turns. From the stage-evidence check and
+the reading of its inputs (CampaignSpec, source manifest, page mappings, asset
+crawl) through the packet, context and report that record them,
+`prepare-build` holds a lock directory beside the package
+(`.campaign-runtime/input/.design-source-package.json.lock`), so each run judges
+provenance against the report and package the previous run left, and records
+the inputs it actually read. With `--map-id`, the fetched spec is written to the
+shared `fetched-specs/` cache file inside the same lock, so a run waiting for
+the lock cannot replace the spec the lock holder is reading. The source-html
+manifest is read once: the `manifest_sha256` the package records is the hash of
+the exact bytes source intake parsed. Every command that edits the Assembly Report
+(`doctor`, `qa run`, waivers, the polish merge and the other stage producers)
+takes the same lock for its read-modify-write, so no stage evidence lands
+between `prepare-build`'s final stage-evidence check and its publication; a
+producer that `prepare-build` reaches from inside its own run enters directly.
+Of several concurrent `--force` runs, the first regenerates the package and the
+rest reuse it as `"synthesized"`. A command that finds the lock held waits up to
+a minute. The lock directory and its owner record appear together, so a lock
+left by a process that died is recovered automatically, and a lock directory
+without an owner record (only an older release leaves one) is never taken
+over: the command refuses it after about a second and names it. Confirm no
+campaigns-os process is working on the target, then remove it. Do not run an
+older Campaigns OS release against the same target at the same time. A
+waiver's `--dry-run` preview takes no lock.
 
 Before writing any output, `prepare-build` also requires distinct paths for the
 Build Packet, Build Context, Assembly Report, Doctor output, normalized Build
 Brief, and fixed Design Source Package. Equal paths and filesystem aliases are
 rejected, including symlinks, hard links, dangling leaf symlinks, and symlinked
-parent directories.
+parent directories. No output may be placed inside the lock directory, or
+inside the staging and tomb directories the lock creates beside it
+(`.lock.staging-*`, `.lock.recovery-staging-*`, `.lock.released-*`,
+`.lock.abandoned-*`), directly or through a directory alias: they are removed
+with their contents when the run finishes.
 
 This behavior is the implemented v0 compatibility boundary. It does not promise
 that a separate future workflow command will generate, repair, approve, or
@@ -504,10 +570,12 @@ Either declaration records the page on the assembly report's
 `template_family` set to the family the packet locks, lists it under
 `stages.prepare_build.declared_out_of_scope`, and reaches
 `stages.prepare_build.status: "completed_partial"`. Intake demands no design
-source for the page: no `capture-*` TODO, no `link-*` TODO. The build stage
-materialises it from the locked family's own page of that role — the `next
-build` prompt names every template-stock page and the family to copy it from —
-and the family decides only *how* the package records its coverage:
+source for the page: no `capture-*` TODO, no `link-*` TODO. This source-scope
+classification does **not** authorize publishing a stock page. `next build`
+keeps these routes unbuilt by default and requires explicit operator opt-in
+per page before materializing a stand-in from the locked family. In particular,
+presell and landing pages staying on another host must not be replaced with
+placeholder copy. The family decides only *how* intake records coverage:
 
 - **A family that publishes complete Template Reference proof — today `apollo`
   alone** — covers the page with synthesized `template_baseline` coverage from
@@ -533,10 +601,10 @@ not built yet`, and keeps checkout launch and test-order proof blocked while a
 runtime page (`select`, `checkout`, `upsell`, `receipt`) is among them. You get
 a terminal, honest intake — not a fully proven campaign.
 
-The build stage lifts those limits page by page. `next-campaigns-build`
-materialises each template-stock page from the locked family's own page of
-that role (the pre-checkout `select` step first, because it seeds the cart the
-runtime pages read). Once the page's built HTML exists at its route under
+The build stage lifts those limits page by page for opted-in pages. It uses
+the locked family's own page of that role (an opted-in pre-checkout `select`
+stand-in first, because it seeds the cart the runtime pages read).
+Once the page's built HTML exists at its route under
 `_site/<slug>/`, doctor reads the `template_stock` marker on the scope decision
 and counts the page as built: it moves into `derived.scope.built_pages` (with
 `template_stock: true`, `template_family`, and no `source_path`), joins the
@@ -565,10 +633,10 @@ family the `template-baseline` contribution's `presentation_intent` names.
 
 ### Recovery after a blocked first run
 
-A blocked run still emits the package, and `prepare-build` never refreshes a
-package it did not just create. So a first run that blocked leaves a package
-whose provenance names the *old* manifest, and simply rerunning with a new
-manifest fails closed:
+A blocked run still emits the package, and a plain `prepare-build` never
+refreshes a package it did not just create. So a first run that blocked leaves a
+package whose provenance names the *old* manifest, and simply rerunning with a
+new manifest fails closed:
 
 ```
 campaigns-os: Design Source Package at <target>/.campaign-runtime/input/design-source-package.json
@@ -597,6 +665,12 @@ npm run campaigns-os -- start \
   --template-family <family>
 ```
 
+When the refusal says the package was synthesized by an earlier
+`prepare-build` and is unchanged since, skip step 2 and add `--force` to step 3
+instead: `prepare-build` (and `start` and `build`, which run the same intake)
+then regenerates the package itself. `--force` resets any stage evidence the
+Assembly Report carries, so the same caution applies.
+
 Step 2 is only ever correct for a package emitted by a blocked run that no
 downstream stage has consumed. Once Build or Polish has bound its evidence to a
 package fingerprint, deleting it invalidates that evidence; reconcile through

package/docs/effects.md

@@ -134,7 +134,9 @@ a flag the command rejects up front. It writes nothing, journals nothing, and is
 the row to read when you want to know what a typo costs. The one exception is
 declared on the rows it belongs to: `start`, `prepare-build`, `build`,
 `run start` and `run end` close out a **stale** run session at the root they are
-about to act on *before* argv is refused.
+about to act on *before* argv is refused. Commands that implement `--dry-run`
+skip this closeout whenever that flag is present, including a valued flag that
+will be refused: `run end --dry-run yes` writes, sends, and deletes nothing.
 
 A refusal is decided by argv alone. When file content or state on disk decides
 the outcome, the command has reached a handler failure and journals it.
@@ -143,9 +145,13 @@ For intake, run-record, built-site QA, and `next`, argv-only checks run before
 their handler reads the target; invalid values are refused without a journal
 entry. For `start`, `prepare-build`, and `build`, bare, empty, and whitespace-only
 values of `--spec`, `--map-id`, `--source`, `--target`, `--source-kind`,
-`--proxy-base`, `--wrapper-policy`, `--design-manifest`, and
-`--order-path-depth` are refused before local spec reads, Map fetches, or cache
-writes on the `--spec`, `--map-id`, and `--map-id --cached-spec` paths.
+`--proxy-base`, `--wrapper-policy`, `--design-manifest`, `--order-path-depth`,
+`--template-family`, `--allow-uncertified-template`, `--theme-policy`, and
+`--brief` are refused before local spec reads, Map fetches, or cache writes on
+the `--spec`, `--map-id`, and `--map-id --cached-spec` paths. So is a
+`--theme-policy` outside `inspect_only`, `auto`, and `off`. Whether a named
+template family is certified, and whether a named brief can be read, depend on
+file content: those checks still run in the handler and are journaled.
 The operator-facing `run-record` and `run end` commands refuse bare, empty, or
 whitespace-only values for every value-taking inherited run-record flag before
 packet work. The five agent
@@ -189,6 +195,12 @@ flag without a value is refused with "Missing value for --<flag>". If a named
 packet yields neither a Map ID nor a valid local-spec identity after checkpoint
 preflight reads the packet, spec, and report, the requirement is a journaled
 handler failure. A conflicting local/Map identity is also a handler failure.
+When `qa run` selects `--legacy-api-test-order`, a missing, bare, empty, or
+unusable `--cart` and an unknown legacy mode are argv-only refusals before QA
+input resolution. They append no lifecycle entry. Accepted modes remain
+`accept`, `decline`, and `both` (case-insensitive); browser `--test-order` still
+takes precedence and does not require the legacy cart. API credentials are
+still checked only inside the legacy handler and failures there are journaled.
 The nested run-record refusal scope in session closeout guards against future
 changes. No internal closeout can currently create a refusal before its
 invoking command journals.

package/docs/local-setup.md

@@ -3,7 +3,7 @@
 For a new campaign, choose its working folder and run this from that folder:
 
 ```sh
-npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.43.1 next-campaign-page-kit@0.2.0 && npx --no-install campaigns-os tooling setup --target . --platform claude
+npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.43.2 next-campaign-page-kit@0.2.0 && npx --no-install campaigns-os tooling setup --target . --platform claude
 ```
 
 Review the release source/provenance before installation as described in

package/docs/orientation-contract-reference.md

@@ -25,7 +25,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.43.1`
+Supported surface at generation time: `1.43.2`
 
 ## Forward compatibility
 

package/docs/progress-snapshots.md

@@ -59,12 +59,16 @@ across them. A progress stream is independent of a run-session ID.
 
 Sanitized immutable snapshots are written under the target repository's
 `.campaign-runtime/progress/` before any request. Allocation uses an exclusive
-local lock with a process owner. Dead owners are recovered through an exclusive
-recovery claim and an atomic rename; a live process is never evicted. An ownerless
-crash gap is recoverable after ten seconds. If recovery itself is interrupted,
-capture fails closed: stop all Campaigns OS writers for that target, then remove
-the abandoned `.allocation-lock` directory in the affected progress scope before
-retrying `next`. Do not remove a lock while a writer is active.
+local lock with a process owner; the lock directory and its owner record are
+published together in one rename, so a lock never exists without its owner.
+Dead owners are recovered through an exclusive recovery claim and an atomic
+rename; a live process is never evicted. A lock directory with no owner record
+(left by an older release) is never taken over: capture refuses it after about
+a second. If one is found, or if recovery itself is interrupted, capture fails
+closed and the warning names the affected `.allocation-lock` directory: stop
+all Campaigns OS writers for that target, then remove that directory before
+retrying `next`. Do not remove a lock while a writer is active. Do not run an
+older Campaigns OS release against the same target at the same time.
 
 An unchanged projection reuses its ID, timestamp and sequence. Identity
 changes start a new stream. Each local scope retains at most 32 snapshots and

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.
@@ -793,9 +801,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 +850,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 +961,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 |
 
@@ -1690,6 +1801,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
 

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.43.2`.
 
 ## What this is