@nextcommerce/campaigns-os 1.34.1 → 1.37.2

package/docs/diagnostics.md

@@ -0,0 +1,55 @@
+# Redacted support diagnostics
+
+Requires Campaigns OS 1.35.0 or later. If that version is not yet published to
+npm, install a reviewed full-SHA source pin as described in the quickstart.
+
+From the campaign folder:
+
+```bash
+npx campaigns-os tooling diagnose --platform codex --packet campaign-runtime.build.json
+npx campaigns-os tooling diagnose --platform codex --packet campaign-runtime.build.json --json > diagnostic.json
+```
+
+Omit `--packet` for installation and skill diagnostics only. Use `--platform
+claude` for a Claude-only profile. `--context` and `--report` may select existing
+local sidecars; `--target` selects a local skills directory. These inputs are
+never included in the export. The text and JSON forms are suitable for review
+and copying to a support request. The command itself sends nothing.
+
+The `campaigns-os-diagnostic/v0` summary is an allowlist projection of existing
+`tooling status` and read-only `doctor` producers. Its stage comes from doctor's
+`next` block, which uses the existing lifecycle picker. It does not execute
+`next`, install, fetch campaign data, run a browser, publish, remit, deploy,
+create an order, sweep a stale run session, or write retained campaign evidence.
+Mutation flags do not change that behavior. Export success means a summary was
+produced, including when its inspection is unavailable; consult its statuses.
+
+The only exported fields are the schema version; a numeric package version or
+null; install mode (`checkout`, `node_modules`, `global`, `npx_cache`,
+`package_directory`, or `unknown`); coarse selected agent profile; tooling and
+doctor statuses; existing next stage; freshness; fixed accepted reason/action
+IDs; and fixed human-readable recovery owner, action, and input-needed text.
+Unknown enum values become `unknown` with `diagnostic.unsupported_value`.
+Unrecognized reason/action IDs become `diagnostic.unsupported_reason` or
+`diagnostic.unsupported_action`; they are never copied or given authority.
+Unsupported IDs need detailed local review, not a guessed repair.
+
+Toolkit freshness is `pinned` only when a producer identifies a source pin,
+`local_ref_current`/`local_ref_behind` for a checkout's existing local upstream
+comparison, otherwise `unknown`. This performs no network freshness check.
+An exact registry version and lockfile still identify installed bytes when a
+source commit is not derivable. Inspection `observed` means local doctor
+inspection succeeded, not that the served build, deployed campaign, or saved
+Map revision is current. Missing inspection is `not_requested` or `unavailable`.
+The diagnostic is neither an orientation envelope nor launch evidence.
+
+The export excludes absolute paths, URLs, argv, environment, source content,
+prompts, free-text findings, credentials, campaign/customer identities, and
+order values. Producer exceptions are summarized with fixed unavailable IDs;
+their raw messages are not exported. Detailed `doctor`/`next` output stays local
+and can contain campaign data, so it is not a substitute for this export.
+
+Recovery names who supplies the missing input. Inspect the detailed local
+producer for the exact command and any campaign-specific input. If a QA verdict
+was recorded but publication failed, follow `qa publish` recovery for that
+retained verdict; never rerun checkout or create an order to republish evidence.

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.34.1`
+Supported surface at generation time: `1.37.2`
 
 ## Forward compatibility
 
@@ -243,6 +243,7 @@ so a renamed command fails here as well as at the supported-surface gate.
 - `campaigns-os findings`
 - `campaigns-os run-record`
 - `campaigns-os run`
+- `campaigns-os demo`
 
 ## Terminal outcome examples
 

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/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.34.1`.
+Recipe kind `campaigns-os-node-v1`, revision `1.0.2`, validated by `schemas/campaigns-os-runtime-recipe.v1.schema.json` (`Campaigns OS Runtime Recipe v1`). Supported surface at generation time: `1.37.2`.
 
 ## What this is
 

package/docs/supported-surface.md

@@ -14,7 +14,7 @@ implementation detail, however stable it looks.
 | Surface | Contract | Change discipline |
 |---|---|---|
 | `schemas/*.schema.json` (all of them) | The portable contract catalog: CampaignSpec, Design Source Package, Build Packet, Build Context, Assembly Report, Doctor Output, sidecar-bundle conformance, Run Record, Workflow Finding, Build Brief, Source-HTML Manifest, Tooling Orientation, Release Ledger, QA Verdict, the QA Verdict sidecar projection, Runtime Recipe, and the legacy-migration inventory/plan/receipt trio. | Hashed. Any content change requires updating the recorded hash **and** bumping `surface_version` in the same PR. A shape change that alters meaning gets a new schema-version const — one version identifier must never cover two shapes (the 2026-08 assembly-report drift is the incident this rule encodes). Additions to an open `v0` schema are expected and consumers must tolerate unknown fields; the security-sensitive legacy-migration schemas are closed, so additions there require a new lineage. 1.28.0 (RL entry `surface_version: 1.28.0`, breaking) removed the two required Build Packet booleans `qa.test_orders_allowed` and `qa.sandbox_test_card_confirmed` (nothing read them; test orders run from `--test-order <mode>` alone), added `local-serve` to the `deploy.target` enum, and added the optional `remit_result` / `remit_base_kind` fields to the Run Record. 1.30.0 (additive) added the optional `data_layer` record to the QA Verdict's `test_orders[]` entries — the order's `dl_purchase` reading (#325). 1.33.0 (additive) added the optional `qa_verdict_publish` block to the Run Record — which verdict was posted to the QA portal, by `qa run` or `qa publish`, and what the portal answered, in the `remit_result` vocabulary (#328). |
-| CLI commands: `start`, `prepare-build`, `build`, `polish`, `checkpoint`, `page-kit`, `spec`, `doctor`, `bundle`, `next`, `theme`, `tooling`, `install-skills`, `install-agent-context`, `validate-assembly-report`, `telemetry`, `standardize`, `qa`, `findings`, `run-record`, `run`, `sdk` | 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. |
@@ -82,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextcommerce/campaigns-os",
-  "version": "1.34.1",
+  "version": "1.37.2",
   "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",
@@ -134,6 +139,11 @@
     "compatibility.json",
     "AGENTS.md",
     "CHANGELOG.md",
-    "docs/sdk-storage-compatibility.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"],