@nextcommerce/campaigns-os 1.33.0

package/docs/legacy-migration.md

@@ -0,0 +1,58 @@
+# Legacy migration contract
+
+`@nextcommerce/campaigns-os/legacy-migration` is the portable contract for
+planning a bounded Campaign Cart SDK 0.3.x to 0.4.x shadow-campaign migration.
+It does not connect to a store or authorize a write.
+
+The v0 contract includes three schemas:
+
+- `campaigns-os-legacy-migration-inventory/v0` captures an exact source
+  campaign, unit-product package identities, shipping methods, wire-ready
+  Offer intents, and authorized-domain intents.
+- `campaigns-os-legacy-provisioning-plan/v0` records the stable preview and its
+  campaign/package/shipping operations. Offer rows remain keyed intents until
+  package IDs exist at apply time.
+- `campaigns-os-legacy-provisioning-receipt/v0` records resource IDs and
+  readback evidence, including one `offer.create` row per applied intent.
+
+## Safety boundary
+
+The contract contains no Admin API token, authenticated transport, session,
+write executor, audit-store implementation, receipt store, rollback, or delete
+operation. Inventory and plan inputs reject credential-like field names
+recursively. Receipts may retain the public campaign `api_key` returned by the
+Admin API, but reject private credential fields; their build-evidence projection
+removes raw readback entirely. Execution is owned by the connector and must
+retain read-before-write, explicit preview and apply, read-after-write, audit,
+durable receipt, and stop-on-ambiguity rules.
+
+Package rows identify exactly one product variant. Quantity tiers, vouchers,
+and post-purchase pricing are Offers, never duplicate or quantity-shaped
+packages. The upstream Offers API supports `all_packages`, but this migration
+contract deliberately refuses it: a migration Offer must list stable package
+keys and resolve those keys to IDs immediately before apply.
+
+## Offer application
+
+`buildLegacyOfferRequest(intent, packageIdByKey)` produces the documented
+Offers create body. It refuses unresolved keys and emits `package_ids`; it does
+not leak local `intent_key` or `package_keys` into the request.
+
+The API read shape is not the write shape. Offer `package_ids` read back under
+`condition.packages[]`, while package `price` reads back under `prices[]`.
+`compareLegacyOfferReadback` and `compareLegacyPackageReadback` project those
+known differences. If a field cannot be projected, they return
+`unprojectable`; they never infer or guess a value. Package price comparison
+therefore requires the campaign currency.
+
+## Determinism and evidence
+
+`normalizeLegacyMigrationInventory` sorts packages, shipping methods, Offers,
+Offer package keys, and domains by their logical keys. Combined with
+`stableCanonicalStringify` and `hashLegacyMigrationArtifact`, equivalent input
+ordering yields the same digest.
+
+`projectLegacyProvisioningReceipt` emits token-free build evidence: campaign,
+package, shipping, and Offer IDs keyed by their stable identities, applied
+Offer intent keys, plan hash, receipt hash, and applied timestamp. It omits
+audit keys and raw readback payloads.

package/docs/migration-sidecar-bundle.md

