@nextcommerce/campaigns-os 1.33.0 → 1.34.1

package/contracts/release-ledger.json

@@ -4593,6 +4593,261 @@
         }
       ],
       "entry_sha256": "76e84afa5f9228efd00a3f8aca8fd2a601a01955ebac370209598633ae3f790c"
+    },
+    {
+      "id": "RL-0119",
+      "sequence": 119,
+      "date": "2026-09-17",
+      "kind": "release",
+      "surface_version": "1.34.0",
+      "changelog_section": "1.34.0",
+      "changelog_sha256": "d0753f1573b293528397ff0d3bee714f6e5fdb74d94d4f19cc14066bf2720ac8",
+      "agent_impact": "New sdk storage-check command scans explicitly scoped Git-tracked HTML/JavaScript against an SDK-owned storage migration manifest. Supply target SDK version and manifest path; inspect incompatible and unknown findings before a bump. The scanner writes neither campaign files nor run journals. Reports carry file hashes and manifest provenance. Unsupported SDK versions and unresolved code cannot establish compatibility; source evidence never replaces browser/order/analytics proof. The SDK manifest is supplied explicitly while campaign-cart #102 awaits publication.",
+      "compatibility": "additive",
+      "migration": "none",
+      "changes": [
+        {
+          "class": "compatibility_policy",
+          "path": "compatibility.json",
+          "surface_entry": "compatibility.json",
+          "summary": "Package compatibility version follows supported surface 1.34.0."
+        },
+        {
+          "class": "compatibility_policy",
+          "path": "contracts/supported-surface.json",
+          "surface_entry": "contracts/supported-surface.json",
+          "summary": "Add sdk CLI command and the scanner reference to supported surface; version 1.34.0."
+        },
+        {
+          "class": "documentation",
+          "path": "docs/orientation-contract-reference.md",
+          "surface_entry": "docs/orientation-contract-reference.md",
+          "summary": "Regenerate the orientation reference for surface 1.34.0."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/runtime-readiness.md",
+          "surface_entry": "docs/runtime-readiness.md",
+          "summary": "Regenerate runtime readiness for surface 1.34.0."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/sdk-storage-compatibility.md",
+          "surface_entry": "docs/sdk-storage-compatibility.md",
+          "summary": "Document explicit manifest provenance, target version, tracked scope, statuses, exclusions and source-only evidence limits."
+        },
+        {
+          "class": "compatibility_policy",
+          "path": "docs/versioning.md",
+          "surface_entry": "docs/versioning.md",
+          "summary": "Document package and supported surface version 1.34.0."
+        },
+        {
+          "class": "generated_runtime",
+          "path": "package-lock.json",
+          "surface_entry": null,
+          "summary": "Lockfile package version follows 1.34.0; dependencies unchanged."
+        },
+        {
+          "class": "package_export",
+          "path": "package.json",
+          "surface_entry": null,
+          "summary": "Version 1.34.0 and ship the SDK storage compatibility reference."
+        },
+        {
+          "class": "cli_surface",
+          "path": "src/cli.mjs",
+          "surface_entry": "sdk",
+          "summary": "New read-only sdk storage-check dispatch, flags and report; suppress lifecycle and session writes for this inspection."
+        },
+        {
+          "class": "compatibility_policy",
+          "path": "docs/supported-surface.md",
+          "surface_entry": "docs/supported-surface.md",
+          "summary": "Document sdk storage-check as a supported CLI command."
+        }
+      ],
+      "entry_sha256": "1db46aa2c1f7fee6ebc788cb355690113e08ff0542a0494c6011f439f4fa0ba1"
+    },
+    {
+      "id": "RL-0120",
+      "sequence": 120,
+      "date": "2026-09-18",
+      "kind": "release",
+      "surface_version": "1.34.1",
+      "changelog_section": "1.34.1",
+      "changelog_sha256": "79fdc2f42ae0258ffb29a9f8950b50894386cfc38bae80ae711181f0ce5fe872",
+      "agent_impact": "Runtime recipe 1.0.2 reflects Playwright removing fsevents. Exact v1 agreement semantics remain unchanged. Browser installation uses the Playwright resolved beside Campaigns OS.",
+      "compatibility": "compatible",
+      "migration": "After a dependency update, run campaigns-os qa install-browser to install the matching Chromium.",
+      "changes": [
+        {
+          "class": "workflow",
+          "path": ".github/workflows/ci.yml",
+          "surface_entry": null,
+          "summary": "Require independent types, unit, contracts, browser and consumer-install proof behind check."
+        },
+        {
+          "class": "named_surface",
+          "path": "contracts/fixtures/runtime-recipe/accept/current.json",
+          "surface_entry": "contracts/fixtures/runtime-recipe/accept/current.json",
+          "summary": "Regenerate recipe fixtures against revision 1.0.2 and surface 1.34.1."
+        },
+        {
+          "class": "named_surface",
+          "path": "contracts/fixtures/runtime-recipe/accept/minimal.json",
+          "surface_entry": "contracts/fixtures/runtime-recipe/accept/minimal.json",
+          "summary": "Regenerate recipe fixtures against revision 1.0.2 and surface 1.34.1."
+        },
+        {
+          "class": "named_surface",
+          "path": "contracts/fixtures/runtime-recipe/reject/advisory-enforcement.json",
+          "surface_entry": "contracts/fixtures/runtime-recipe/reject/advisory-enforcement.json",
+          "summary": "Regenerate recipe fixtures against revision 1.0.2 and surface 1.34.1."
+        },
+        {
+          "class": "named_surface",
+          "path": "contracts/fixtures/runtime-recipe/reject/allowlist-without-hosts.json",
+          "surface_entry": "contracts/fixtures/runtime-recipe/reject/allowlist-without-hosts.json",
+          "summary": "Regenerate recipe fixtures against revision 1.0.2 and surface 1.34.1."
+        },
+        {
+          "class": "named_surface",
+          "path": "contracts/fixtures/runtime-recipe/reject/committed-output-claim.json",
+          "surface_entry": "contracts/fixtures/runtime-recipe/reject/committed-output-claim.json",
+          "summary": "Regenerate recipe fixtures against revision 1.0.2 and surface 1.34.1."
+        },
+        {
+          "class": "named_surface",
+          "path": "contracts/fixtures/runtime-recipe/reject/engines-disagreement-warns.json",
+          "surface_entry": "contracts/fixtures/runtime-recipe/reject/engines-disagreement-warns.json",
+          "summary": "Regenerate recipe fixtures against revision 1.0.2 and surface 1.34.1."
+        },
+        {
+          "class": "named_surface",
+          "path": "contracts/fixtures/runtime-recipe/reject/lifecycle-scripts-enabled.json",
+          "surface_entry": "contracts/fixtures/runtime-recipe/reject/lifecycle-scripts-enabled.json",
+          "summary": "Regenerate recipe fixtures against revision 1.0.2 and surface 1.34.1."
+        },
+        {
+          "class": "named_surface",
+          "path": "contracts/fixtures/runtime-recipe/reject/missing-required-field.json",
+          "surface_entry": "contracts/fixtures/runtime-recipe/reject/missing-required-field.json",
+          "summary": "Regenerate recipe fixtures against revision 1.0.2 and surface 1.34.1."
+        },
+        {
+          "class": "named_surface",
+          "path": "contracts/fixtures/runtime-recipe/reject/unknown-kind.json",
+          "surface_entry": "contracts/fixtures/runtime-recipe/reject/unknown-kind.json",
+          "summary": "Regenerate recipe fixtures against revision 1.0.2 and surface 1.34.1."
+        },
+        {
+          "class": "named_surface",
+          "path": "contracts/fixtures/runtime-recipe/reject/unknown-network-policy.json",
+          "surface_entry": "contracts/fixtures/runtime-recipe/reject/unknown-network-policy.json",
+          "summary": "Regenerate recipe fixtures against revision 1.0.2 and surface 1.34.1."
+        },
+        {
+          "class": "named_surface",
+          "path": "contracts/fixtures/runtime-recipe/reject/unknown-output-check.json",
+          "surface_entry": "contracts/fixtures/runtime-recipe/reject/unknown-output-check.json",
+          "summary": "Regenerate recipe fixtures against revision 1.0.2 and surface 1.34.1."
+        },
+        {
+          "class": "named_surface",
+          "path": "contracts/fixtures/runtime-recipe/reject/unknown-revision.json",
+          "surface_entry": "contracts/fixtures/runtime-recipe/reject/unknown-revision.json",
+          "summary": "Regenerate recipe fixtures against revision 1.0.2 and surface 1.34.1."
+        },
+        {
+          "class": "named_surface",
+          "path": "contracts/fixtures/runtime-recipe/reject/unknown-step-id.json",
+          "surface_entry": "contracts/fixtures/runtime-recipe/reject/unknown-step-id.json",
+          "summary": "Regenerate recipe fixtures against revision 1.0.2 and surface 1.34.1."
+        },
+        {
+          "class": "named_surface",
+          "path": "contracts/fixtures/runtime-recipe/reject/unperformable-check-skipped.json",
+          "surface_entry": "contracts/fixtures/runtime-recipe/reject/unperformable-check-skipped.json",
+          "summary": "Regenerate recipe fixtures against revision 1.0.2 and surface 1.34.1."
+        },
+        {
+          "class": "named_surface",
+          "path": "contracts/fixtures/runtime-recipe/reject/unpinned-lockfile.json",
+          "surface_entry": "contracts/fixtures/runtime-recipe/reject/unpinned-lockfile.json",
+          "summary": "Regenerate recipe fixtures against revision 1.0.2 and surface 1.34.1."
+        },
+        {
+          "class": "hashed_surface",
+          "path": "contracts/runtime-recipe.campaigns-os-node-v1.json",
+          "surface_entry": "contracts/runtime-recipe.campaigns-os-node-v1.json",
+          "summary": "Advance recipe to 1.0.2 with an empty exact install-script dependency expectation."
+        },
+        {
+          "class": "compatibility_policy",
+          "path": "contracts/supported-surface.json",
+          "surface_entry": "contracts/supported-surface.json",
+          "summary": "Advance the supported surface to 1.34.1 and refresh the runtime recipe hash."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/qa-and-test-orders.md",
+          "surface_entry": "docs/qa-and-test-orders.md",
+          "summary": "Document runtime recipe 1.0.2 and package-owned browser installation and validation."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/runtime-readiness.md",
+          "surface_entry": "docs/runtime-readiness.md",
+          "summary": "Document runtime recipe 1.0.2 and package-owned browser installation and validation."
+        },
+        {
+          "class": "generated_runtime",
+          "path": "package-lock.json",
+          "surface_entry": null,
+          "summary": "Lock reviewed dependency updates and remove the retired fsevents install script."
+        },
+        {
+          "class": "package_export",
+          "path": "package.json",
+          "surface_entry": null,
+          "summary": "Validate Playwright 1.63 and YAML 2.9.1; expose independent CI checks and automatic unit-test discovery."
+        },
+        {
+          "class": "documentation",
+          "path": "docs/orientation-contract-reference.md",
+          "surface_entry": "docs/orientation-contract-reference.md",
+          "summary": "Regenerate the orientation reference for supported surface 1.34.1."
+        }
+      ],
+      "entry_sha256": "e7bb42ad4d748d9fefed5d15a9cef195638f465cf7e93cff2892fde3bd72a1c5"
+    },
+    {
+      "id": "RL-0121",
+      "sequence": 121,
+      "date": "2026-09-18",
+      "kind": "release",
+      "surface_version": null,
+      "changelog_section": "1.34.1+agent.1",
+      "changelog_sha256": "8b3ea071381418b1516d5e02d4b6b26ce39e7b9f4c0b0fc8ff5b3e05a841ae39",
+      "agent_impact": "HTML parsing uses parse5 8.0.1 and entities 8.1.0. Existing ESM imports and the declared Node >=20.19.0 minimum remain compatible. No consumer action is required.",
+      "compatibility": "compatible",
+      "migration": "none",
+      "changes": [
+        {
+          "class": "package_export",
+          "path": "package.json",
+          "surface_entry": null,
+          "summary": "Upgrade parse5 to ^8.0.1 without changing package exports or the supported Node range."
+        },
+        {
+          "class": "generated_runtime",
+          "path": "package-lock.json",
+          "surface_entry": null,
+          "summary": "Lock parse5 8.0.1 and entities 8.1.0 as the reviewed HTML parser dependencies."
+        }
+      ],
+      "entry_sha256": "ae6ef7c17e02e52cad5ba4faa1e4adf8ba3bba375acac36e3e9046d8273c053f"
     }
   ]
 }

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

