@nextcommerce/campaigns-os 1.33.0 → 1.37.1

package/docs/progress-snapshots.md

@@ -0,0 +1,142 @@
+# Minimal progress observations
+
+Candidate release **1.36.0** adds the portable `@nextcommerce/campaigns-os/progress`
+export and `schemas/campaigns-os-progress-snapshot.v0.schema.json`. The currently
+published install example does not include this feature. Progress is a compact
+observation of the existing lifecycle, not a second workflow or proof of readiness.
+
+`next --packet <packet>` records the canonical picker result after the same doctor
+checks that supply its continuation and gates. Agents run `next` after setup,
+assembly, polish and preview deployment so those committed stage reports become
+visible. The CLI `build` command prepares inputs and runs doctor; it does not build
+or deploy the campaign. Preview's existing stage is `deploy`. Arbitrary edits are
+not tracked. `qa run --packet <packet>` observes its successfully committed or
+unchanged QA report before the existing closeout: ready QA closes its run once,
+blocked QA keeps it open. A progress delivery cannot close a run.
+
+## What is shared
+
+The strict v0 object carries its schema, package version, observation timestamp,
+producer (`next` or `qa`), opaque progress stream and sequence, prior snapshot ID,
+content digest, Map ID and separate revision/spec/build hashes. Six independent
+stage records retain observed status and explicit build binding. Continuation
+retains the canonical stage, blocked/divergent flags, fixed action IDs and gate
+states. Preview carries only presence and a hash of the URL. An optional QA block
+retains the exact verdict ID, disposition (including `ready_with_exceptions`),
+binding and publication state. Publication failure does not invalidate a locally
+retained verdict; recovery uses `qa publish`, without repeating an order.
+
+No commands, prompts, free text, content, local paths, URLs, query strings,
+credentials, order values or customer payloads enter the wire. Unknown vocabulary
+becomes a fixed `unknown` marker and cannot imply a passing continuation. A
+stage's observed `completed` status is a ledger claim, not independent verification.
+Only matching fingerprints carry `matching`; absent or unverifiable binding is
+`unconfirmed`. A current local output hash never proves a deployment is current.
+
+The identity algorithms are deliberately different:
+
+- `map-store-v1` retains the original saved Map hash. A fresh Map fetch records
+  that hash and the fetched local semantic baseline in Build Context intake.
+  Saved revision alignment is `aligned` only while the local spec still matches
+  that baseline and the context names this packet and Map. Existing contexts,
+  offline caches and local exports without that provenance remain `unconfirmed`.
+  The saved hash may still be retained as identity; it alone proves no alignment.
+- `campaign-spec-material-v1` hashes recursively key-sorted JSON after removing
+  top-level `spec_identity`, `slug`, `map_id` and `saved_at`, as existing
+  `specMaterialHash` does. It includes lifecycle and parent Map fields that the
+  saved Map producer excludes. It must never be compared as a Map-store hash.
+  Assembly Report `identity.spec_hash` is a raw-byte hash and is not this value.
+- `sha256-manifest/v1` is the existing doctor's output fingerprint: SHA-256 of
+  the sorted relative-path and file-SHA-256 manifest under the built route.
+  Reported assembly/QA binding uses the doctor's actual observed output and its
+  recorded-fingerprint comparison. Missing output remains nullable/unconfirmed.
+
+Different Map revisions, local specs, builds, packet/context/report bindings and
+endpoint scopes have independent streams. Completed stages cannot be combined
+across them. A progress stream is independent of a run-session ID.
+
+## Capture and delivery
+
+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.
+
+An unchanged projection reuses its ID, timestamp and sequence. Identity
+changes start a new stream. Each local scope retains at most 32 snapshots and
+separate remit metadata; retention can leave an incomplete history. There is no
+daemon. A later observation retries its current pending delivery; old pending
+snapshots remain in the bounded local history, without background sends.
+
+`--no-write` disables both capture and delivery. `--no-remit` keeps capture local.
+`--no-run-session` does not start a session. A missing/invalid Map ID keeps the
+observation local with `map_id_missing`; a missing campaign key similarly yields
+`campaign_key_missing`. Capture or delivery failures never alter the lifecycle
+result or exit status.
+Capture may wait up to 1.5 seconds for allocation. Delivery is awaited within
+its separate two-second network budget. Unchanged lifecycle results mean the
+command's output and status remain unchanged; these bounded waits can add latency.
+
+The planned ops receiver is `POST /api/progress`. Destination precedence is an
+explicit `--proxy-base`, then the bound Build Context's `intake.proxy_base`, then
+the canonical NEXT endpoint only when there is no source binding. An invalid or
+foreign source binding fails closed, including a context without a nonempty
+matching packet pointer. An explicit endpoint override remains independent of
+that context, and cannot confirm its saved revision.
+
+HTTPS and plain HTTP loopback are accepted;
+userinfo, query, fragment and other protocols are refused. Redirects are refused.
+The existing campaign-key resolver supplies `X-Campaign-Key`; keys never enter
+snapshots or metadata.
+
+The same telemetry on/off choice governs sharing. Canonical delivery defaults on;
+explicit off, malformed environment/configuration and scope mismatch keep delivery
+off. Consent off still permits the sanitized local capture and sends no request.
+Noncanonical progress delivery requires an explicit matching scoped file
+opt-in (`telemetry on --proxy-base <endpoint>`). Unlike existing Run Record remit,
+unscoped environment ON cannot bypass scope for progress; it yields
+`scoped_consent_required`. Minimal stage observations are intended to be visible
+in Workspace. This producer does not implement the receiver or Workspace UI.
+
+Delivery uses a total two-second budget, at most one initial request and one retry
+for transport errors, 429 or 5xx. Both requests use identical canonical JSON bytes,
+ID and timestamp. A response body is bounded to 4 KiB. A 2xx or 409 succeeds only
+with `{ "ok": true, "snapshot_id": "<id>", "digest": "<same-id>" }`. Other
+400/401/403/409 answers and nonmatching acknowledgments remain failed; a conflict
+never silently counts as stored. Response error text is never copied to metadata.
+
+## Portable consumption
+
+```js
+import {
+  verifyProgressSnapshot, groupProgressHistories, progressStorageKey,
+} from '@nextcommerce/campaigns-os/progress';
+
+const checked = await verifyProgressSnapshot(snapshot);
+const histories = await groupProgressHistories(snapshots);
+const key = progressStorageKey(snapshot, scopeHash);
+```
+
+The export uses standard Web Crypto and TextEncoder; it has no Node, filesystem
+or network dependency. `validateProgressSnapshot` checks bounded strict shape and
+binding invariants; `verifyProgressSnapshot` also verifies the content digest.
+`snapshot_id` hashes recursively key-sorted JSON of every field except itself.
+Canonical transport JSON includes the ID, with no whitespace or newline.
+The exported schema and supported example fixture agree byte-for-byte in tests.
+
+`groupProgressHistories` accepts at most 256 snapshots, groups whole observations
+by complete identity plus stream, removes exact duplicate IDs and sorts sequences.
+Groups are `conflicted`, `incomplete`, `unconfirmed` or `observed`. It neither
+chooses a lifecycle stage nor merges completion claims. `observed` confers no
+receiver trust or readiness. Invalid members are rejected with fixed reason codes.
+
+The planned immutable receiver key is
+`progress:v0:<scope-hex>:<map-id>:<revision-hex>:<stream>:<sequence>:<digest-hex>`.
+`progressStorageKey` returns null without a valid shape, scope hash, Map or saved
+revision. A key match identifies scope; it is not authentication or trust. The
+receiver must verify the digest and authorized Map scope and stamp its own trust.
+Unknown, incomplete or conflicted histories must never yield a ready workspace.

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.37.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`, `demo` | 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. |
@@ -81,3 +82,15 @@ the package a consumer installs."
    the PR body — downstream pins (Campaigns Agent context spine, ops-repo
    `public-contracts.manifest.json`) update on their own cadence against a
    version they can see move.
+
+Candidate 1.36.0 adds the portable `./progress` export, its strict v0 JSON schema,
+[progress observation reference](progress-snapshots.md), and supported example
+fixture. Observations preserve canonical continuation and separate Map/spec/build
+identities; consumers must not treat history presence or scope-key matching as
+readiness or trust.
+
+Candidate 1.37.0 adds the `demo` CLI command, [offline sample reference](demo-preview.md),
+a hashed `demo/apollo-v0/provenance.json` and named attribution notice. The command
+exclusively creates a new target with validated inert pages. Its internal static
+files are covered by the provenance output hashes; they are not independent
+consumer interfaces. No campaign proof or session authority is granted.

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.37.1",
   "description": "Toolkit for agent-assisted NEXT campaign builds.",
   "license": "Apache-2.0",
   "repository": {
@@ -47,7 +47,12 @@
     "./schemas/campaigns-os-legacy-migration-inventory.v0.schema.json": "./schemas/campaigns-os-legacy-migration-inventory.v0.schema.json",
     "./schemas/campaigns-os-legacy-provisioning-plan.v0.schema.json": "./schemas/campaigns-os-legacy-provisioning-plan.v0.schema.json",
     "./schemas/campaigns-os-legacy-provisioning-receipt.v0.schema.json": "./schemas/campaigns-os-legacy-provisioning-receipt.v0.schema.json",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./progress": {
+      "import": "./src/progress.mjs",
+      "default": "./src/progress.mjs"
+    },
+    "./schemas/campaigns-os-progress-snapshot.v0.schema.json": "./schemas/campaigns-os-progress-snapshot.v0.schema.json"
   },
   "scripts": {
     "campaigns-os": "node ./bin/campaigns-os.mjs",
@@ -60,7 +65,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 +85,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 +96,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 +138,12 @@
     "CONTEXT.md",
     "compatibility.json",
     "AGENTS.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "docs/sdk-storage-compatibility.md",
+    "docs/activation-and-evidence.md",
+    "docs/diagnostics.md",
+    "docs/progress-snapshots.md",
+    "demo",
+    "docs/demo-preview.md"
   ]
 }

package/schemas/campaign-runtime-build-context.v0.schema.json

@@ -24,6 +24,48 @@
       },
       "description": "Context-relative reference to the normalized Design Source Package. sha256 hashes the exact artifact bytes; material_fingerprint drives freshness gates."
     },
+    "intake": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "saved_map_revision": {
+          "anyOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "map_id",
+                "hash",
+                "algorithm",
+                "local_spec_material_hash"
+              ],
+              "properties": {
+                "map_id": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "hash": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "algorithm": {
+                  "const": "map-store-v1"
+                },
+                "local_spec_material_hash": {
+                  "type": "string",
+                  "pattern": "^sha256:[0-9a-f]{64}$"
+                }
+              }
+            }
+          ]
+        }
+      }
+    },
     "spec": {
       "type": "object",
       "required": ["path", "hash", "active_pages"],