@nextcommerce/campaigns-os 1.33.0

package/docs/release-ledger-authoring-guide.md

@@ -0,0 +1,274 @@
+# Release-ledger authoring guide
+
+Every agent-relevant change to this repository gets one entry in
+`contracts/release-ledger.json`. This is how you write one, and what CI will do
+to you if you do not.
+
+If you are an agent reading this repository rather than changing it, you want
+[`AGENTS.md`](../AGENTS.md) and
+[`docs/orientation-contract-reference.md`](orientation-contract-reference.md)
+instead.
+
+## Why a ledger as well as a changelog
+
+`CHANGELOG.md` is keyed to the supported-surface version. That misses a whole
+class of change that a downstream agent very much cares about: a renamed CLI
+flag, a rewritten contract doc, a new or reworded skill, a changed
+generated-runtime input, a widened compatibility statement. None of those need
+touch a hashed file, so none of them move `surface_version`, so an agent reading
+only the changelog concludes nothing happened.
+
+The ledger records those. The changelog stays the human narrative, and each
+ledger entry links to exactly one changelog section so the two can never tell
+different stories.
+
+## What counts as agent-relevant
+
+One definition, one file: `contracts/agent-relevant-change-policy.v1.json`. The
+classifier, the gate, the generated reference, and every test read it. There is
+no second copy to keep in sync, and you should not make one.
+
+It defines ten semantic classes — `schema`, `hashed_surface`, `named_surface`,
+`cli_surface`, `skill`, `package_export`, `compatibility_policy`,
+`documentation`, `workflow`, `generated_runtime` — and classifies a changed path
+in a fixed, total order:
+
+1. **Self-referential exemptions.** `contracts/release-ledger.json` and
+   `CHANGELOG.md`. Recording a change is not itself a recorded change.
+2. **Explicit rules.** Ordered, first match wins.
+3. **Derived from the supported surface.** Every path in `hashed{}` or `named[]`
+   is agent-relevant by construction. This pass runs *before* the ignore list on
+   purpose: a path you just added to the supported surface must never be
+   swallowed by a broad ignore prefix like `docs/` or `contracts/`.
+4. **Ignored, with a stated reason.** "No agent impact" is an assertion someone
+   wrote down, not an omission someone forgot.
+5. **Unclassified — an error.** A path matching nothing fails the gate. The
+   classifier fails closed, which means adding a new top-level file makes you
+   say what it is.
+
+## Writing an entry
+
+```jsonc
+{
+  "id": "RL-0007",              // never reused, never renumbered
+  "sequence": 7,                // exactly one more than the last entry
+  "date": "2026-09-01",         // not earlier than the last entry
+  "kind": "release",            // or "amendment"
+  "surface_version": "1.15.0",  // null for a same-surface change
+  "changelog_section": "1.15.0",
+  "changelog_sha256": "<sha256 of that section body>",
+  "agent_impact": "What a consumer must do differently. 'None.' is fine — but write it.",
+  "compatibility": "compatible | additive | breaking",
+  "migration": "The exact action, or \"none\". A breaking entry may not say none.",
+  "changes": [
+    {
+      "class": "named_surface",
+      "path": "docs/build-packet.md",
+      "surface_entry": "docs/build-packet.md",
+      "summary": "One sentence, written for a consumer."
+    }
+  ],
+  "entry_sha256": "<sha256 of this entry with entry_sha256 removed>"
+}
+```
+
+`sequence` and `id` are two different things. `sequence` is the entry's
+position in the array and must equal that position: the checker derives the
+expected value from the index, not from the previous entry's claim, so it is the
+authoritative order. `id` is a unique, immutable label (`RL-NNNN`) that is never
+reused and never renumbered; nothing requires its number to match `sequence`.
+The two therefore diverge legitimately, and already do in this ledger: when two
+PRs are open at once, the second to merge restamps its `sequence` to sit after
+the first while keeping the id it was written with. Read order from `sequence`
+and identity from `id`; never renumber an id to close the gap.
+
+Two hashes, two jobs. `changelog_sha256` catches a changelog section edited
+after the fact. `entry_sha256` catches a historical entry edited in place, even
+in a squashed history where the diff is gone.
+
+Computing them:
+
+```bash
+node --input-type=module -e '
+import { readFileSync } from "node:fs";
+import { parseChangelogSections, entryHash } from "./scripts/orientation-contract.mjs";
+const section = parseChangelogSections(readFileSync("CHANGELOG.md", "utf8"))
+  .find((s) => s.section_id === "1.15.0");
+console.log("changelog_sha256:", section.body_sha256);
+'
+```
+
+Then add the entry with that `changelog_sha256`, and compute `entry_sha256` the
+same way with `entryHash(entry)`.
+
+### Same-surface changes
+
+Set `surface_version` to `null` and link a changelog section identified as
+`<current-version>+agent.<n>` — for example `1.14.0+agent.1`. It sorts at the
+same version, so nobody reads it as a release that did not happen, and it gives
+the entry a real section to point at.
+
+### Path-less change items
+
+A CLI flag has no file of its own. Record it with `"path": null` and name the
+affected `surface_entry` (the command). The gate still requires that some
+classified path of the same class changed in the range, so a flag change cannot
+be recorded without the bytes actually moving somewhere.
+
+### Fixes that touch only policy-ignored paths
+
+A fix living entirely in paths the policy ignores — `src/` other than
+`src/cli.mjs`, `scripts/`, tests and fixtures — carries a same-surface CHANGELOG
+section (`X.Y.Z+agent.N`) and **no ledger entry**. There is nothing for an entry
+to claim: every change item must map to a classified changed path in the range,
+and an ignored path is never classified, so an entry written for such a PR is
+refused by the backward direction of the gate rather than merely unnecessary. A
+path-less item fails the same way, because no classified change of its class
+exists in the range. The ignore list and its stated reasons are in
+[`contracts/agent-relevant-change-policy.v1.json`](../contracts/agent-relevant-change-policy.v1.json).
+
+The dividing line inside `src/` is `src/cli.mjs`: an explicit rule classifies it
+as `cli_surface`, so any change to it is agent-relevant and owes an entry, even
+when the behaviour change originates in a helper module beside it.
+
+### Amendments
+
+Historical entries are never edited. When an entry turns out to be wrong or
+incomplete, append a correction:
+
+```jsonc
+{
+  "id": "RL-0008",
+  "sequence": 8,
+  "kind": "amendment",
+  "amends": "RL-0007",
+  "amendment_reason": "RL-0007 was recorded as compatible; it removed a documented guarantee.",
+  "surface_version": null,
+  "changelog_section": "1.15.0+agent.1",
+  "compatibility": "breaking",
+  "migration": "Stop relying on the removed guarantee; see docs/build-packet.md.",
+  "agent_impact": "Treat the 1.15.0 packet doc change as breaking, not compatible.",
+  "changes": [ /* … */ ]
+}
+```
+
+An amendment is the only entry kind whose change items may map to no changed
+path in its own range, because it corrects meaning rather than moving bytes.
+
+### Correcting a section's bytes
+
+A changelog section an entry hashes is as frozen as the entry. When the section
+itself has to change — a stray merge-conflict marker committed inside it is the
+case that has happened — the historical entry cannot take the new hash, and a
+plain amendment pointing at some other section leaves the stale hash failing.
+So an amendment may link the **same** `changelog_section` as the entry it
+amends, carrying that section's current `changelog_sha256`. The checker then
+reads the amended entry's hash as superseded, and the amendment's own hash
+keeps the section pinned. Only an amendment, and only one that names the
+entry currently holding the link, may re-link a section; any other second link
+still fails the one-to-one rule. Say in `amendment_reason` what changed in the
+section and why.
+
+`scripts/check-changelog-structure.mjs` (part of `npm run check`) refuses the
+marker lines outright, in `CHANGELOG.md` and under `docs/`, and also holds the
+section layout: identifiers unique, `+agent.N` sections in one run directly
+above their release with N descending (newest first), and every ledger
+`changelog_section` naming a section that exists. Insert a new `+agent.N`
+section at the top of its release's run, not directly above the release
+heading.
+
+## Running the gate
+
+```bash
+node ./scripts/check-release-ledger.mjs                    # structure, hashes, limits
+node ./scripts/check-release-ledger.mjs --base origin/main # the two-way gate
+```
+
+Without `--base` the checker validates the ledger as it stands. The completeness
+gate needs a comparison point, so pass `--base` in CI and before you open a PR.
+`npm run check` runs the structural half.
+
+## What passes and what fails
+
+The authoritative matrix is data, not prose:
+`contracts/fixtures/orientation/release-gate/cases.json`. Every case there is a
+test in `scripts/check-release-ledger.test.mjs`. Add a case and you have added a
+test.
+
+Passes:
+
+- A hashed schema changed, `surface_version` advanced, one entry claims it.
+- A named contract doc changed with no surface bump, one entry with
+  `surface_version: null` and a `+agent.N` changelog section.
+- A CLI flag, a skill, a workflow, or the compatibility statement changed, same
+  shape.
+- Several changes in one entry, each path covered by exactly one change item.
+- An amendment that maps to no changed path.
+
+Fails:
+
+- An agent-relevant path with no change item — the failure the gate exists for.
+- A change item naming a path that did not change and is not an amendment.
+- A change item claiming an implementation path the policy excludes.
+- A duplicate entry id, or one entry recording the same `(class, path,
+  surface_entry)` identity twice. Identity is unique WITHIN an entry, not across
+  the ledger: a path is touched by many releases over a repository's life, and
+  each of those is a real change that must be recordable. Recording one change
+  twice inside a single range is caught by the coverage rule instead — a path
+  covered by more than one change item fails.
+- A sequence gap, or a date earlier than the previous entry.
+- A `breaking` entry whose migration is `none`, or a blank `agent_impact`.
+- A missing changelog section, a duplicate section identifier, or a stale
+  `changelog_sha256`.
+- A stale `entry_sha256`.
+- Any commit-shaped property on an entry — see below.
+- A rewritten or deleted historical entry.
+- Two entries claiming the same `surface_version`.
+- A changed path the policy has never seen.
+- A supported-surface bump that no new entry claims.
+- A path-less change item with no classified change of its class in the range.
+- An amendment with no `amends`, an `amends` naming no earlier entry, or no
+  `amendment_reason`; or a non-amendment carrying either field.
+
+Only entries NEW in the comparison range are classified against the current
+policy and supported surface. A historical entry was written under the policy in
+force at the time and the ledger is append-only, so re-judging it under a
+tightened policy would fail a document nobody is permitted to edit. Everything
+else — shape, ordering, sequence, hashes, changelog correspondence — applies to
+every entry.
+
+## Entries carry no commit
+
+An entry cannot name the commit containing it without being rewritten after that
+commit exists. The schema rejects any commit-shaped property, and the checker
+says so by name rather than reporting a generic "unexpected property".
+
+A consumer derives the introducing commit from history at the target OID:
+oldest-first over the commits touching the ledger, crediting each entry id to the
+first commit whose ledger blob contains it. Merge commits are handled by that
+walk without a special case.
+
+The walk covers the FULL history ending at the target, with history
+simplification disabled (`git rev-list --full-history --reverse --topo-order
+<oid> -- contracts/release-ledger.json`). A walk that starts at some base loses
+every entry introduced before it; a simplified walk can drop the side-branch
+commit that actually introduced an entry. `AGENTS.md` states both properties for
+consumers.
+
+## Size bounds
+
+`contracts/orientation-limits.v1.json` bounds what a consumer reads: source
+bytes, section count, section bytes, envelope bytes, ledger entries. Exceeding
+one is a refusal with `orientation_too_large`, never a truncation. So is a
+measurement that is absent or non-finite: a bound nobody measured is a bound
+nobody enforced.
+
+Every bound is a whole-artifact guardrail — the complete changelog and the
+complete ledger at the target commit, not a baseline-to-target window. That is
+the conservative direction, since a window is always a subset of the whole. Two
+of them (section count, ledger entries) grow monotonically; when one is reached
+the answer is baseline rotation, described in the contract's `_growth_note`, not
+a quiet raise.
+
+Raising a limit is a reviewed policy change: advance `limits_version`, and the
+change owes its own ledger entry like anything else.