@@ -3,7 +3,7 @@
   "_growth_note": "When a bound below is genuinely reached, the answer is to find out why before raising it. A dependency install that exceeds its bound on a warm machine is a supply-chain change, not a slow morning; an output inventory that exceeds its file or byte bound is a build that went wrong, not a package that grew 50x overnight. Raising a bound is the fallback, it advances recipe_revision, and it owes a release-ledger entry. Widening the accepted npm range follows the same path, and its trigger is external and checkable: widen when a Node release line ships that npm major by default, not when a particular machine happens to have it installed.",
   "schema": "campaigns-os-runtime-recipe/v1",
   "recipe_kind": "campaigns-os-node-v1",
-  "recipe_revision": "1.0.1",
+  "recipe_revision": "1.0.2",
   "refusal_reason_code": "runtime_recipe_refused",
   "fail_closed": true,
   "unperformable_check_disposition": "failed",
@@ -84,7 +84,7 @@
       "stdin": "closed",
       "lifecycle_scripts": "disabled",
       "timeout_bound": "install_seconds",
-      "rationale": "ci rather than install, so the lockfile is authoritative and the tree is reproducible. --ignore-scripts is the load-bearing flag: it suppresses every dependency lifecycle script and the target's own prepare. Exactly one dependency in the resolved tree declares an install script, and it ships a prebuilt binary in its published tarball, so nothing in the tree needs its scripts to function. --no-audit and --fund=false remove two network- and output-side effects that are not part of preparing a runtime."
+      "rationale": "ci rather than install, so the lockfile is authoritative and the tree is reproducible. --ignore-scripts is the load-bearing flag: it suppresses every dependency lifecycle script and the target's own prepare. No dependency in the resolved tree declares an install script. The exact list in target_expectations remains a reviewed expectation: additions and removals require a recipe revision, so existing v1 consumers retain the same agreement semantics. --no-audit and --fund=false remove two network- and output-side effects that are not part of preparing a runtime."
     },
     {
       "id": "build",
@@ -286,9 +286,7 @@
       "build:spec": "tsc -p campaign-spec/tsconfig.build.json",
       "prepare": "npm run build:spec"
     },
