@nextcommerce/campaigns-os 1.53.0 → 1.54.0

package/contracts/release-ledger.json

@@ -6197,6 +6197,339 @@
         }
       ],
       "entry_sha256": "197929e76610b701b015cac7ee37f1f8a75b18e350a8268b679b8ca51a9b7f14"
+    },
+    {
+      "id": "RL-0237",
+      "sequence": 228,
+      "date": "2026-10-06",
+      "kind": "release",
+      "surface_version": null,
+      "changelog_section": "1.53.0+agent.3",
+      "changelog_sha256": "d93e2a6e96de6d7e17d3f1235ff2c9ca6984890fe1026df284c38eacdbcb5557",
+      "agent_impact": "standardize evaluates a campaign_cart_app root's bundled campaign-cart dependency against the SDK support policy by the lowest version its package.json spec allows, recorded as sdk_loader.bundled_dependency.floor_version. An exact pin (0.4.30, =0.4.30, v0.4.30) or one ^, ~ or >= range on a released version is evaluated by that version, unchanged from before. Any other spec (<0.4.39, an ||, hyphen or x-range, a tag) now gets no version_policy evaluation and raises the new warning version.sdk_dependency_floor_unknown; earlier releases evaluated the version written in the spec, so such a range could pass or fail the minimum on a version npm might not install. Prerelease pins still raise version.sdk_prerelease_pin only. resolved_version is unchanged.",
+      "compatibility": "compatible",
+      "migration": "none",
+      "changes": [
+        {
+          "class": "named_surface",
+          "path": "docs/campaign-standardization-report.md",
+          "surface_entry": "docs/campaign-standardization-report.md",
+          "summary": "Describe judging a bundled dependency by its floor_version, which specs have a certain floor, and the version.sdk_dependency_floor_unknown warning for those that do not."
+        }
+      ],
+      "entry_sha256": "d98fbc7e8865f4ab5bb35bb7510a787af576ef23dfe5b50377fb2f744af8bf0b"
+    },
+    {
+      "id": "RL-0236",
+      "sequence": 229,
+      "date": "2026-10-06",
+      "kind": "release",
+      "surface_version": null,
+      "changelog_section": "1.53.0+agent.4",
+      "changelog_sha256": "b1de69de9257b9151d0fb38eeb0c23f92bc8a3a405f0c0f6e6d7427b44564c75",
+      "agent_impact": "doctor built_output.sdk_markup WRONG_FIELD_NAME and the standardize checkout field contract now judge first_name and last_name (mapped from Campaign Cart SDK 0.4.39) and phone_number (from 0.4.41) against the SDK version of the page: doctor reads the page's own exact loader pin, then the campaign's _data/campaigns.json sdk_version; standardize reads the file's own exact loader pin, then the lowest exact pin the campaign root declares (exact loader pins; a bundled campaign-cart dependency's exact pin or the floor of a ^, ~ or >= range, any other range reading as unknown; or for Page Kit roots the campaign's campaigns.json sdk_version). On a version at or after the name's since-version the name passes, so pages written to the SDK 0.4.41 field names stop blocking. Below it, or when no exact released version can be read, results are unchanged: first_name and last_name block (WRONG_FIELD_NAME; checkout.unsupported_field_binding) and phone_number blocks in doctor and warns as checkout.unknown_field_binding in standardize; fname, lname and phone pass on every version. WRONG_FIELD_NAME details gain sdk_version and sdk_version_source (loader or campaigns_json) and, for these three names, since; the gate gains campaign_sdk_version. standardize checkout_fields.bindings[] gain since, sdk_version and sdk_version_source (loader, campaign or campaigns_json), and stale-alias and unknown-field evidence for these names carries since and sdk_version.",
+      "compatibility": "compatible",
+      "migration": "none",
+      "changes": [
+        {
+          "class": "cli_surface",
+          "path": "src/doctor/checks.mjs",
+          "surface_entry": "doctor",
+          "summary": "The SDK markup gate passes the campaign's campaigns.json sdk_version to the field-name check as the fallback for a page with no exact loader pin, and records it as campaign_sdk_version."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/build-packet.md",
+          "surface_entry": "docs/build-packet.md",
+          "summary": "WRONG_FIELD_NAME: first_name and last_name are mapped from SDK 0.4.39 and phone_number from 0.4.41, judged against the page loader pin, then campaigns.json; unknown is judged as an earlier SDK."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/campaign-standardization-report.md",
+          "surface_entry": "docs/campaign-standardization-report.md",
+          "summary": "Describe the field contract version_gated_aliases and the sdk_version and sdk_version_source each checkout binding records. A bundled dependency counts only through an exact pin or a ^, ~ or >= floor."
+        }
+      ],
+      "entry_sha256": "b6af3f03f0bc8e03b7a24d10c65c2cc889ede6e04ce7828b4e78c2562414564b"
+    },
+    {
+      "id": "RL-0238",
+      "sequence": 230,
+      "date": "2026-10-06",
+      "kind": "release",
+      "surface_version": null,
+      "changelog_section": "1.53.0+agent.5",
+      "changelog_sha256": "69caf644546b719adf09b72227b50230250b586e6043de066dfe4b79c70c22df",
+      "agent_impact": "qa run --test-order now types the test card on Campaign Cart SDK 0.4.41 checkouts. 0.4.41 mounts the card number and CVV as iframe[id^=spreedly-hosted-number] and iframe[id^=spreedly-hosted-cvv] (Spreedly Checkout SDK fields loaded by payments.29next.com/js/v1/payment.js) instead of the iFrame v1 spreedly-number-frame / spreedly-cvv-frame ids, and the runner matched only the old ids, so the typed-card step timed out before submit on 0.4.41. The runner now matches either generation. Before typing, card_fields_filled waits up to 15s until no element carries next-loading-spreedly (the SDK sets it from before the card iframes mount until the fields are ready, 0.4.38 to 0.4.41), because digits typed into a 0.4.41 field before then can be dropped, and the SDK then refuses the short number without tokenizing, so order_submitted timed out with no order. After typing, it reads both fields back and retypes, up to 3 attempts in all. The step gains evidence {generation: spreedly-hosted | spreedly-iframe-v1, number_frame_id, cvv_frame_id, ready_wait_ms, attempts}; its detail is unchanged. card_fields_filled now fails by name, with no order submitted, in three cases: when more than one number or CVV iframe matches or the two generations mix (Playwright previously raised a strict-mode violation); when next-loading-spreedly is still set after 15s, meaning the card script never finished loading; and when the fields still do not hold the typed card after 3 attempts (the error gives the digit counts and last four of the number). No verdict field or flag changes; spreedly_tokenized still reads the core.spreedly.com payment_methods request, which 0.4.41 still makes. Pages pinned to 0.4.40 or earlier run as before, plus the readiness wait and the read-back.",
+      "compatibility": "additive",
+      "migration": "none",
+      "changes": [
+        {
+          "class": "named_surface",
+          "path": "docs/qa-and-test-orders.md",
+          "surface_entry": "docs/qa-and-test-orders.md",
+          "summary": "The typed-card step names both card-field generations (Spreedly iFrame fields on SDK 0.4.40 and earlier, the Spreedly-hosted fields NEXT payments.29next.com script mounts on 0.4.41 and later), waits for next-loading-spreedly to clear before typing, and reads both fields back, retyping up to three attempts in all."
+        }
+      ],
+      "entry_sha256": "edc4fd10bfe974dd3cfd9e6a6d5f3337a483db0525f6231bf68d3e79e22ac51f"
+    },
+    {
+      "id": "RL-0240",
+      "sequence": 231,
+      "date": "2026-10-06",
+      "kind": "release",
+      "surface_version": null,
+      "changelog_section": "1.53.0+agent.7",
+      "changelog_sha256": "f91240db8674ccb5f7a94f042c93b059aa4f0a138124927b391554f554cafddc",
+      "agent_impact": "doctor --built with --base-url adds a ready line saying the local built files were checked and the URL was not fetched (it only fills deploy.preview_url in the minimal Build Packet), names qa run --site <repo> --base-url <url> --family <family> --browser for the served pages, and sets derived.base_url { value, fetched: false, recorded_as: deploy.preview_url } in JSON. Do not report a doctor --built result as a check of a preview or production site.",
+      "compatibility": "compatible",
+      "migration": "none",
+      "changes": [
+        {
+          "class": "cli_surface",
+          "path": "src/cli.mjs",
+          "surface_entry": "doctor",
+          "summary": "The doctor --built usage line says --base-url is not fetched and fills deploy.preview_url in the minimal packet."
+        },
+        {
+          "class": "cli_surface",
+          "path": "src/doctor/inspect.mjs",
+          "surface_entry": "doctor",
+          "summary": "doctor --built with --base-url reports that only local files were checked, names qa run --site for served pages, and sets derived.base_url.fetched false."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/qa-and-test-orders.md",
+          "surface_entry": "docs/qa-and-test-orders.md",
+          "summary": "State that doctor --built reads local files only, that --base-url is not fetched, how to check served pages, and that the minimal packet does not drive packet QA."
+        }
+      ],
+      "entry_sha256": "6382a67f50d12ae1999b352595ff6faa13fca3e122617e9ba43ce4cc8c77e659"
+    },
+    {
+      "id": "RL-0241",
+      "sequence": 232,
+      "date": "2026-10-06",
+      "kind": "release",
+      "surface_version": null,
+      "changelog_section": "1.53.0+agent.9",
+      "changelog_sha256": "359d517828d411f329a3fe02bb421a676652ffb2662532599e435dd0cf38a5f7",
+      "agent_impact": "When the per-target lock or the progress allocation lock cannot be taken because a file, a symbolic link, or a directory with no owner record that holds other entries sits at the lock path, the refusal names what is there and says it is never removed automatically. Report it as an obstruction to move out of the way, not as a busy or ownerless lock. The holder of a lock also removes staging and released siblings whose recorded owner process no longer exists.",
+      "compatibility": "compatible",
+      "migration": "none",
+      "changes": [
+        {
+          "class": "named_surface",
+          "path": "docs/design-source-package.md",
+          "surface_entry": "docs/design-source-package.md",
+          "summary": "Say that a non-lock entry at the target lock path is named and never removed, and that the holder removes lock siblings left by dead processes."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/progress-snapshots.md",
+          "surface_entry": "docs/progress-snapshots.md",
+          "summary": "Say that a file or other non-lock entry at the allocation lock path is named in the warning and never removed."
+        }
+      ],
+      "entry_sha256": "82debb74a4998923dd9cfb3bea6ed486ba408860001fe79c6dc2460de026bb4a"
+    },
+    {
+      "id": "RL-0244",
+      "sequence": 233,
+      "date": "2026-10-07",
+      "kind": "release",
+      "surface_version": null,
+      "changelog_section": "1.53.0+agent.10",
+      "changelog_sha256": "7b0402af57d09ba68a5ca4fc1b8e9044eafa8f2b8a3d921bf26c6803958126db",
+      "agent_impact": "The vendored starter catalog and the SDK attribute index now describe Campaign Cart SDK 0.4.41. A certified family is verified against 0.4.41, so a missing SDK pin is reported against that version. built_output.sdk_markup accepts the 0.4.41 address block, data-next-i18n and phone attributes and reports sdk_attribute_index_version 0.4.41; built_output.cart_placeholders checks pages pinned to 0.4.41 instead of reporting them unexercised. Read a WRONG_FIELD_NAME finding as naming the 0.4.41 field set, which is the same as 0.4.38 plus the version-gated aliases.",
+      "compatibility": "compatible",
+      "migration": "none",
+      "changes": [
+        {
+          "class": "named_surface",
+          "path": "docs/build-packet.md",
+          "surface_entry": "docs/build-packet.md",
+          "summary": "Say the vendored checkout field names are taken at SDK v0.4.41."
+        }
+      ],
+      "entry_sha256": "41994901ffbce1dbdf74e020465ba9622ed062cb310b6021265fe848ae12a559"
+    },
+    {
+      "id": "RL-0245",
+      "sequence": 234,
+      "date": "2026-10-07",
+      "kind": "release",
+      "surface_version": "1.54.0",
+      "changelog_section": "1.54.0",
+      "changelog_sha256": "60ec528377c8a9f14165cfd7d6e09a4e7933c65cd53c6ca3fe8f74ff7acbe91d",
+      "agent_impact": "Surface 1.54.0. Ships 1.53.0+agent.1 through +agent.11, including qa run --test-order typing card fields on Campaign Cart SDK 0.4.41 and the starter catalog, SDK attribute index and support policy at 0.4.41. New subcommand sdk repin --target <static-repo> [--target-sdk <x.y.z>] [--apply] [--json] replaces the hand-run sed step when bumping the Campaign Cart SDK in a static campaign repo (no _data/campaigns.json). It rewrites only the version segment of semver-pinned (@vX.Y.Z or @X.Y.Z) loader.js and campaign-cart.css URLs below the target, the same references standardize lists under sdk_loader.references; @latest, @main, commit and prerelease refs and pins at or above the target are reported in left_alone and never rewritten. The target defaults to the SDK support policy's preferred_minimum. Preview is the default and writes nothing; --apply writes the files and the change record .campaign-runtime/sdk-repin.json (schema campaigns-os-sdk-repin/v0: files_touched, reference_count, from_versions, to_version, rewrites, left_alone), whose path and sha256 the --json result gives for a Run Record to cite. A second run reports nothing_to_change and writes nothing. A page-kit repo is refused with exit 2 (status refused_page_kit); use page-kit sync there. After --apply, run browser QA against the new pin: repin does not prove the SDK works. qa run keeps the verdict local by default when the base URL (from --base-url or the packet's deploy.preview_url) is a local address (localhost or *.localhost, any 127.x.x.x, 0.0.0.0, [::1] or an IPv4-mapped loopback), for saved-Map and local-spec runs alike; publish_decision.reason reads loopback_base_url and the output names qa publish and --post-verdict. An agent that wants a local-address verdict on the Map's QA tab passes --post-verdict or runs qa publish afterwards. Remote base URLs publish as before. record deploy now binds stages.deploy to the build it probed (source_build_fingerprint). After a record build of different output, a stamped deploy reads required and next names deploy before QA: serve the new build and run record deploy again. A byte-identical rebuild keeps the deploy current, and a deploy recorded before this change, with no stamp, is kept as recorded.",
+      "compatibility": "compatible",
+      "migration": "none",
+      "changes": [
+        {
+          "class": "compatibility_policy",
+          "path": "compatibility.json",
+          "surface_entry": null,
+          "summary": "Advance the declared version to 1.54.0."
+        },
+        {
+          "class": "compatibility_policy",
+          "path": "contracts/effects.v1.json",
+          "surface_entry": "contracts/effects.v1.json",
+          "summary": "Declare sdk repin (tier none) and sdk repin --apply (tier B: the rewritten files, the change record and the lifecycle journal), and add --apply to the effect-changing flags; on the eight qa run rows, name the local-address default in the verdict send's condition and record it unobserved under the 127.0.0.1 offline fixture (#486), with qa publish as the proof of that send; state that record deploy stamps the build fingerprint it probed, and that record build makes a completed deploy stamped with other output required."
+        },
+        {
+          "class": "compatibility_policy",
+          "path": "contracts/supported-surface.json",
+          "surface_entry": "contracts/supported-surface.json",
+          "summary": "Advance surface_version to 1.54.0 and record the effects contract and Assembly Report schema hashes."
+        },
+        {
+          "class": "cli_surface",
+          "path": "src/cli.mjs",
+          "surface_entry": "sdk",
+          "summary": "Add the sdk repin subcommand and its usage line: rewrite semver-pinned Campaign Cart loader and stylesheet URLs below the target in a static repo, preview by default, --apply writes the files and the campaigns-os-sdk-repin/v0 change record, --target-sdk overrides the policy target, a page-kit repo is refused with exit 2; the record deploy usage line says the deploy stage carries the build fingerprint it probed and is required again after a record build of other output."
+        },
+        {
+          "class": "compatibility_policy",
+          "path": "docs/supported-surface.md",
+          "surface_entry": "docs/supported-surface.md",
+          "summary": "Add the sdk repin row."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/sdk-storage-compatibility.md",
+          "surface_entry": "docs/sdk-storage-compatibility.md",
+          "summary": "Document sdk repin as the pin-rewrite step after the storage check for static repos: which references it rewrites and leaves alone, the preview and --apply modes, the change record, and the page-kit refusal."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/effects.md",
+          "surface_entry": "docs/effects.md",
+          "summary": "List the sdk repin preview among the read-only invocations and --apply among the effect-changing flags."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/campaign-standardization-report.md",
+          "surface_entry": "docs/campaign-standardization-report.md",
+          "summary": "Point from sdk_loader.references to sdk repin for static repos."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/qa-and-test-orders.md",
+          "surface_entry": "docs/qa-and-test-orders.md",
+          "summary": "Describe the local-address default and how to publish such a verdict; the local proof steps say record deploy is bound to the build it probed and is owed again after a record build of other output."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/local-setup.md",
+          "surface_entry": "docs/local-setup.md",
+          "summary": "Pin the 1.54.0 package in the local setup install command."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/skills-revision.md",
+          "surface_entry": "docs/skills-revision.md",
+          "summary": "Use the current 1.54.0+skills.1 bundle in executable examples."
+        },
+        {
+          "class": "package_export",
+          "path": "package.json",
+          "surface_entry": null,
+          "summary": "Advance the package version to 1.54.0."
+        },
+        {
+          "class": "skill",
+          "path": "skills.json",
+          "surface_entry": "skills.json",
+          "summary": "Advance the bundled skill revision to 1.54.0+skills.1 and each skill version one patch."
+        },
+        {
+          "class": "skill",
+          "path": "skills/campaign-lifecycle-orientation/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.54.0+skills.1 bundle revision."
+        },
+        {
+          "class": "skill",
+          "path": "skills/campaign-readback-classification/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.54.0+skills.1 bundle revision."
+        },
+        {
+          "class": "skill",
+          "path": "skills/campaign-run-evidence/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.54.0+skills.1 bundle revision."
+        },
+        {
+          "class": "skill",
+          "path": "skills/contribution-intake/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.54.0+skills.1 bundle revision."
+        },
+        {
+          "class": "skill",
+          "path": "skills/next-campaigns-build/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.54.0+skills.1 bundle revision."
+        },
+        {
+          "class": "skill",
+          "path": "skills/next-campaigns-os-setup/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.54.0+skills.1 bundle revision."
+        },
+        {
+          "class": "skill",
+          "path": "skills/next-campaigns-os/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.54.0+skills.1 bundle revision."
+        },
+        {
+          "class": "skill",
+          "path": "skills/next-campaigns-polish/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.54.0+skills.1 bundle revision."
+        },
+        {
+          "class": "skill",
+          "path": "skills/next-campaigns-qa/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.54.0+skills.1 bundle revision."
+        },
+        {
+          "class": "documentation",
+          "path": "docs/orientation-contract-reference.md",
+          "surface_entry": "docs/orientation-contract-reference.md",
+          "summary": "Regenerate at surface 1.54.0."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/runtime-readiness.md",
+          "surface_entry": "docs/runtime-readiness.md",
+          "summary": "Regenerate at surface 1.54.0."
+        },
+        {
+          "class": "generated_runtime",
+          "path": "package-lock.json",
+          "surface_entry": null,
+          "summary": "Advance the package version to 1.54.0."
+        },
+        {
+          "class": "schema",
+          "path": "schemas/campaign-runtime-assembly-report.v0.schema.json",
+          "surface_entry": "schemas/campaign-runtime-assembly-report.v0.schema.json",
+          "summary": "Describe source_build_fingerprint on a stage, which stages.deploy now carries: the build fingerprint record deploy probed."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/build-packet.md",
+          "surface_entry": "docs/build-packet.md",
+          "summary": "The record build and record deploy rows say deploy is stamped with the build it probed and reset to required by a record build of other output; an unstamped deploy is kept."
+        }
+      ],
+      "entry_sha256": "5ab33ca302fa671ac78c3e9b752ed7b251e756b05256f97ff75acd08c58ad5ba"
     }
   ]
 }

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.53.0",
+  "surface_version": "1.54.0",
   "package_exports": [
     "./commercial-journey",
     "./commercial-parity",
@@ -60,7 +60,7 @@
       "sha256": "65bcd8b5f41f1e9ecfc36f3b8838cd4ed531bd74c5a318ee5147131f6c9b4a1c"
     },
     "schemas/campaign-runtime-assembly-report.v0.schema.json": {
-      "sha256": "8a0d37be9a4bb34d0ed073c9d6bfa4406a7b499c801c34c5fbb26646e2665c0b"
+      "sha256": "625a6f2ed6bee726f9cddad750e64a54a7e03744c777f5a70afe4a39afdd9848"
     },
     "schemas/campaign-runtime-build-context.v0.schema.json": {
       "sha256": "f310c1b7844d9b1994864d15858ff0c6f17efc1e5285ba193d181bdb2dd4be2f"
@@ -120,7 +120,7 @@
       "sha256": "dfc9abed38d456969e47a21f606d308a03bdf036f3466f7d6e47a602747dacf4"
     },
     "contracts/effects.v1.json": {
-      "sha256": "8282f7ffe91aaf12c4b79e4431b5ddc35cce82e42f1746d4a0ea44f54bd7fb8e"
+      "sha256": "10a9020aaba5780e2ee2f3ddf6d81127047f6caec0de774c48540d9b664e0a6a"
     },
     "schemas/campaigns-os-effects.v1.schema.json": {
       "sha256": "3eadd22169ab98bc7c2f682af2751267605170581182158d96be035b0cfe44dc"

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

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

package/docs/build-packet.md

@@ -827,12 +827,19 @@ Blockers (not waivable — the markup provably does not do what it says):
 - `CHECKOUT_NOT_FORM` — `data-next-checkout` on an element that is not `<form>`.
 - `WRONG_FIELD_NAME` — `data-next-checkout-field` with a value the SDK does not
   map. The set is vendored from the SDK at a named tag
-  (`src/sdk-attribute-index.mjs`, currently v0.4.38: `email`, `fname`, `lname`,
+  (`src/sdk-attribute-index.mjs`, currently v0.4.41: `email`, `fname`, `lname`,
   `phone`, `address1`, `address2`, `city`, `province`, `postal`, `country`,
   `payment-method`, `accepts_marketing`, `cc-number`, `cc-month`, `cc-year`,
   `exp-month`, `exp-year`, `cvv`, the legacy `card-*` spellings, and any
   `billing-` prefixed name). The message names the SDK spelling for the usual
-  offenders (`firstName` → `fname`, `zip` → `postal`).
+  offenders (`firstName` → `fname`, `zip` → `postal`). Three names depend on
+  the page's SDK version: `first_name` and `last_name` are mapped from v0.4.39
+  and `phone_number` from v0.4.41. The version is the page's own exact loader
+  pin, else the campaign's `sdk_version` in `_data/campaigns.json`. Below the
+  name's version, or when neither gives an exact released version, the name
+  blocks, and the message names `fname`, `lname` or `phone`, which every
+  version maps. Each finding carries `sdk_version` and `sdk_version_source`
+  (`loader` or `campaigns_json`) in its detail.
 - `MISSING_SELECTOR_ID_MATCH` — an `add-to-cart` button whose
   `data-next-selector-id` names no selector on the page (an element that is a
   bundle, package, cart or upsell selector; another element echoing the id
@@ -1730,10 +1737,10 @@ hand-editing `.campaign-runtime/` JSON:
 | Command | Writes | Refused (nothing written) when |
 |---|---|---|
 | `campaigns-os record setup --packet <p>` | Build Context `scaffold.required=false` (`handoff_skill` next-campaigns-build) and `stages.setup` completed | the campaign output directory (`assembly.output_dir`) does not exist, or there is no Build Context or Assembly Report |
-| `campaigns-os record build --packet <p> [--build-environment <development\|production>]` | `stages.assembly` completed with `build_fingerprint` = doctor's `derived.build_output_fingerprint.value`, `source_package_material_fingerprint` = the report's Design Source Package material fingerprint when present, `evidence.build_environment` = the `--build-environment` value when given (kept from the last record otherwise), and `stages.polish` reset to `required` (`required_by` build, `required_for` qa) unless its evidence is bound to this exact output | doctor cannot compute the fingerprint (no `_site/<public_route_slug>/`), setup is still required, or `stages.setup` is not terminal |
+| `campaigns-os record build --packet <p> [--build-environment <development\|production>]` | `stages.assembly` completed with `build_fingerprint` = doctor's `derived.build_output_fingerprint.value`, `source_package_material_fingerprint` = the report's Design Source Package material fingerprint when present, `evidence.build_environment` = the `--build-environment` value when given (kept from the last record otherwise), and `stages.polish` reset to `required` (`required_by` build, `required_for` qa) unless its evidence is bound to this exact output; a completed `stages.deploy` whose `source_build_fingerprint` names other output is reset to `required` the same way, without the old probe's `outputs` and `evidence`, and its prior record is kept in `stages.deploy.history` (a deploy with no `source_build_fingerprint`, recorded before deploy stamped it, is kept) | doctor cannot compute the fingerprint (no `_site/<public_route_slug>/`), setup is still required, or `stages.setup` is not terminal |
 | `campaigns-os record polish --packet <p> --evidence <file>` | `stages.polish` from the file (`docs/polish-evidence.md` §7: completed, blocked or skipped), bound to doctor's current fingerprint; `report.theme.repair_loop_defect` when the file sets it | build is not recorded for the current output, the file has a shape error (named by field), or, for a completed status, the polish gate doctor evaluates would not pass on the result |
 | `campaigns-os record theme --packet <p>` | `report.theme`: status `applied`, `load_order` `after-next-core`, `css_path`, `commerce_pages` and per-page evidence read from each built commerce page's stylesheet links; any earlier theme waiver is cleared | build is not recorded for the current output, the campaign ships no commerce pages, a built commerce page that loads `next-core.css` does not load `brand-theme.css` (or `checkout-brand.css`) after it or links one missing from the built output, or no built commerce page loads `next-core.css` |
-| `campaigns-os record deploy --packet <p> --base-url <url>` | the packet's `deploy.preview_url` and `stages.deploy` completed with the URL in `outputs` and one evidence line per built page that answered (each page is requested under the URL first) | the packet is not `local-serve`, the URL is not a loopback origin naming the campaign's route root, a built page does not answer 2xx, polish is not recorded, the built output changed since build was recorded, or the theme gate is blocked |
+| `campaigns-os record deploy --packet <p> --base-url <url>` | the packet's `deploy.preview_url` and `stages.deploy` completed with the URL in `outputs`, one evidence line per built page that answered (each page is requested under the URL first), and `source_build_fingerprint` = the recorded `stages.assembly.build_fingerprint` it probed, so a later `record build` of different output makes deploy owed again and `next` routes back to `record deploy` before QA; a byte-identical rebuild keeps it current | the packet is not `local-serve`, the URL is not a loopback origin naming the campaign's route root, a built page does not answer 2xx, polish is not recorded, the built output changed since build was recorded, or the theme gate is blocked |
 
 Each command also refuses a stage `next` has not reached: while doctor's
 prepare-build gate is set (`next` answers prepare-build) or while an earlier

package/docs/campaign-standardization-report.md

@@ -170,12 +170,34 @@ version discovery), `checkout_fields` (every
 script evidence, and `proof_state`), `runtime_contract`, `findings`, and
 `remediation`.
 
+Three names in the field contract depend on the SDK version
+(`version_gated_aliases`): `first_name` and `last_name` from 0.4.39 and
+`phone_number` from 0.4.41. Each is `supported` only when the binding's SDK
+version is an exact release at or after that version; otherwise it is
+classified as on an earlier SDK (`first_name` and `last_name` as stale aliases,
+`phone_number` as unknown). Each binding records the `sdk_version` it was
+judged against and its `sdk_version_source`: `loader` (the file's own exact
+loader pin), `campaign` (for a file with no loader of its own, the lowest of
+the root's exact loader pins and its bundled dependency's floor: an exact pin,
+or `^`, `~` or `>=` on a released version; any other range leaves the version
+unknown), or
+`campaigns_json` (a Page Kit campaign's `sdk_version`; a shared file takes the
+lowest across campaigns). An unpinned loader or a missing pin leaves
+`sdk_version` null, judged as an earlier SDK, because `fname`, `lname` and
+`phone` work on every version.
+
 `sdk_loader.references` records pinned and unpinned loader refs alike
 (`version` is null for `@latest`/branch/commit pins, which raise
 `version.sdk_loader_unpinned` instead of a policy evaluation). Only URLs that
 point at a loader/dist artifact count; incidental `campaign-cart@x.y.z`
 strings elsewhere in source are ignored.
 
+In a static repo (no `_data/campaigns.json`), `campaigns-os sdk repin --target
+<repo> [--target-sdk <x.y.z>] [--apply]` rewrites the semver-pinned references
+in this list that are below the target version, changing only the version
+segment of each URL. It previews by default and leaves the unpinned refs
+alone. See `sdk-storage-compatibility.md`.
+
 `payment.proof_state` is one of `runtime_proof_required` (custom-control
 evidence found), `undetermined` (radios exist; static scanning cannot exclude
 externally-styled custom controls), or `not_applicable` (no `payment_method`
@@ -216,6 +238,16 @@ Page Kit root that inlines them gets the same `checkout_fields` block and the
 same `checkout.unsupported_field_binding` / `checkout.unknown_field_binding`
 findings as an application root.
 
+A bundled dependency is judged by its floor, the lowest version its
+`package.json` spec lets npm install, recorded as
+`sdk_loader.bundled_dependency.floor_version`. Only an exact pin (`0.4.30`,
+`=0.4.30`, `v0.4.30`) or one `^`, `~` or `>=` range on a released version has
+a certain floor; `^0.4.25` is evaluated as `0.4.25`. Any other spec (`<0.4.39`,
+an `||`, hyphen or x-range, a tag) has none, so it gets no evaluation and
+raises the warning `version.sdk_dependency_floor_unknown` instead; a
+prerelease pin raises `version.sdk_prerelease_pin`. `resolved_version` stays
+the version text extracted from the spec, for reference.
+
 Both are also injectable from the CLI: pass
 `--sdk-support-policy <path-to-json>` and/or `--field-contract <path-to-json>`
 to `standardize`. Each file is read and JSON-parsed

package/docs/design-source-package.md

@@ -396,9 +396,13 @@ 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.
+campaigns-os process is working on the target, then remove it. Anything else
+at the lock path (a file, a symbolic link, or a directory with no owner record
+that holds other entries) is not a lock: once the wait ends the command names
+what is there and never removes it. The holder of the lock removes staging and
+released directories beside it whose recorded owner process no longer exists.
+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

package/docs/effects.md

@@ -42,6 +42,7 @@ CLI exempts from lifecycle capture (the converse does not hold: `demo` and the
 `doctor` inspection and `doctor --no-write` skip it and write nothing but may
 send the one live campaign read): `help`, `readback`,
 `run status`, `doctor --no-live-refs` inspection, `sdk storage-check`,
+the `sdk repin` preview (without `--apply`),
 `tooling diagnose`, a refused invocation, `run-record --no-write`, and every
 `--dry-run` form on the commands that implement the flag. Everything else
 appends an entry when a journal is selected — an active run session,
@@ -160,7 +161,7 @@ Both rows are tier C, because a change makes recorded stages owed again, and eac
 
 There is **one row per command and per effect-changing flag combination**. The
 flags that change what the invocation does to the world are listed once, in
-`vocabulary.effect_changing_flags`: `--browser`, `--built`, `--dry-run`,
+`vocabulary.effect_changing_flags`: `--apply`, `--browser`, `--built`, `--dry-run`,
 `--emit-packet`, `--example`, `--force`, `--from-store`, `--list`,
 `--no-live-refs`, `--no-post-verdict`, `--no-probe`, `--no-remit`, `--no-run-session`,
 `--no-write`, `--republish`, `--test-order`, `--write`, `--write-map`. Flags

package/docs/local-setup.md

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

package/docs/orientation-contract-reference.md

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

package/docs/progress-snapshots.md

@@ -65,7 +65,9 @@ rename; a live process is never evicted. A lock directory with no owner record
 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
+retrying `next`. A file or other non-lock entry at the lock path is named in
+the warning and never removed: move it out of the way. 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

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

@@ -59,8 +59,10 @@ the toolkit runs that loop in a fixed order:
 2. **Serve and prove.** Serve `_site/` on localhost (the `next deploy` handoff
    names the directory and any root-route rewrite) and run `polish capture`
    against it. Once polish is recorded, `record deploy --packet <p> --base-url
-   <url>` records the URL on `deploy.preview_url` and the deploy stage; then run
-   `qa run --browser` and the typed-card order paths against it.
+   <url>` records the URL on `deploy.preview_url` and the deploy stage, bound
+   to the build it probed (a `record build` of different output makes it owed
+   again and keeps the old record in the deploy stage's history); then run `qa run --browser` and the typed-card order paths against
+   it.
 3. **Prove the pin on the production output.** Before committing, run
 
    ```bash
@@ -726,6 +728,16 @@ spec resolved from the portal for the run — keep publish-by-default regardless
 of consent: those verdicts are the QA tab's product surface, not telemetry.
 Explicit flags always win in both directions for saved-Map QA.
 
+A run whose base URL is a local address (`localhost` or any `*.localhost`
+name, any `127.x.x.x` address, `0.0.0.0`, `[::1]` or an IPv4-mapped loopback,
+from `--base-url` or the packet's `deploy.preview_url`) keeps its verdict local
+by default, whatever the spec source. Those runs are checks on your own
+machine, and people watching the Map's QA tab should not see them. The output
+names the destination and how to publish: `qa publish` for the stored verdict,
+or `--post-verdict` on the next run. `--post-verdict` publishes a local-address
+run, and `publish_decision.reason` reads `loopback_base_url` when the default
+kept it local.
+
 A packet with `local_spec_id` always keeps its verdict and progress local.
 `qa run` suppresses portal publication even with `--post-verdict`; the flag
 does not turn a local ID into a Map destination. `qa publish` refuses such a
@@ -1810,7 +1822,12 @@ The browser driver intentionally behaves like a user:
   proven against the persisted-order voucher read-back
 - checkout is advanced through the visible cart/checkout button
 - address autocomplete is settled or closed before submit
-- Spreedly card and CVV iframes are filled with sequential keystrokes
+- the card and CVV iframes are filled with sequential keystrokes: Spreedly's
+  iFrame fields on SDK 0.4.40 and earlier, and on 0.4.41 and later the
+  Spreedly-hosted fields that NEXT's `payments.29next.com` script mounts.
+  Typing starts once the checkout form drops `next-loading-spreedly` (the
+  fields are ready), and both fields are read back and retyped, up to three
+  attempts in all, before `card_fields_filled` passes
 - the real submit button is clicked without fabricating SDK state
 
 The intended QA order matrix is:
@@ -1962,6 +1979,14 @@ placeholder-text blocker and the other residue gates still run. The emitted
 minimal packet is marked `_synthesized` — it points doctor/QA at the built
 output and family, and is not a substitute for a real Build Packet.
 
+`doctor --built` reads the local built files only. `--base-url` is not
+fetched: it fills `deploy.preview_url` in the minimal packet, and the output
+says so (`derived.base_url.fetched: false` in JSON). A clean `doctor --built`
+run with a preview URL says nothing about the preview. To check the served
+pages, run `qa run --site <repo> --base-url <url> --family <family> --browser`.
+The emitted minimal packet does not drive packet QA: `qa resolve` and
+`qa run --packet` block on it, because it carries no local CampaignSpec.
+
 **Trade-off — non-packet QA is narrower than packet-driven QA.** It runs the
 built-output gates (residue, placeholder text, demo-asset, pricing-CSS, brand
 contract) but **skips the CampaignSpec/source-HTML-driven checks** a packet

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.53.0`.
+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.54.0`.
 
 ## What this is