@@ -0,0 +1,139 @@
+# Migration sidecar bundle v0
+
+The migration sidecar bundle is the strict JSON boundary between a campaign
+repository, its CI producer, and Campaigns Agent readback. It does not replace
+the underlying artifacts and it does not create another manifest file. The
+machine contract is
+[`contracts/migration-sidecar-bundle.v0.json`](../contracts/migration-sidecar-bundle.v0.json),
+and the conformance command is:
+
+```bash
+campaigns-os bundle check --packet campaign-runtime.build.json --json
+```
+
+Add `--require-qa` when the migration or campaign claims QA is complete.
+
+## Conformance is not readiness
+
+`status: conformant` (and `ok: true`) means the sidecars agree with each other
+and with the contract: every required artifact is present, valid JSON, on its
+declared schema version, freshly timestamped, and carrying the same campaign
+identity. It says nothing about whether doctor or QA passed. A doctor sidecar
+that records a blocked run is a well-formed artifact whose content says the
+campaign cannot proceed, and a blocked QA verdict is schema-valid.
+
+Read readiness from two places instead:
+
+- The findings. A doctor sidecar recording a blocked run (`status: blocked`
+  or `ok: false`) emits `bundle.doctor_output.blocked`; a QA verdict whose
+  `disposition` is `blocked` emits `bundle.qa_verdict.blocked`. Both are
+  warnings by default (the bundle is still conformant) and errors under
+  `--require-qa` (a QA-complete handoff cannot ride either block, so the bundle
+  is nonconformant and the command exits 2).
+- `stage_blocked` keeps its published meaning: `true` only when a required
+  QA verdict (`--require-qa`) is blocked. The doctor case is carried by the
+  finding alone until a schema bump widens the field.
+
+The text report prints a `Readiness:` line directly under `Status:` that reads
+those fields for you. The remedy for a blocked doctor is to resolve its errors
+and re-run `campaigns-os doctor --packet campaign-runtime.build.json
+--write --strip-paths` so the retained sidecar records a ready run.
+
+## Canonical bundle
+
+| Kind | Canonical path | Requirement | Schema/version | Freshness |
+| --- | --- | --- | --- | --- |
+| Build Packet | `campaign-runtime.build.json` | Required | `campaign-runtime-build-packet/v0` | Its `generated_at` is the bundle-selection authority. Never select a packet by mtime. |
+| Build Context | `.campaign-runtime/build-context.json` | Required | `campaign-runtime-build-context/v0` | Producer-stamped `generated_at`; `packet_path` must point to the root packet. |
+| Assembly Report | `.campaign-runtime/assembly-report.json` | Required | `campaign-runtime-assembly-report/v0` | Producer-stamped `generated_at`; authored stage evidence is preserved. |
+| Doctor Output | `.campaign-runtime/doctor-output.json` | Required | `campaigns-os-doctor-output/v0` | Refresh after any doctor-input change; an explicit `stale: true` fails conformance. `generated_by` names the command that persisted it (`doctor`, `next`, `start`, `build`, `qa run`); a sidecar without it predates the stamp. |
+| QA Verdict projection | `.campaign-runtime/qa-verdict.json` | Required after QA | QA schema `1.0`, constrained by the sidecar projection schema | `generated_at` is the projection/promotion instant. |
+
+The packet stays at repository root because that is the default discovery
+contract. A packet found only at
+`.campaign-runtime/campaign-runtime.build.json` is reported with a root-path
+remedy; conformance does not silently widen discovery.
+
+The checker validates canonical paths, declared schema versions, strict UTC
+timestamps, cross-artifact Map ID, public slug, campaign directory, live URL
+path, template family, and spec identity, doctor freshness, and the URL/order-
+free QA projection. Safe repository-relative spellings such as
+`campaign-runtime.build.json` and `./campaign-runtime.build.json` are
+equivalent; absolute paths, URIs, backslashes, and parent traversal are not.
+
+Spec identity has two deliberately separate meanings. Build Context
+`spec.hash` and Assembly Report `identity.spec_hash` retain exact raw-byte
+integrity. Build Context `spec.material_hash`, Assembly Report
+`identity.spec_material_hash`, and QA Verdict `spec_hash` carry the canonical
+semantic identity used for cross-producer correlation. Harmless JSON formatting
+and the declared volatile top-level metadata do not change the material hash;
+commerce or funnel changes do. A partially regenerated material-identity set
+fails closed. For stored bundles produced before the material fields existed,
+the checker uses the contract's explicit strict-legacy mode and requires the
+three historical hash values to match exactly.
+
+A blocked doctor remains readable evidence. Under `--require-qa`, a schema-
+valid QA Verdict whose disposition is `blocked` is nonconformant for handoff and
+the result carries `stage_blocked: true`; shape-valid does not mean ready.
+
+The Build Packet schema keeps `campaign_directory` and `live_url_path`
+nullable for older or partial packet compatibility. Bundle conformance is
+deliberately stricter: both identities must be non-empty so equality with the
+Assembly Report can be proved. Regenerate the packet with `start` or
+`prepare-build` before checking a bundle whose packet carries either value as
+`null`.
+
+## Headless CI producer
+
+Resolve and check out one commit before producing anything. The initial
+`campaigns-os start` run writes the packet, context, report, and doctor output
+from explicit CampaignSpec/source/template inputs. `prepare-build` writes the
+packet, context, and report; refresh Doctor output with the command below.
+Later CI runs must preserve the authored packet, context, and Assembly Report
+rather than recreating them with `--force` and erasing stage decisions.
+
+Refresh generated evidence at that commit:
+
+```bash
+campaigns-os doctor \
+  --packet campaign-runtime.build.json \
+  --write \
+  --strip-paths \
+  --json
+
+# Only when carrying forward a named historical full verdict:
+campaigns-os qa promote \
+  --packet campaign-runtime.build.json \
+  --verdict "$EXPLICIT_FULL_VERDICT" \
+  --json
+
+campaigns-os bundle check \
+  --packet campaign-runtime.build.json \
+  --require-qa \
+  --json
+```
+
+`qa promote` requires one explicit full-verdict path. CI must not pick a verdict
+by mtime, filename sort, or a directory's apparent “latest” entry. If there is
+no historical verdict to promote, run QA and let `qa run` write the committed
+projection.
+
+The checker emits both exact per-file SHA-256 digests and one
+`material_digest`. The material digest canonicalizes object-key order and
+removes only the volatile fields declared in the machine contract (generation
+timestamps and run IDs). Repeating the producer over the same substantive
+evidence therefore keeps the material digest stable; changing a disposition,
+identity, stage state, or assertion changes it.
+
+## Consumer and compatibility fixture
+
+The supported production-shaped fixture lives at
+`contracts/fixtures/sidecar-bundle/production-shaped/`. It contains the root
+packet and all four canonical sidecars, including a URL/order-free QA verdict.
+Campaigns Agent can copy or read that tree in both its deterministic and
+real-Campaigns-OS lanes without this public repository importing private Agent
+code.
+
+Markdown reports, equivalence ledgers, and migration-specific scripts may live
+beside the bundle as supporting evidence. They never satisfy a missing JSON
+artifact and are never substituted for current readback truth.