package/docs/runtime-readiness.md

@@ -0,0 +1,211 @@
+<!--
+  GENERATED FILE — do not edit.
+  Source: contracts/runtime-recipe.campaigns-os-node-v1.json
+  Regenerate: node ./scripts/generate-runtime-readiness.mjs --write
+-->
+
+# Runtime readiness
+
+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`.
+
+## What this is
+
+A recipe is data, not code. A consumer executes exactly the commands enumerated here and never a command assembled from repository data. This repository publishes the recipe; the installed consumer bootstrap executes it, using its own released parser rather than anything loaded from the checkout under evaluation.
+
+Enforcement is fail-closed. Every field is normative: `fail_closed` is `true` and a check that cannot be performed counts as `failed`, never as skipped. A refusal carries the stable reason code `runtime_recipe_refused`.
+
+## What a prepared runtime can and cannot do
+
+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.
+
+| Capability | Available |
+|---|---|
+| `type_check` | yes |
+| `build_spec` | yes |
+| `browser_qa` | **no** |
+
+## Preconditions
+
+All four must already hold before any step runs. They are fixed booleans because a precondition a document could switch off is not a precondition.
+
+- `target_oid_resolved`
+- `lockfile_present`
+- `clean_staging_generation`
+- `input_fingerprint_recorded`
+
+## Tool versions
+
+| Tool | Accepted range | Verified against | Rationale |
+|---|---|---|---|
+| Node | `>=20.19.0 <25` | `22.23.1` | The lower bound is the target's own declared minimum. The upper bound is the recipe's, not the target's: the target declares an open-ended minimum, and an open-ended range is not a bound. Delegating the ceiling to the checkout under evaluation would let that checkout widen the accepted runtime of the consumer evaluating it. Qualifying a new Node major is a one-line revision plus a ledger entry, which is the intended cost. |
+| npm | `10 || 11` | `10.9.8`, `11.19.1` | Both majors were run end to end against this recipe and produced byte-identical output, and together they are exactly the set that supported Node release lines ship by default. Later majors are opt-in installs rather than what the ecosystem is running, so they stay outside the range until a Node line bundles one; that trigger is an external fact rather than a taste call. |
+
+The contract declares its own ranges rather than inheriting the target's. It records the target's `engines.node` as `>=20.19.0`; on disagreement the disposition is `refuse`. The exact value this revision was authored against. A consumer compares the target's live value to this string and refuses on any difference, per on_disagreement. That is deliberately strict: a widened engines range in the target is precisely the silent widening this contract exists to catch, and re-agreeing is a one-line revision.
+
+## Network
+
+Two independent bounds that must both hold. The per-step policy bounds WHERE bytes may come from; the integrity digests recorded in the lockfile bound WHICH bytes are acceptable — that second bound is declared at `target_expectations.lockfile.integrity_pinned`, over the file at `target_expectations.lockfile.path`, which is also listed in `inputs.files`. Neither bound substitutes for the other. WHO ENFORCES THIS, PRECISELY: this object is a declaration the CONSUMER enforces. The argv in `steps[].args` deliberately does not carry it — there is no `--registry` and no offline flag there, and no `env` field on a step. A conforming consumer constructs the process environment for each step so that its package manager resolves only from that step's declared `hosts` (and from nothing at all where the policy is `deny`), owns the cache and both npmrc paths per `cache_ownership`, and refuses inherited npmrc, proxy, and credential configuration per the three `inherit_*` fields above. Carrying the pin in argv instead would change the recipe's commands, which is a new recipe KIND rather than a revision; it is a legitimate future design, not a silent fix. WHAT THAT GUARANTEES: a package-manager configuration bound, not a host-level network sandbox. It cannot stop a process from opening a socket to some other address. What bounds that is the other half of the recipe: `--ignore-scripts` on both steps means no third-party dependency code executes during preparation at all, so the only programs that run are the package manager and the compiler. Read each step's policy as 'the consumer configures this step's process to resolve packages only from that step's declared hosts, which for a `deny` step is none at all, and no third-party code runs that could disregard it' — which is true and checkable. Do not read it as 'the host is prevented from reaching anything else', which would require a sandbox this contract does not specify. A consumer that adds a real network sandbox strengthens this bound without changing a field below, and is encouraged to; a consumer that treats the declared hosts as advisory violates it.
+
+| Step | Policy | Hosts | Rationale |
+|---|---|---|---|
+| `install` | `allowlist` | `registry.npmjs.org` | The install step is the only step that needs bytes it does not already have, and it needs them from exactly one place. Measured cold-cache install is a few seconds, so the network window is small. The cache is an optimisation and never a correctness input: an offline-after-warm policy would make a stale or poisoned cache silently change what gets built, with no fetch left to catch it. Note that `args` above carries no registry flag — the consumer is responsible for setting the package manager's registry to this host in the process environment before invoking that argv, and for refusing any inherited npmrc, proxy, or credential configuration that could redirect it. Combined with `--ignore-scripts`, nothing that runs during install is third-party code that could disregard the setting. The integrity digests remain the independent second bound, which is what makes a redirected or substituted byte stream fail even if the first bound were evaded. |
+| `build` | `deny` | none | The build step is a local type-directed compile and needs no network at all. Declaring that turns an assumption into a check. As with install, `args` above carries no offline flag — the consumer puts the package manager into offline mode through the process environment it constructs for this step. `tsc` opens no sockets of its own, and `--ignore-scripts` keeps pre/post hooks from introducing any. |
+
+Cache ownership is `consumer_profile`. Inherited proxy configuration: `false`. Inherited credentials: `false`. Inherited npm configuration file: `false`.
+
+## Steps
+
+### install
+
+```
+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.
+
+### build
+
+```
+npm run --ignore-scripts build:spec
+```
+
+Working directory `target_root`, stdin `closed`, lifecycle scripts `disabled`, bounded by `build_seconds`.
+
+Not redundant with the install step. Because install runs with lifecycle scripts disabled, the target's prepare script does not fire and the output directory is absent afterwards; this step is the only thing that builds the runtime under the recipe's own flags. --ignore-scripts here means the named script runs while its pre and post siblings do not, so the build is exactly one contracted command rather than an open-ended chain the target can extend.
+
+## Inputs
+
+The complete input set, enumerated explicitly rather than globbed. The compiler's configured include globs are NOT the input set: two root modules enter the compilation transitively through imports from the entry module and are emitted, so a fingerprint derived from the globs would cover 36 of the 38 compiled sources and miss one of the larger emitted surfaces. Test fixtures and the package's own tests are not inputs; nothing under them is emitted. A checker resolves the compiler's actual file list and asserts it equals this enumeration, so this list cannot rot silently.
+
+Fingerprint algorithm `sha256`, over 42 enumerated files:
+
+- `campaign-spec/analytics-vocabulary.ts`
+- `campaign-spec/index.ts`
+- `campaign-spec/normalize.ts`
+- `campaign-spec/package.json`
+- `campaign-spec/routing.ts`
+- `campaign-spec/rules/analytics-contract-shape.ts`
+- `campaign-spec/rules/assembly-hints-shape.ts`
+- `campaign-spec/rules/campaign-metadata.ts`
+- `campaign-spec/rules/checkout-has-success-url.ts`
+- `campaign-spec/rules/cycle-detection.ts`
+- `campaign-spec/rules/design-source-shape.ts`
+- `campaign-spec/rules/downsell-without-upsell.ts`
+- `campaign-spec/rules/exit-intent-validation.ts`
+- `campaign-spec/rules/funnel-count.ts`
+- `campaign-spec/rules/funnel-hypothesis-length.ts`
+- `campaign-spec/rules/funnel-identity.ts`
+- `campaign-spec/rules/funnel-weight-sum.ts`
+- `campaign-spec/rules/index.ts`
+- `campaign-spec/rules/offer-ref-integrity.ts`
+- `campaign-spec/rules/package-pricing-sanity.ts`
+- `campaign-spec/rules/page-count.ts`
+- `campaign-spec/rules/page-id-uniqueness.ts`
+- `campaign-spec/rules/promo-code-input-validation.ts`
+- `campaign-spec/rules/promo-codes-shape.ts`
+- `campaign-spec/rules/route-field-ignored-for-page-type.ts`
+- `campaign-spec/rules/route-target-resolves.ts`
+- `campaign-spec/rules/schema-version.ts`
+- `campaign-spec/rules/sdk-version.ts`
+- `campaign-spec/rules/shipping-countries-shape.ts`
+- `campaign-spec/rules/shipping-methods-present.ts`
+- `campaign-spec/rules/store-profile-shape.ts`
+- `campaign-spec/rules/thank-you-requirement.ts`
+- `campaign-spec/rules/unknown-top-level-fields.ts`
+- `campaign-spec/rules/upsell-has-packages.ts`
+- `campaign-spec/rules/upsell-routing-complete.ts`
+- `campaign-spec/rules/upsell-without-checkout.ts`
+- `campaign-spec/rules/variant-labels-shape.ts`
+- `campaign-spec/sdk-version-parse.ts`
+- `campaign-spec/tsconfig.build.json`
+- `campaign-spec/types.ts`
+- `package-lock.json`
+- `package.json`
+
+## Outputs
+
+The output directory is a build product. It is untracked and git-ignored, no committed copy exists, and the copy in a published tarball exists only because packing runs the prepare script. There is therefore no baseline hash for its CONTENTS that this repository could publish, and any acceptance criterion phrased as 'output matches expected hashes' is not implementable as written. Verification is self-consistency instead: the inventory is complete and has nothing extra, the recorded hashes still hold, the entry module imports, the type entry is present, and the inputs that produced the output still match the inputs at the target commit. The build is deterministic — independent clean checkouts at one commit produce byte-identical output, and the compiler config emits neither source maps nor declaration maps, so no absolute paths or timestamps are embedded — which is what makes content hashing a sound strategy rather than a hopeful one.
+
+Directory `campaign-spec/dist`. Committed: `false`. Type entry `campaign-spec/dist/index.d.ts`.
+
+Expected inventory is derived, never listed twice. For every enumerated input under module_source_root whose path ends in .ts, the build is expected to emit campaign-spec/dist/<path relative to module_source_root, with .ts replaced> once per entry in emitted_extensions. The expected inventory is exactly that set: nothing missing, nothing extra. Emitted extensions: `.js`, `.d.ts`. At this revision that derivation yields 76 files.
+
+### Mandatory checks
+
+Every check below is mandatory; there is no optional check, because an optional check is an advisory bound under another name.
+
+| Check | Kind | Detects | Applies to | Rationale |
+|---|---|---|---|---|
+| `dist_inventory` | `dist_inventory` | `absent`, `extra` | The set of files present under outputs.directory after the build step. | Catches both directions. A missing module is an incomplete emit; an unexpected file is as much a signal as a missing one, because it means something other than the declared build wrote into the output directory. |
+| `content_hash_stability` | `content_hash_stability` | `corrupt` | The bytes of every file under outputs.directory, hashed with the inputs.fingerprint_algorithm digest and recorded in the generation manifest. | Detects any post-build modification of the prepared runtime. Costs single-digit milliseconds against an output measured in hundreds of kilobytes. It is a self-consistency check, not a comparison against a hash published here: no such hash can exist, because the output is not committed. |
+| `module_import_smoke` | `module_import_smoke` (shallow) | `corrupt` | Importing the emitted package entry module once. | A file can hash cleanly and still be unloadable. Shallow for this revision: importing the entry module transitively loads most of the emitted graph for one import's cost. A per-module deep import is a revision, warranted if a partial emit is ever actually observed rather than in anticipation of one. |
+| `type_entry_presence` | `type_entry_presence` | `absent` | outputs.type_entry. | Consumers resolve types for the package export through this file, and the pack check already asserts its presence in the published tarball. Cheap, and it guards a real declared contract rather than an internal detail. |
+| `cli_skill_commit_agreement` | `cli_skill_commit_agreement` | `mismatched_generation` | The executable and the skills tree resolved by the running session. | Asserts that the executable a session runs and the skills tree it loads resolve below the same generation path and the same target OID. Two halves of a session drawn from different generations is the failure this catches, and neither hashes nor imports would notice it. |
+| `tool_versions` | `tool_versions` | `unsupported_tooling` | The Node and npm versions that actually executed the steps, against tooling.node and tooling.npm. | Recorded after the fact as well as checked before, so a generation carries evidence of what built it rather than only of what was permitted to. |
+| `input_fingerprint` | `input_fingerprint` | `stale` | The digest over the enumerated inputs.files recorded at build time, compared against the same digest computed at the target commit. | The one check that cannot be dropped. Stale output is internally consistent — its hashes are correct, it imports, its types are present — so it is invisible to every output-side check. Only comparing the inputs that produced it against the inputs at the target commit catches it. |
+
+### Prepared-runtime states
+
+Declarative descriptions of the prepared-runtime states an output-check implementation must distinguish. A test builds each state from the accepted recipe rather than from paths written down here, so adding a module to the input set cannot leave a fixture describing an inventory that no longer exists.
+
+| State | Expect | Detected as | Why it matters |
+|---|---|---|---|
+| `healthy` | pass | — | The control. Without it the four failure fixtures prove only that the checker fails, not that it discriminates. |
+| `absent` | fail | `absent` | Nothing was built, or the output directory was removed after the build. The inventory check is the only one that can report this cleanly; every other check would report a cascade. |
+| `extra` | fail | `extra` | Something other than the declared build wrote into the output directory. An unexpected file is as much a signal as a missing one. |
+| `corrupt` | fail | `corrupt` | A file was modified after the build recorded its digest. Caught by hash stability; the import smoke is the second line for the case where the alteration also makes the module unloadable. |
+| `stale` | fail | `stale` | The output is internally consistent — complete inventory, correct hashes, imports fine — but was produced from inputs that no longer match the target commit. Only the input fingerprint sees this. |
+
+## What the recipe assumes about the target
+
+What this revision assumes about the target, stated as values a checker can compare rather than as prose a reader has to trust. Each one is a thing that, if it changed without the recipe changing, would silently alter what preparation does: a widened engine range, a rewritten build script, a lockfile format the install step reads differently, or a new dependency that would execute code the moment the suppressing flag was dropped.
+
+| Assumption | Value |
+|---|---|
+| Manifest | `package.json` |
+| 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` |
+
+## Bounds
+
+| Bound | Value | Measured baseline | Applies to | Rationale |
+|---|---|---|---|---|
+| `install_seconds` | 180 seconds | about 3.2 seconds on a cold cache, about 0.3 seconds warm | Wall-clock duration of the install step. | Roughly 57x the measured cold-cache cost, and deliberately generous. The measurement is a fast local connection, which is the best case rather than the typical one; this bound has to hold on a cold cache, a congested network, a loaded machine, and in CI. A timeout that trips on a slow morning produces a refusal the operator cannot act on. |
+| `build_seconds` | 90 seconds | about 0.8 seconds | Wall-clock duration of the build step and the output checks that follow it. | Roughly 115x the measured cost. The whole mandatory check set adds well under a second on top, so nothing here is deferred for cost. Generous for the same reason as the install bound. |
+| `transaction_seconds` | 450 seconds | about 4 seconds end to end | Wall-clock duration of the whole preparation transaction: preconditions, both steps, and every output check. | Roughly 110x measured. It bounds the transaction as a whole rather than being the sum of its parts, so a phase that stalls short of its own bound still cannot hold a preparation open indefinitely. |
+| `max_output_bytes` | 16777216 bytes | 240,359 bytes | Total bytes of all files under outputs.directory after the build step. | 16 MiB, roughly 70x the measured output. This bound does not exist in the performance budget it otherwise mirrors; it is added so that a build which goes haywire is a typed refusal rather than a filled disk. |
+| `max_output_files` | 4096 files | 76 files | Count of files under outputs.directory after the build step. | Roughly 54x the measured count. Paired with max_output_bytes because the two catch different runaway shapes: many small files, and few enormous ones. |
+
+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.
+
+## Changing the recipe
+
+The line is consumer comprehension, not semantic significance. A NEW KIND is anything an installed consumer would have to newly understand in order to execute the document correctly: a different command or package manager, a changed network policy shape, a new KIND of output check, or a new required field. An older consumer must fail closed on it, and a consumer release comes first. A REVISION re-parameterises fields the consumer already understands: accepted version bounds, timeout values, the enumerated input set, the expected output inventory. An older consumer executes a revision correctly, with different numbers. Both owe a release-ledger entry; only a new kind gates on a consumer release. The test for which one applies is answerable in a fixture — does a consumer built against this schema parse and execute the document? — rather than by judgement about how big the change feels.
+
+The recipe and its schema are both HASHED supported-surface entries, so changing either requires `surface_version` to advance in the same change. The single authority for how a checkout of this repository at one commit becomes a usable installed runtime. No checker, schema, document, or test may carry its own copy of a command, a version bound, a timeout, an input path, or an output rule stated here — every one of them is read from this file. It is data, never code: a consumer executes exactly the argv enumerated in steps[] and never a command assembled from repository data. Registered as a HASHED supported-surface entry rather than a named one, deliberately departing from the policy contracts introduced alongside it: a reason-code vocabulary grows additively and can safely live behind a named entry, but any change to the commands, network policy, accepted tool versions, inputs, or output verification here is an agent-relevant release event by the recipe's own rule. Only a hashed entry makes such a change require surface_version to advance in the same change (scripts/check-supported-surface.mjs --base). A recipe whose commands can change without a version bump is not a contract. Changing this file also owes a release-ledger entry.
+
+## Refusals
+
+These documents are refused. Each is a single-mutation fixture under `contracts/fixtures/runtime-recipe/reject/`, so a refusal is always attributable to one change.
+
+| Fixture | Why it is refused |
+|---|---|
+| `reject/unknown-kind.json` | recipe_kind names a kind this schema version does not define. An installed consumer was not released knowing how to execute it, so it fails closed rather than guessing that a v2 is a v1 with extras. |
+| `reject/unknown-revision.json` | recipe_revision leaves the major line the kind defines. A revision may only re-parameterise fields the consumer already understands; a different major is a shape change wearing a revision's clothes. |
+| `reject/unknown-network-policy.json` | A safety-critical enum: the install step declares a network policy outside the defined set. There is no allow-all value, and an unrecognized one is refused rather than treated as permissive. |
+| `reject/allowlist-without-hosts.json` | An allowlist with no hosts is not a bound, it is an empty declaration that reads like one. The schema requires a non-empty host list whenever the policy is an allowlist. |
+| `reject/unknown-output-check.json` | A safety-critical enum: an output check names a kind the consumer cannot perform. A new KIND of check is a new recipe kind, because an installed consumer cannot perform a check it was not released knowing. |
+| `reject/unknown-step-id.json` | A safety-critical enum: a step identity outside the defined set. Steps are identified rather than positional, so an unrecognized id is a command the consumer has no contract for. |
+| `reject/lifecycle-scripts-enabled.json` | A safety-critical enum: a step that permits lifecycle scripts. Enabling them would let the target run arbitrary code during preparation, which is the single thing the recipe's flags exist to prevent. |
+| `reject/engines-disagreement-warns.json` | A safety-critical enum: disagreement between the contract's tool range and the target's declared engines resolved as a warning. An accept-with-warning path produces a build made under conditions nobody approved. |
+| `reject/advisory-enforcement.json` | fail_closed switched off. Advisory bounds record the right numbers and enforce nothing, so the first time a bound matters you discover it was decorative. |
+| `reject/unperformable-check-skipped.json` | A safety-critical enum: a check that cannot be performed treated as skipped. A skipped check reports success it never established. |
+| `reject/committed-output-claim.json` | The recipe claims its output directory is a committed artifact. It is not: the directory is git-ignored and untracked, so no baseline for its contents can exist here and verification must be self-consistency. |
+| `reject/unpinned-lockfile.json` | The recipe claims its lockfile is not integrity-pinned. The network allowlist bounds where bytes may come from and the lockfile's digests bound which bytes are acceptable; dropping the second leaves the first standing alone, which it was never meant to do. |
+| `reject/missing-required-field.json` | The enumerated input set is absent. Without it there is nothing to fingerprint, and staleness — the one failure mode no output-side check can see — becomes undetectable. |

package/docs/supported-surface.md

@@ -0,0 +1,83 @@
+# Supported surface
+
+This repo stopped being an implementation the day other tooling started building
+on it. Campaigns Agent pins schemas, contract docs, and a CLI argv surface;
+the private ops repo vendors the runtime schemas behind a byte-parity gate;
+page-kit campaign repos consume the artifacts the CLI emits. This document — and
+its machine twin, [`contracts/supported-surface.json`](../contracts/supported-surface.json),
+enforced by `scripts/check-supported-surface.mjs` in `npm run check` and CI —
+names exactly what those consumers may depend on. If it is not listed, it is
+implementation detail, however stable it looks.
+
+## What is supported
+
+| 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. |
+| `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 export `./legacy-migration` and its three schema exports | Portable SDK 0.3.x migration inventory, preview-plan, receipt, Offer request/readback, and token-free evidence helpers. Guide: [`docs/legacy-migration.md`](legacy-migration.md). | Pure contract only: no authenticated transport, write executor, audit store, receipt store, sessions, deletes, or rollback. Consumers own execution and must retain the guarded apply protocol. |
+| Package export `./text-safety` | `singleLineField`, `singleLineFragment` and `singleLineDetail`: flatten a value this toolkit did not author to one line with no control characters before it is rendered into a single-line notice. `singleLineField` is for a value printed as its own field (a run id, a target path): every control character becomes U+FFFD and nothing else changes. `singleLineFragment` is for a value folded into a sentence (a gate's repair command or instruction): line breaks and tabs become spaces, runs of whitespace collapse, the ends are trimmed, and every other control character becomes U+FFFD. `singleLineDetail` is `singleLineFragment` plus Markdown escaping, a length cap and a placeholder for an empty value (a quoted loader message). | Pure string functions, no imports, no I/O. Added at surface 1.27.0; `singleLineFragment` added at 1.27.0+agent.2. The escape set may widen; a value that was already safe stays unchanged. |
+| Contract docs: `CONTEXT.md`, `docs/campaigns-os-build-flow.md`, `docs/build-packet.md`, `docs/migration-sidecar-bundle.md`, `docs/design-source-package.md`, `docs/campaign-build-brief.md`, `docs/campaign-standardization-report.md`, `docs/brand-theme-bridge.md`, `docs/qa-and-test-orders.md`, `docs/legacy-migration.md`, `docs/versioning.md`, `docs/workflow-findings-sidecar.md`, this file | Named entry points consumers pin for context. | Content evolves freely; the path must keep existing. |
+| `skills.json` + `skills/` + `skills.sh` | Versioned skill packages and their installer. | Governed by `check-skill-versions.mjs` (parity + bump gate + reserved external names). `skills.json` ships in the npm pack as of surface 1.0.0. |
+| `compatibility.json` | The published compatibility statement. | Named; must keep existing. |
+| Orientation contract: `AGENTS.md`, `CHANGELOG.md`, `contracts/release-ledger.json`, `contracts/agent-relevant-change-policy.v1.json`, `contracts/orientation-limits.v1.json`, `contracts/orientation-reason-codes.v1.json`, `docs/orientation-contract-reference.md`, `docs/release-ledger-authoring-guide.md`, `contracts/fixtures/orientation/canonicalization/v1.json` | The declarative data a consumer reads from Git objects to decide whether a commit is safe to work against, without executing anything from this repository. Schema `campaigns-os-tooling-orientation/v1`; ledger schema `campaigns-os-release-ledger/v1`. The canonicalization fixture gives independent implementations exact ledger and changelog bytes plus their expected SHA-256 digests. Entry point: [`AGENTS.md`](../AGENTS.md). | Named. The ledger is append-only: a correction ships as a new amendment entry, never an edit. `scripts/check-release-ledger.mjs` enforces the two-way gate; `docs/orientation-contract-reference.md` and the canonicalization fixture are generated together, and CI fails if either is stale. |
+| Orientation fixtures: `contracts/fixtures/orientation/envelope/*.json`, `contracts/fixtures/orientation/hostile-target/**` (as named) | The bytes a consumer's parser validates against: one envelope per terminal outcome, plus a hostile target carrying Git hooks, an executable file, and npm lifecycle scripts for proving a reader executes nothing. The hostile target carries a second invariant for the runtime recipe: preparing it must run the recipe's own two steps and no lifecycle script reachable from them. | Named. Regenerate the envelopes with `npm run generate:orientation-docs`. Fixtures under `contracts/fixtures/` that are **not** named here — including the legacy-migration conformance corpus — are this repo's own test data and are not supported. |
+| Runtime recipe: `contracts/runtime-recipe.campaigns-os-node-v1.json` | The declarative description of how a checkout at one commit becomes a usable installed runtime: exact commands, accepted tool ranges, per-step network policy, the enumerated input set, the mandatory output checks, and the enforced bounds. This repository publishes it; the consumer bootstrap executes it. Guide: [`docs/runtime-readiness.md`](runtime-readiness.md). | **Hashed**, deliberately unlike the orientation policy contracts beside it. Any change to commands, network policy, tool versions, inputs, or output verification is an agent-relevant release event, and only a hashed entry makes such a change require `surface_version` to advance in the same PR. A recipe whose commands can change without a version bump is not a contract. |
+| Runtime-recipe fixtures: `contracts/fixtures/runtime-recipe/**` (as named), `docs/runtime-readiness.md` | Accept and single-mutation reject documents a consumer's parser validates against, the prepared-runtime states its output checks must distinguish, and the generated guide. | Named. All of it is generated — regenerate with `npm run generate:runtime-docs`; CI fails on a stale copy. |
+| Migration sidecar bundle: `contracts/migration-sidecar-bundle.v0.json`, `docs/migration-sidecar-bundle.md`, and `contracts/fixtures/sidecar-bundle/production-shaped/**` (as named) | The strict machine contract and production-shaped consumer fixture for the root Build Packet plus Build Context, Assembly Report, Doctor Output, and QA Verdict JSON sidecars. Packet selection uses `generated_at`, never mtime; raw spec integrity is distinct from canonical material identity; safe repository-relative spellings normalize without accepting traversal; markdown may coexist but is never readback truth. | The machine contract and schemas are hashed. The fixture is named byte-for-byte consumer input and must keep passing `campaigns-os bundle check --require-qa`. A required QA verdict with `disposition: blocked` keeps handoff nonconformant and sets `stage_blocked`. A doctor sidecar recording a blocked run emits `bundle.doctor_output.blocked`, and a blocked QA verdict `bundle.qa_verdict.blocked`, as warnings by default and errors under `--require-qa`; `stage_blocked` is unchanged; `status: conformant` never asserts that doctor or QA passed. |
+
+The Run Record lifecycle block keeps two duration meanings explicit:
+`duration_ms` is summed active command time, while `wall_clock_duration_ms` is
+the elapsed span between the first command start and last completion. Run
+sessions bind to an explicit packet across working directories, retain blocked
+QA attempts for repair, and close only on a ready verdict or explicit `run end`.
+Doctor and QA producers update only their matching Assembly Report stage with
+their current output paths and timestamps; they do not synthesize historical
+stage completion.
+
+Everything on this list must also **ship in the npm tarball** — the gate checks
+`package.json` `files[]` coverage, so "supported" can never mean "absent from
+the package a consumer installs."
+
+## What is NOT supported
+
+- `src/**` except the files reached through the explicit
+  `./commercial-journey`, `./commercial-parity`, and `./legacy-migration` package exports — including
+  files downstream context spines currently read
+  (`src/cli.mjs`, `src/qa-*.mjs`, `src/doctor-check-registry.mjs`, …). Reading
+  them for context is fine; importing or pinning behavior from them is not.
+  Doctor issue **codes** are contract-adjacent but currently governed by the
+  ops-repo ADR-003 parity baseline, not this manifest.
+- `scripts/**` — repo checkers, including this gate's own implementation.
+- `examples/**`, `prompts/**`, `agents/**` — illustrative, regenerated at will.
+- `contracts/**` other than `supported-surface.json`,
+  `reserved-skill-names.json`, and the orientation contract/fixture entries
+  named in the manifest — internal build/QA contract data. In particular,
+  `contracts/fixtures/orientation/release-gate/cases.json` is this repo's own
+  release-gate test matrix, not a consumer contract.
+- CLI output text, log lines, and human-facing handoff strings. Machine-readable
+  artifact fields are governed by their schemas, not by prose.
+
+## Changing the surface
+
+1. Make the change and update `contracts/supported-surface.json` (hash and/or
+   entries) in the same PR.
+2. Bump `surface_version` when any hashed file changed (the `--base` gate in CI
+   enforces this; parity runs in every `npm run check`). Also bump it when the
+   manifest adds a `cli_commands`, `package_exports`, or `bin` entry: those are
+   additive public-surface expansions even though the gate cannot yet derive
+   the owed bump automatically.
+3. Add a release-ledger entry. Every agent-relevant change — hashed or named
+   path, CLI command/subcommand/flag, skill, schema, package export,
+   compatibility policy, agent-facing documentation, workflow, or generated
+   runtime — owes exactly one entry in `contracts/release-ledger.json`, whether
+   or not `surface_version` moved. `scripts/check-release-ledger.mjs --base`
+   enforces this in both directions. See
+   [the authoring guide](release-ledger-authoring-guide.md).
+4. Breaking a consumer-visible shape? New schema-version const, and say so in
+   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.