-    "install_script_dependencies": [
-      "fsevents"
-    ]
+    "install_script_dependencies": []
   },
   "capabilities": {
     "_note": "What a generation prepared by this recipe can and cannot do. Stated explicitly because 'runtime ready' invites the wrong reading: the same flag that makes the install safe also means the prepared generation has no browser to drive. Preparing a runtime and being able to run browser QA are different readiness questions, and this recipe answers only the first.",

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 \u2014 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 \u2014 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) \u2014 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.33.0",
+  "surface_version": "1.34.1",
   "package_exports": [
     "./commercial-journey",
     "./commercial-parity",
@@ -23,6 +23,7 @@
     "checkpoint",
     "page-kit",
     "spec",
+    "sdk",
     "doctor",
     "bundle",
     "next",
@@ -43,7 +44,7 @@
       "sha256": "f5097f6cccaf211d442c1ebc584d2c76d5a07a44e587df130de02117a9412db0"
     },
     "contracts/runtime-recipe.campaigns-os-node-v1.json": {
-      "sha256": "f06944b37ddbcfc6353ebc01dbc1eaf9ee5ebe3dbc91609214e25252905915ff"
+      "sha256": "90aaaaade90cf2525ea1aa05be5cb2d02b57e6e59f9278a946efa8a087946fd3"
     },
     "schemas/campaign-build-brief.v1.schema.json": {
       "sha256": "d524003184131398dc15fdb84385af1be0de0c69d6c5ede7278689a5b6101b81"
@@ -175,6 +176,7 @@
     "contracts/fixtures/runtime-recipe/reject/missing-required-field.json",
     "contracts/fixtures/orientation/hostile-target/repo/bin/intended.mjs",
     "contracts/fixtures/orientation/hostile-target/repo/hostile-dependency-tripwire/package.json",
-    "contracts/fixtures/orientation/hostile-target/repo/hostile-dependency-tripwire/tripwire.mjs"
+    "contracts/fixtures/orientation/hostile-target/repo/hostile-dependency-tripwire/tripwire.mjs",
+    "docs/sdk-storage-compatibility.md"
   ]
 }

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.33.0`
+Supported surface at generation time: `1.34.1`
 
 ## Forward compatibility
 
@@ -228,6 +228,7 @@ so a renamed command fails here as well as at the supported-surface gate.
 - `campaigns-os checkpoint`
 - `campaigns-os page-kit`
 - `campaigns-os spec`
+- `campaigns-os sdk`
 - `campaigns-os doctor`
 - `campaigns-os bundle`
 - `campaigns-os next`

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

@@ -1689,3 +1689,29 @@ meta assertions to avoid duplicating their values into the verdict.
 Older verdicts lacking this assertion were not checked. Consumers must retain
 run/time/spec-hash context and segregate server-stamped untrusted submissions;
 a trusted submission attests the runner, not execution or resource identity.
+
+### Playwright updates and consumer installs
+
+After installing or updating Campaigns OS, run `npx campaigns-os qa install-browser`
+from the campaign project (or `campaigns-os qa install-browser` for a global
+installation). This resolves the same Playwright package as QA and polish capture.
+A project's own `npx playwright install` can resolve a different version and install
+a different Chromium build. Campaigns OS is an optional-dependency owner, not a
+Playwright peer dependency: npm may share a compatible copy or install a nested one.
+The consumer project's lockfile determines its installed version; this repository's
+lockfile only controls checkout builds.
+
+CI reports independent types, unit, contracts, and browser lanes under the existing
+required `check` status. `npm run check:browser` requires working Chromium and fails
+on launch errors. `npm run check:consumer` installs the packed package into fresh
+projects with a shared Playwright, an older conflicting version, and `latest`, then
+installs and launches Campaigns OS's Chromium. These checks use local fixture pages;
+they do not place merchant orders. `npm run check` remains the browser-free contributor
+check; run the browser commands separately after installing Chromium.
+
+Dependency PRs must include any required release-ledger entries. If the set of
+install-script dependencies changes, update the runtime recipe's exact expectation,
+advance its revision and the supported-surface/package patch version, and regenerate
+the runtime-readiness guide and fixtures. The v1 recipe still uses exact agreement:
+removing a dependency does not authorize silently reinterpreting that field as an
+allowlist. Dependabot groups minor/patch updates; major API upgrades remain separate.

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.1`, validated by `schemas/campaigns-os-runtime-recipe.v1.schema.json` (`Campaigns OS Runtime Recipe v1`). Supported surface at generation time: `1.33.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.34.1`.
 
 ## What this is
 
@@ -65,7 +65,7 @@ npm ci --ignore-scripts --no-audit --fund=false
 
 Working directory `target_root`, stdin `closed`, lifecycle scripts `disabled`, bounded by `install_seconds`.
 
-ci rather than install, so the lockfile is authoritative and the tree is reproducible. --ignore-scripts is the load-bearing flag: it suppresses every dependency lifecycle script and the target's own prepare. Exactly one dependency in the resolved tree declares an install script, and it ships a prebuilt binary in its published tarball, so nothing in the tree needs its scripts to function. --no-audit and --fund=false remove two network- and output-side effects that are not part of preparing a runtime.
+ci rather than install, so the lockfile is authoritative and the tree is reproducible. --ignore-scripts is the load-bearing flag: it suppresses every dependency lifecycle script and the target's own prepare. No dependency in the resolved tree declares an install script. The exact list in target_expectations remains a reviewed expectation: additions and removals require a recipe revision, so existing v1 consumers retain the same agreement semantics. --no-audit and --fund=false remove two network- and output-side effects that are not part of preparing a runtime.
 
 ### build
 
@@ -170,7 +170,7 @@ What this revision assumes about the target, stated as values a checker can comp
 | Lockfile | `package-lock.json`, version `3`, integrity pinned `true` |
 | Script `build:spec` | `tsc -p campaign-spec/tsconfig.build.json` |
 | Script `prepare` | `npm run build:spec` |
-| Dependencies declaring an install script | `fsevents` |
+| Dependencies declaring an install script | none |
 
 ## Bounds
 

package/docs/sdk-storage-compatibility.md

@@ -0,0 +1,19 @@
+# SDK storage compatibility before a bump
+
+Run the read-only source scanner from a campaign repository before changing its SDK pin:
+
+```sh
+npx campaigns-os sdk storage-check --target . --target-sdk 0.4.38 --manifest /path/to/campaign-cart/docs/compatibility/storage-migrations.v1.json --scope campaigns/spring,shared --json
+```
+
+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.
+
+`--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.
+
+Acorn parses JavaScript ASTs; parse5 identifies executable inline HTML scripts and source offsets. Findings inventory storage area, operation, key, file/line/column, reason, and SDK-owned public replacement when supplied. The scanner recognizes direct `localStorage`/`sessionStorage`, `window`/`globalThis`/`self` properties, simple constant browser-global/storage aliases and storage destructuring, literal `getItem`/`setItem`/`removeItem` calls (including bracket method notation), property access/assignment/deletion, and lexical constant string indirection. Comments, ordinary strings, JSON script blocks and public store calls do not become storage reads. A literal legacy SDK key at or after its manifest migration boundary is incompatible. Guessed prefixes cannot establish compatibility.
+
+Dynamic storage keys, unresolved storage methods, shadowed storage names, missing migration release evidence, unsupported target versions, and JavaScript parse failures report unknown. This bounded analysis does not execute merchant code or prove computed keys correct. It does not follow arbitrary data flow, dynamic imports, event-handler attributes, generated code or runtime-loaded script graphs. Inspect unresolved findings and include all campaign sources in scope; a clean result is only static tracked source compatibility evidence. Browser behavior, order creation, tracking and analytics still require their own proof, especially where multiple campaigns share an origin. Use the SDK public store API where the manifest recommends it; do not invent a prefix-first merchant repair.
+
+Storage `length` property reads are unaffected metadata (`storage-metadata-read`). Storage `key()` enumeration, extracted method references, and mutations of reserved members remain unknown; enumeration cannot prove an SDK key lookup safe. Git discovery failures return one bounded CLI error. Local script diagnostics retain repository-relative spellings from HTML source, including `../` paths; excluded/outside sources are not read. The Git root and operator target are compared by filesystem device/inode identity, so supported case aliases and symlinks can name the same root. Source containment uses realpaths below the Git root without case folding. Extra positional CLI arguments are rejected so an accidental scope or version value cannot silently disappear.

package/docs/supported-surface.md

@@ -14,7 +14,8 @@ 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` | 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` | 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. |
+| `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. |
 | Package exports `./commercial-journey` and `./commercial-parity` | Portable scenario planning, response normalization, contract-governed source extraction, Exact-only parity comparison, and deterministic QA assertion serialization. These modules own no network transport and do not calculate prices locally. | Consumers execute descriptors through a supported calculate transport, then pass captured envelopes into the pure normalizer. Existing export paths are gated and may not be renamed or removed without a breaking surface change. |

package/docs/versioning.md

@@ -2,7 +2,7 @@
 
 This repo uses independent compatibility versions:
 
-- package version: `1.33.0` — equals `surface_version` in
+- package version: `1.34.0` — equals `surface_version` in
   `contracts/supported-surface.json` (`check:supported-surface` enforces it)
   and is the version published to the npm registry; `+agent.N` changelog
   sections are same-surface changes and are not published on their own

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextcommerce/campaigns-os",
-  "version": "1.33.0",
+  "version": "1.34.1",
   "description": "Toolkit for agent-assisted NEXT campaign builds.",
   "license": "Apache-2.0",
   "repository": {
@@ -60,7 +60,7 @@
     "prepare": "npm run build:spec",
     "check:spec": "node --test \"campaign-spec/test/**/*.test.ts\"",
     "check": "npm run check:provenance && npm run check:workflows && npm run check:changelog-structure && npm run build:spec && npm run check:tests && npm run check:spec && npm run check:fixtures && npm run check:legacy-migration && npm run check:spec-conformance && npm run check:private-strings && npm run check:template-doctrine && npm run check:slot-manifest && npm run check:skill-versions && npm run check:cart-readiness && npm run check:sidecar-bundle && npm run check:supported-surface && npm run check:release-ledger && npm run check:runtime-recipe && npm run check:orientation-docs && npm run check:runtime-docs && npm run check:pack -- --skip-prepare",
-    "check:tests": "node --test ./src/*.test.mjs ./scripts/refresh-starter-template-catalog.test.mjs ./scripts/check-catalog-provenance.test.mjs ./scripts/check-workflow-contracts.test.mjs ./scripts/check-changelog-structure.test.mjs ./scripts/check-slot-manifest.test.mjs ./scripts/check-skill-versions.test.mjs ./scripts/check-supported-surface.test.mjs ./scripts/check-campaign-spec-conformance.test.mjs ./scripts/check-release-ledger.test.mjs ./scripts/generate-orientation-reference.test.mjs ./scripts/check-runtime-recipe.test.mjs ./scripts/check-fixtures.test.mjs ./scripts/starter-templates-path.test.mjs ./scripts/check-template-doctrine.test.mjs",
+    "check:tests": "node ./scripts/check-tests.mjs",
     "check:legacy-migration": "node ./scripts/check-legacy-migration.mjs",
     "check:fixtures": "node ./scripts/check-fixtures.mjs",
     "check:spec-conformance": "node ./scripts/check-campaign-spec-conformance.mjs",
@@ -80,7 +80,10 @@
     "check:runtime-recipe": "node ./scripts/check-runtime-recipe.mjs",
     "check:runtime-docs": "node ./scripts/generate-runtime-readiness.mjs --check",
     "generate:runtime-docs": "node ./scripts/generate-runtime-readiness.mjs --write",
-    "check:sidecar-bundle": "node ./bin/campaigns-os.mjs bundle check --packet contracts/fixtures/sidecar-bundle/production-shaped/campaign-runtime.build.json --require-qa --json"
+    "check:sidecar-bundle": "node ./bin/campaigns-os.mjs bundle check --packet contracts/fixtures/sidecar-bundle/production-shaped/campaign-runtime.build.json --require-qa --json",
+    "check:browser": "node ./scripts/check-tests.mjs --browser",
+    "check:consumer": "node ./scripts/check-playwright-consumer.mjs",
+    "check:contracts": "npm run check:provenance && npm run check:workflows && npm run check:changelog-structure && npm run check:fixtures && npm run check:legacy-migration && npm run check:spec-conformance && npm run check:private-strings && npm run check:template-doctrine && npm run check:slot-manifest && npm run check:skill-versions && npm run check:cart-readiness && npm run check:sidecar-bundle && npm run check:supported-surface && npm run check:release-ledger && npm run check:runtime-recipe && npm run check:orientation-docs && npm run check:runtime-docs"
   },
   "engines": {
     "node": ">=20.19.0"
@@ -88,11 +91,11 @@
   "dependencies": {
     "acorn": "^8.18.0",
     "ajv": "^8.20.0",
-    "parse5": "^7.3.0",
-    "yaml": "^2.9.0"
+    "parse5": "^8.0.1",
+    "yaml": "^2.9.1"
   },
   "optionalDependencies": {
-    "playwright": "^1.62.1"
+    "playwright": "^1.63.0"
   },
   "devDependencies": {
     "typescript": "^5.9.3"
@@ -130,6 +133,7 @@
     "CONTEXT.md",
     "compatibility.json",
     "AGENTS.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "docs/sdk-storage-compatibility.md"
   ]
 }

package/src/cli.mjs

@@ -459,6 +459,7 @@ Usage:
   campaigns-os doctor --packet <campaign-runtime.build.json> [--context <json>] [--report <json>] [--strip-paths] [--write] [--no-write] [--doctor-out <path>] [--json]   # inspection by default; --doctor-out requires --write; --no-write wins
   campaigns-os doctor --built <page-kit-target-repo> --family <family> [--slug <slug>] [--base-url <url>] [--emit-packet [path]] [--json]   # L7: doctor a built _site/ with no Build Packet
   campaigns-os bundle check --packet <campaign-runtime.build.json> [--require-qa] [--json]   # validate the canonical migration/readback JSON bundle; never substitutes markdown
+  campaigns-os sdk storage-check --target <git-root> --target-sdk <x.y.z> --manifest <SDK-manifest.json> --scope <dir,file> [--exclude <dir,file>] [--json]
   campaigns-os standardize --target <campaign-repo> [--family <family>] [--slug <slug>] [--sdk-support-policy <path.json>] [--field-contract <path.json>] [--no-doctor] [--json]
   campaigns-os theme inspect --packet <campaign-runtime.build.json> [--context <json>] [--theme-policy <inspect_only|auto|off>] [--json]
   campaigns-os theme generate --packet <campaign-runtime.build.json> [--context <json>] [--out-dir <dir>] [--force] [--json]
@@ -608,7 +609,8 @@ export async function main(argv) {
   // run never inherits an old run_id — but an ignored session was also an
   // abandoned one: nine of them were found lingering with no Run Record and
   // nothing remitted. Closing out is best-effort and never blocks the command.
-  const sweptStale = await closeOutStaleRunSessions(command, args);
+  const storageInspection = command === "sdk" && args._[1] === "storage-check";
+  const sweptStale = storageInspection ? [] : await closeOutStaleRunSessions(command, args);
   const ambient = ambientRunSession(args);
 
   // Wrap every command in the lifecycle instrumentation (T6): it captures the
@@ -757,7 +759,7 @@ function resolveLifecycleJournal(args, { ambient = null, fallbackDir = null } =
 // not break a command (telemetry never blocks a build). `help` is a no-op
 // command and is not worth recording.
 function persistLifecycleIfRequested(args, command, lifecycle, sessionHolder) {
-  if (command === "help") return;
+  if (command === "help" || (command === "sdk" && args._[1] === "storage-check")) return;
   // An inspection must not append to a delivered campaign's active run either.
   if (command === "doctor" && args.packet && (args.write !== true || args["no-write"] === true)) return;
   const ambient = sessionHolder?.current || null;
@@ -1060,6 +1062,24 @@ async function dispatch(command, args, recorder = NOOP_RECORDER, ambient = null,
     return;
   }
 
+  if (command === "sdk") {
+    if (args._[1] !== "storage-check" || args._.length !== 2) throw new Error("Use: campaigns-os sdk storage-check --target <git-root> --target-sdk <x.y.z> --manifest <SDK-manifest.json> --scope <dir,file> [--exclude <dir,file>] [--json].");
+    const known = new Set(["_", "target", "target-sdk", "manifest", "scope", "exclude", "json"]);
+    if (args.json !== undefined && args.json !== true) throw new Error("--json is a boolean flag and takes no value.");
+    for (const key of Object.keys(args)) if (!known.has(key)) throw new Error(`Unknown SDK storage-check flag: --${key}`);
+    const { scanSdkStorageCompatibility, formatStorageCompatibilityReport } = await import("./sdk-storage-compatibility.mjs");
+    const result = scanSdkStorageCompatibility({
+      cwd: requireArg(args, "target"),
+      targetSdkVersion: requireArg(args, "target-sdk"),
+      manifestPath: requireArg(args, "manifest"),
+      scope: requireArg(args, "scope").split(","),
+      exclude: args.exclude === undefined ? [] : requireArg(args, "exclude").split(","),
+    });
+    console.log(args.json ? JSON.stringify(result, null, 2) : formatStorageCompatibilityReport(result));
+    process.exitCode = result.status === "source-compatible" ? 0 : 2;
+    return;
+  }
+
   if (command === "standardize") {
     const result = standardizationReportCommand(args);
     writeStandardizationReportResult(result, args);