@nextcommerce/campaigns-os 1.33.0

package/agents/copilot/copilot-instructions.md

@@ -0,0 +1,14 @@
+# Campaigns OS Instructions
+
+When this repository contains Campaigns OS artifacts, use them as the build handoff:
+
+- `campaign-runtime.build.json` defines the CampaignSpec, source adapter, target output, template family, deploy target, SDK origin state, and QA proof depth.
+- `.campaign-runtime/build-context.json` records page mappings and setup/build handoff details.
+- `.campaign-runtime/assembly-report.json` records stage evidence and blockers.
+- `.campaign-runtime/theme/theme-report.json`, when present, is optional brand-theme evidence. Generated `brand-theme.css` must load after `next-core.css`; missing or low-confidence theme is a warning/skipped reason, not permission to edit SDK-owned runtime surfaces.
+
+CampaignSpec validation is owned by the public `@nextcommerce/campaigns-os/campaign-spec` rules surfaced through doctor `spec.validation` findings; use structured rule/path detail when available.
+
+Preserve Campaign Cart SDK-owned commerce surfaces. Replace starter demo refs from CampaignSpec/API. Prepared AI/exported HTML must be converted into page-kit-ready source first: keep page-owned body markup, strip document wrappers, add YAML frontmatter, move shared CSS/assets into the campaign structure, and use Liquid helpers only for page-kit links/assets/includes. Landing/presell pages can preserve source design; checkout/upsell/downsell/receipt should use starter-template commerce surfaces as SDK contract references while campaign/source owns visual chrome. Copy starter template families atomically with dependent pages, `_includes/`, `_layouts/`, `assets/css/`, and `assets/js/`; do not copy only checkout/receipt pages. Do not claim launch readiness until build, polish, deploy, and QA evidence are recorded.
+
+Before Polish becomes terminal or hands off to deploy/QA, install the package-owned Playwright browser with `npm run qa:install-browser`, serve the current build, and run `campaigns-os polish capture --packet campaign-runtime.build.json --base-url <served-current-build-url>`. After that checkpoint clears, QA must use the Campaigns OS Node/npm runner: run `campaigns-os qa resolve`, then run `campaigns-os qa run --browser --test-order common` against the tested URL. Typed-card test-order proof must use `campaigns-os qa run --test-order <common|checkout|decline|accept|both|full|explicit-path>` through the tested checkout and rendered upsell controls; global test cards bypass the gateway and create no transactions, so no permission/approval is needed. `common` runs the checkout baseline, first-offer accept and decline, and a deduplicated shortest real receipt path when that adds coverage (at most four orders). `full` walks every actual terminal path in the selected checkout topology; cycles, missing routes, and reachable nonterminals block exhaustive proof before browser launch. The accidental-flood cap remains `6`, and an overflow names the exact explicit `--max-test-orders` raise. Analytics correctness is two-phase: the campaign-root visit inventories declared providers/tags only, and the same canonical typed-card run proves Purchase only from the topology-recognized final receipt document after `--analytics-settle`. Missing/unrecognized receipts are manual-review warnings; recognized receipt no-signal and capture/settle errors block. Only the genuine recognized-receipt/no-signal failure is waivable; capture/settle errors are not. Checkout/upsell signals remain whole-journey parity evidence and cannot satisfy a silent receipt. Do not use `next.getCartData().cartLines` as cart-populated proof; use typed-card order read-back, `cart:updated` payload `items` / `summary.lines`, and rendered bundle DOM evidence. Localhost on any port is a Campaigns App Development domain for SDK QA with analytics suppressed; non-localhost preview/production origins still need SDK origin allowlist confirmation. Do not use external browser skills, SDK test-mode events, or direct backend orders as launch proof. Campaigns OS proof is not merchant launch readiness; before launch, confirm production storefront URL, live payment methods, shipping markets, legal/support URLs, analytics expectations, and merchant-side configuration.

package/agents/cursor/campaigns-os.mdc

@@ -0,0 +1,13 @@
+---
+description: Campaigns OS target campaign guidance
+globs:
+  - "campaign-runtime.build.json"
+  - ".campaign-runtime/**/*.json"
+alwaysApply: false
+---
+
+Read Campaigns OS artifacts before editing campaign pages. Treat CampaignSpec/API values as live commerce truth, starter-template contracts as SDK surface truth, and designed HTML/assets as visual/content intent. Treat CampaignSpec validation as owned by the public `@nextcommerce/campaigns-os/campaign-spec` rules surfaced through doctor `spec.validation` findings; use structured rule/path detail when available. If `context.theme` or `.campaign-runtime/theme/theme-report.json` exists, use it as optional brand-theme evidence; generated `brand-theme.css` must load after `next-core.css`, and missing/low-confidence theme is a warning or skipped reason, not permission to edit SDK-owned runtime surfaces.
+
+Do not carry over demo package, shipping, voucher, payment, tracking, footer, or SEO values. Prepared AI/exported HTML must be converted into page-kit-ready source first: keep page-owned body markup, strip document wrappers, add YAML frontmatter, move shared CSS/assets into the campaign structure, and use Liquid helpers only for page-kit links/assets/includes. Preserve prepared landing/presell source HTML when it is a real standalone design. For checkout/upsell/downsell/receipt, use starter-template commerce surfaces as SDK contract references while campaign/source owns visual chrome. Copy starter template families atomically with dependent pages, `_includes/`, `_layouts/`, `assets/css/`, and `assets/js/`; do not copy only checkout/receipt pages. Emit SDK routing meta tags as campaign-root paths such as `/campaign-slug/upsell/`. Preserve SDK-owned checkout/cart/upsell/receipt surfaces. For `shop-three-step`, shipping is dynamic via `window.next.getShippingMethods()`.
+
+Before Polish becomes terminal or hands off to deploy/QA, install the package-owned Playwright browser with `npm run qa:install-browser`, serve the current build, and run `campaigns-os polish capture --packet campaign-runtime.build.json --base-url <served-current-build-url>`. After that checkpoint clears, QA uses the Campaigns OS Node/npm runner: `campaigns-os qa resolve`, then `campaigns-os qa run --browser --test-order common` against the tested URL. Test-order proof uses `campaigns-os qa run --test-order <common|checkout|decline|accept|both|full|explicit-path>` through the tested checkout and rendered upsell controls; global test cards bypass the gateway and create no transactions, so no permission/approval is needed. `common` runs the checkout baseline, first-offer accept and decline, and a deduplicated shortest real receipt path when that adds coverage (at most four orders). `full` walks every actual terminal path in the selected checkout topology; cycles, missing routes, and reachable nonterminals block exhaustive proof before browser launch. The accidental-flood cap remains `6`, and an overflow names the exact explicit `--max-test-orders` raise. Analytics correctness is two-phase: the campaign-root visit inventories declared providers/tags only, and the same canonical typed-card run proves Purchase only from the topology-recognized final receipt document after `--analytics-settle`. Missing/unrecognized receipts are manual-review warnings; recognized receipt no-signal and capture/settle errors block. Only the genuine recognized-receipt/no-signal failure is waivable; capture/settle errors are not. Checkout/upsell signals remain whole-journey parity evidence and cannot satisfy a silent receipt. Do not use `next.getCartData().cartLines` as cart-populated proof; use typed-card order read-back, `cart:updated` payload `items` / `summary.lines`, and rendered bundle DOM evidence. Localhost on any port is a Campaigns App Development domain for SDK QA with analytics suppressed; non-localhost preview/production origins still need SDK origin allowlist confirmation. External browser skills, SDK test-mode events, and direct backend orders are not launch proof. Campaigns OS proof is not merchant launch readiness; before launch, confirm production storefront URL, live payment methods, shipping markets, legal/support URLs, analytics expectations, and merchant-side configuration.

package/bin/campaigns-os.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+import { main } from "../src/cli.mjs";
+
+// Filesystem errno codes worth a friendly, path-named message instead of the
+// raw Node error string. Each maps `where` (": <path>" when known, else "")
+// to a full message. Only ENOENT gets the "run start first" packet hint — for
+// permission/type errors that guidance would be wrong, and EACCES is not
+// read-specific (a write to an unwritable target raises it too).
+const FS_ERRNO_MESSAGE = {
+  ENOENT: (where) =>
+    `file not found${where}. Check the path; ` +
+    "run `campaigns-os start ...` first if you have not generated the packet yet.",
+  EACCES: (where) => `permission denied accessing${where}. Check the file's permissions.`,
+  EPERM: (where) => `operation not permitted on${where}. Check the file's permissions.`,
+  EISDIR: (where) => `expected a file but found a directory${where}. Check the path.`,
+  ENOTDIR: (where) => `a path segment is not a directory${where}. Check the path.`,
+};
+
+main(process.argv.slice(2)).catch((error) => {
+  // Rewrite raw Node filesystem errno errors (e.g. a mistyped or unreadable
+  // --packet path) into a clearer message, instead of leaking bare errno
+  // strings like `ENOENT: no such file or directory, open '...'`.
+  const buildMessage = error && error.code ? FS_ERRNO_MESSAGE[error.code] : null;
+  if (buildMessage) {
+    // `error.path` is present for open-time failures (ENOENT/EACCES/EPERM/
+    // ENOTDIR) but absent for read-time ones (EISDIR reading a directory), so
+    // name the path only when we have it.
+    const where = typeof error.path === "string" ? `: ${error.path}` : "";
+    console.error(`campaigns-os: ${buildMessage(where)}`);
+    process.exit(1);
+  }
+  // main() normally rejects with an Error, but guard against a non-Error throw
+  // (a string, number, or Promise.reject("boom")) so the user never sees
+  // `campaigns-os: undefined`.
+  console.error(`campaigns-os: ${String(error?.message ?? error)}`);
+  process.exit(1);
+});

package/campaign-spec/README.md

@@ -0,0 +1,138 @@
+# campaign-spec
+
+The CampaignSpec contract layer: a normalize phase, a composable rule registry,
+and a canonical fixture corpus. Read `../CONTEXT.md` first for vocabulary
+(`CampaignSpec`, `Rule`, `Violation`, `Tag`, `Corpus`).
+
+This module is the single, public source of truth for CampaignSpec validation.
+The Campaigns OS CLI doctor runs these rules during spec validation, and any
+campaign authoring UI (such as a Map Builder bundle) can import the same registry
+so internal teams and third-party agencies validate against identical rules. The
+rules are pure TypeScript over a normalized spec with no heavy dependencies.
+
+## Layout
+
+```
+campaign-spec/
+  index.ts                 # public interface
+  types.ts                 # CampaignSpec, Rule, Violation, Tag, Severity
+  normalize.ts             # v4.3 authoring → canonical v4.2 funnels[] shape
+  rules/
+    index.ts               # preset RuleSet constants
+    cycle-detection.ts     # one file per rule
+    ...
+  fixtures/
+    index.ts               # corpus loader
+    *.json                 # specs
+    expected/*.json        # expected violations per spec
+  test/
+    rules/*.test.ts        # per-rule unit tests
+    corpus.test.ts         # corpus contract test
+```
+
+## Public interface
+
+```ts
+import {
+  // Types
+  type CampaignSpec, type Rule, type Violation, type Tag,
+  // Phases
+  normalize, runRules, validateSpec,
+  // Presets
+  allRules, fastRules, specOnlyRules,
+} from './campaign-spec'
+
+// Backwards-compat (= runRules(allRules, normalize(spec)))
+const violations = validateSpec(spec)
+
+// Composable
+const violations = runRules(normalize(spec), fastRules)
+
+// Custom selection
+const violations = runRules(
+  normalize(spec),
+  allRules.filter(r => r.tags.includes('structure') && r.id !== 'CycleDetection'),
+)
+```
+
+## Rule shape
+
+```ts
+type Rule = {
+  id: string                    // unique, stable; appears in Violation.ruleId
+  severity: 'error' | 'warning' // default; per-violation can override
+  tags: Tag[]                   // closed set, see types.ts
+  check(spec: CampaignSpec): Violation[]
+}
+```
+
+Rules are **pure** over a normalized spec. No context bag. No live data
+dependency. Mode flags ("partial spec mid-edit", "fast mode") are tag filters,
+not context flags. Rule parameters are bound at registration time.
+
+## Violation shape
+
+```ts
+type Violation = {
+  ruleId: string
+  severity: 'error' | 'warning'
+  message: string
+  path: string                  // JSON Pointer: /funnels/0/pages/2/route
+  data?: Record<string, unknown>
+}
+```
+
+`path` enables field-level UI without rule-specific wiring. `data` carries
+structured detail.
+
+## Adding a rule
+
+1. Create `rules/your-rule.ts`. Export a `Rule` value.
+2. Add it to the `allRules` array in `rules/index.ts`. If it belongs in
+   `fastRules` or `specOnlyRules`, add it to those too.
+3. Add a unit test in `test/rules/your-rule.test.ts` that loads a focused
+   fixture and asserts the violations.
+4. If the rule needs a new fixture, add `fixtures/<name>.json` and
+   `fixtures/expected/<name>.expected.json`. The corpus contract test will
+   pick it up automatically.
+
+## Adding a tag
+
+Edit the `Tag` union in `types.ts` and the tag inventory in `../CONTEXT.md`.
+The closed taxonomy is intentional — closed sets are documented; open sets
+drift.
+
+## Tests
+
+The suite runs on `node --test` (no bun dependency); `test/harness.ts` is a thin
+adapter mapping the matchers used onto `node:assert`.
+
+```bash
+# from the campaigns-os package root
+npm run check:spec
+# or directly
+node --test "campaign-spec/test/**/*.test.ts"
+```
+
+Three surfaces:
+
+- **Per-rule** (`test/rules/*.test.ts`): focused fixtures, focused assertions.
+- **Corpus contract** (`test/corpus.test.ts`): every fixture asserted against
+  its expected violations across all rules. Drift lights up exactly which
+  fixture diffed.
+- **Compiled bundle** (`test/dist-smoke.test.ts`): imports the built
+  `dist/index.js` to prove `npm run build:spec` produced a working ESM module
+  with the full public surface (run `build:spec` first).
+
+## Consuming from a browser bundle
+
+A campaign authoring UI can bundle this module (e.g. with esbuild as a browser
+IIFE) and expose the public interface on `window` to run export-time validation
+client-side. The rules have no Node-only or live-data dependencies, so the same
+registry that backs the CLI doctor runs unchanged in the browser.
+
+## See also
+
+- `../CONTEXT.md` — domain vocabulary.
+- v4.1 spec topology is intentionally unsupported: `normalize()` rejects
+  `funnel_pages` input rather than silently wrapping it.

package/campaign-spec/dist/analytics-vocabulary.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Analytics dl_* event vocabulary — SYNCED SNAPSHOT from the Campaign Cart SDK.
+ *
+ * SOURCE OF TRUTH: campaign-cart `src/utils/analytics/schemas/events.ts`
+ * (`DL_EVENTS`), carried via its generated `events.manifest.json`.
+ * Synced from SDK v0.4.30 (manifest event list unchanged since v0.4.28).
+ *
+ * Why a snapshot, not an import: campaigns-os is the public toolkit and takes
+ * no dependency on the browser SDK bundle (wrong direction, heavy). This module
+ * is the canonical CONSUMABLE the validator (AnalyticsContractShape) and the Map
+ * Builder picker (via the campaign-spec.js shim) both read, so they validate /
+ * autocomplete against exactly one list (cf. ADR-003, one rule registry).
+ *
+ * RESYNC when the SDK adds/removes a dl_* event: copy the manifest events array
+ * here verbatim and bump the SDK version line above. The accompanying test
+ * (analytics-vocabulary.test.ts) guards internal consistency.
+ *
+ * The vocabulary is the SDK FIRABLE SUPERSET (~35), not just the schema-bearing
+ * events: blockedEvents matches by exact event name against everything the SDK
+ * dispatches, so any fired event must be a known/blockable member.
+ */
+export type DlEventCategory = 'ecommerce' | 'user' | 'upsell' | 'cart' | 'navigation' | 'engagement';
+export interface DlEventDefinition {
+    /** Exact dataLayer event name the SDK pushes — matched verbatim by blockedEvents. */
+    name: string;
+    /** Coarse grouping for picker UIs. */
+    category: DlEventCategory;
+    /** True when the SDK defines a field-level validation schema for this event. */
+    hasSchema: boolean;
+    /** Human label for picker UIs and repair prompts. */
+    description: string;
+}
+/** SDK version whose manifest this snapshot was last checked against. */
+export declare const CAMPAIGN_CART_ANALYTICS_VOCABULARY_SDK_VERSION = "0.4.30";
+/**
+ * First Campaign Cart SDK version that stamps campaign_* and ncsid-derived
+ * campaign_session_id identifiers on every analytics event.
+ */
+export declare const CAMPAIGN_CART_ANALYTICS_IDENTITY_MIN_SDK_VERSION = "0.4.30";
+/** The canonical vocabulary, category-grouped (mirrors the SDK manifest order). */
+export declare const DL_EVENTS: readonly DlEventDefinition[];
+/** Flat list of canonical event names. */
+export declare const DL_EVENT_NAMES: readonly string[];
+/** O(1) membership set for validation. */
+export declare const DL_EVENT_NAME_SET: ReadonlySet<string>;
+/** True when name is a known canonical SDK dl_* event. */
+export declare function isKnownDlEvent(name: string): boolean;

package/campaign-spec/dist/analytics-vocabulary.js

@@ -0,0 +1,74 @@
+/**
+ * Analytics dl_* event vocabulary — SYNCED SNAPSHOT from the Campaign Cart SDK.
+ *
+ * SOURCE OF TRUTH: campaign-cart `src/utils/analytics/schemas/events.ts`
+ * (`DL_EVENTS`), carried via its generated `events.manifest.json`.
+ * Synced from SDK v0.4.30 (manifest event list unchanged since v0.4.28).
+ *
+ * Why a snapshot, not an import: campaigns-os is the public toolkit and takes
+ * no dependency on the browser SDK bundle (wrong direction, heavy). This module
+ * is the canonical CONSUMABLE the validator (AnalyticsContractShape) and the Map
+ * Builder picker (via the campaign-spec.js shim) both read, so they validate /
+ * autocomplete against exactly one list (cf. ADR-003, one rule registry).
+ *
+ * RESYNC when the SDK adds/removes a dl_* event: copy the manifest events array
+ * here verbatim and bump the SDK version line above. The accompanying test
+ * (analytics-vocabulary.test.ts) guards internal consistency.
+ *
+ * The vocabulary is the SDK FIRABLE SUPERSET (~35), not just the schema-bearing
+ * events: blockedEvents matches by exact event name against everything the SDK
+ * dispatches, so any fired event must be a known/blockable member.
+ */
+/** SDK version whose manifest this snapshot was last checked against. */
+export const CAMPAIGN_CART_ANALYTICS_VOCABULARY_SDK_VERSION = '0.4.30';
+/**
+ * First Campaign Cart SDK version that stamps campaign_* and ncsid-derived
+ * campaign_session_id identifiers on every analytics event.
+ */
+export const CAMPAIGN_CART_ANALYTICS_IDENTITY_MIN_SDK_VERSION = '0.4.30';
+/** The canonical vocabulary, category-grouped (mirrors the SDK manifest order). */
+export const DL_EVENTS = [
+    { name: 'dl_view_item_list', category: 'ecommerce', hasSchema: true, description: 'Product list / collection impression' },
+    { name: 'dl_view_item', category: 'ecommerce', hasSchema: true, description: 'Product detail view' },
+    { name: 'dl_select_item', category: 'ecommerce', hasSchema: true, description: 'Product clicked from a list' },
+    { name: 'dl_view_search_results', category: 'ecommerce', hasSchema: true, description: 'Search results viewed' },
+    { name: 'dl_search', category: 'ecommerce', hasSchema: false, description: 'Search performed (Meta Search)' },
+    { name: 'dl_add_to_cart', category: 'ecommerce', hasSchema: true, description: 'Item added to cart' },
+    { name: 'dl_remove_from_cart', category: 'ecommerce', hasSchema: true, description: 'Item removed from cart' },
+    { name: 'dl_add_to_wishlist', category: 'ecommerce', hasSchema: false, description: 'Item added to wishlist' },
+    { name: 'dl_view_cart', category: 'ecommerce', hasSchema: true, description: 'Cart viewed' },
+    { name: 'dl_begin_checkout', category: 'ecommerce', hasSchema: true, description: 'Checkout started' },
+    { name: 'dl_add_shipping_info', category: 'ecommerce', hasSchema: true, description: 'Shipping info added' },
+    { name: 'dl_add_payment_info', category: 'ecommerce', hasSchema: true, description: 'Payment info added' },
+    { name: 'dl_purchase', category: 'ecommerce', hasSchema: true, description: 'Main order purchase' },
+    { name: 'dl_refund', category: 'ecommerce', hasSchema: false, description: 'Order refunded (adapter-mapped)' },
+    { name: 'dl_view_promotion', category: 'ecommerce', hasSchema: false, description: 'Promotion impression' },
+    { name: 'dl_select_promotion', category: 'ecommerce', hasSchema: false, description: 'Promotion clicked' },
+    { name: 'dl_user_data', category: 'user', hasSchema: true, description: 'User + cart context (fired first)' },
+    { name: 'dl_sign_up', category: 'user', hasSchema: true, description: 'Account sign-up' },
+    { name: 'dl_login', category: 'user', hasSchema: true, description: 'Account login' },
+    { name: 'dl_subscribe', category: 'user', hasSchema: true, description: 'Subscription created' },
+    { name: 'dl_start_trial', category: 'user', hasSchema: false, description: 'Trial started (Meta StartTrial)' },
+    { name: 'dl_viewed_upsell', category: 'upsell', hasSchema: true, description: 'Upsell offer viewed' },
+    { name: 'dl_accepted_upsell', category: 'upsell', hasSchema: true, description: 'Upsell accepted' },
+    { name: 'dl_skipped_upsell', category: 'upsell', hasSchema: true, description: 'Upsell skipped' },
+    { name: 'dl_upsell_purchase', category: 'upsell', hasSchema: true, description: 'Accepted upsell in GA4 purchase format' },
+    { name: 'dl_cart_updated', category: 'cart', hasSchema: false, description: 'Cart contents changed' },
+    { name: 'dl_package_swapped', category: 'cart', hasSchema: false, description: 'Package variant swapped' },
+    { name: 'dl_page_view', category: 'navigation', hasSchema: false, description: 'SDK page view' },
+    { name: 'dl_route_changed', category: 'navigation', hasSchema: false, description: 'Funnel route changed' },
+    { name: 'dl_scroll_depth', category: 'engagement', hasSchema: false, description: 'Scroll-depth milestone reached' },
+    { name: 'dl_exit_intent_shown', category: 'engagement', hasSchema: false, description: 'Exit-intent offer shown' },
+    { name: 'dl_exit_intent_accepted', category: 'engagement', hasSchema: false, description: 'Exit-intent offer accepted' },
+    { name: 'dl_exit_intent_dismissed', category: 'engagement', hasSchema: false, description: 'Exit-intent offer dismissed' },
+    { name: 'dl_exit_intent_closed', category: 'engagement', hasSchema: false, description: 'Exit-intent modal closed' },
+    { name: 'dl_exit_intent_action', category: 'engagement', hasSchema: false, description: 'Exit-intent CTA/action clicked' },
+];
+/** Flat list of canonical event names. */
+export const DL_EVENT_NAMES = DL_EVENTS.map((e) => e.name);
+/** O(1) membership set for validation. */
+export const DL_EVENT_NAME_SET = new Set(DL_EVENT_NAMES);
+/** True when name is a known canonical SDK dl_* event. */
+export function isKnownDlEvent(name) {
+    return DL_EVENT_NAME_SET.has(name);
+}

package/campaign-spec/dist/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * campaign-spec — the CampaignSpec contract layer.
+ *
+ * Public interface for the spec validation module — the single source
+ * of truth for CampaignSpec validation. The Campaigns OS CLI doctor and
+ * any campaign authoring UI (e.g. a Map Builder browser bundle built
+ * from this module) import from here, so internal teams and third-party
+ * agencies validate against the same rules.
+ *
+ * Read ../CONTEXT.md for vocabulary (CampaignSpec, Rule, Violation, Tag,
+ * Corpus, normalize) and ./README.md for usage patterns.
+ */
+import type { CampaignSpec, RuleSet, Violation } from './types.ts';
+export type { CampaignSpec, Rule, RuleSet, Violation, Tag, Severity, Fixture, Page, PageType, Funnel, Offer, Campaign, DesignSource, DesignSourceBreakpoints, TemplateFamilyHint, UpsellTemplatePattern, UpsellMvTiers, VariantLabels, PromoCode, AnalyticsContract, AnalyticsMode, AnalyticsProvider, OutOfBandPixel, ManualEvent, ContentParam, TrackingParams, AnalyticsParams, UtmTransfer, } from './types.ts';
+export { normalize, NormalizeError } from './normalize.ts';
+export { FORWARD_ROUTE_FIELDS, ACCEPT_ROUTE_FIELD, DECLINE_ROUTE_FIELD, ROUTE_FIELDS, PAYMENT_BEARING_PAGE_TYPES, OFFER_BEARING_PAGE_TYPES, forwardRouteTarget, acceptRouteTarget, declineRouteTarget, hasForwardRoute, applicableForwardFields, inapplicableForwardFields, describeForwardField, outgoingEdgeIds, } from './routing.ts';
+export type { ForwardFieldApplicability } from './routing.ts';
+export { allRules, fastRules, specOnlyRules } from './rules/index.ts';
+export { SUPPORTED_SCHEMA_VERSIONS } from './rules/schema-version.ts';
+export { RELEASED_SDK_VERSION_PATTERN, parseSdkVersion, isReleasedSdkVersion, describeSdkVersionRejection, } from './sdk-version-parse.ts';
+export type { SdkVersionParseResult, SdkVersionRejectionReason, } from './sdk-version-parse.ts';
+export { CAMPAIGN_CART_ANALYTICS_IDENTITY_MIN_SDK_VERSION, CAMPAIGN_CART_ANALYTICS_VOCABULARY_SDK_VERSION, DL_EVENTS, DL_EVENT_NAMES, DL_EVENT_NAME_SET, isKnownDlEvent, } from './analytics-vocabulary.ts';
+export type { DlEventCategory, DlEventDefinition, } from './analytics-vocabulary.ts';
+/**
+ * Run a RuleSet against a normalized spec. Returns the flat list of
+ * violations across all rules; callers choose their failure policy (throw on
+ * any error, collect for UI, etc.).
+ *
+ *   const violations = runRules(normalize(spec), allRules)
+ *   if (violations.some(v => v.severity === 'error')) { ... }
+ */
+export declare function runRules(spec: CampaignSpec, rules: RuleSet): Violation[];
+/**
+ * Backwards-compatible entry point: normalize → run all rules.
+ *
+ * Equivalent to `runRules(normalize(input), allRules)`. Catches NormalizeError
+ * and surfaces it as a single error-severity Violation so legacy callers that
+ * expect a flat array don't need to handle exceptions.
+ */
+export declare function validateSpec(input: unknown): Violation[];

package/campaign-spec/dist/index.js

@@ -0,0 +1,77 @@
+/**
+ * campaign-spec — the CampaignSpec contract layer.
+ *
+ * Public interface for the spec validation module — the single source
+ * of truth for CampaignSpec validation. The Campaigns OS CLI doctor and
+ * any campaign authoring UI (e.g. a Map Builder browser bundle built
+ * from this module) import from here, so internal teams and third-party
+ * agencies validate against the same rules.
+ *
+ * Read ../CONTEXT.md for vocabulary (CampaignSpec, Rule, Violation, Tag,
+ * Corpus, normalize) and ./README.md for usage patterns.
+ */
+import { normalize, NormalizeError } from "./normalize.js";
+import { allRules } from "./rules/index.js";
+export { normalize, NormalizeError } from "./normalize.js";
+// Outgoing-edge resolution — the single source of truth for "where does this
+// page go". Source intake, cycle detection and the QA topology extractor all
+// consume these rather than keeping their own page-type tables.
+export { FORWARD_ROUTE_FIELDS, ACCEPT_ROUTE_FIELD, DECLINE_ROUTE_FIELD, ROUTE_FIELDS, PAYMENT_BEARING_PAGE_TYPES, OFFER_BEARING_PAGE_TYPES, forwardRouteTarget, acceptRouteTarget, declineRouteTarget, hasForwardRoute, applicableForwardFields, inapplicableForwardFields, describeForwardField, outgoingEdgeIds, } from "./routing.js";
+export { allRules, fastRules, specOnlyRules } from "./rules/index.js";
+// Supported schema_version matrix — single source for the SchemaVersion rule
+// and any consumer that needs to present or gate on the supported lineages.
+// A sync test pins it to the schemas/campaign-spec.v4.schema.json enum.
+export { SUPPORTED_SCHEMA_VERSIONS } from "./rules/schema-version.js";
+// Strict released-SDK-version parser — shared with the downstream Page Kit
+// SDK-version checkpoint (src/page-kit-sdk-version.mjs) so authoring-time
+// validation and build-time gating reject exactly the same values.
+export { RELEASED_SDK_VERSION_PATTERN, parseSdkVersion, isReleasedSdkVersion, describeSdkVersionRejection, } from "./sdk-version-parse.js";
+// Canonical dl_* analytics event vocabulary — synced from the Campaign Cart SDK.
+// The AnalyticsContractShape rule validates blockedEvents against it; the Map
+// Builder picker (via the campaign-spec.js shim) autocompletes from it.
+export { CAMPAIGN_CART_ANALYTICS_IDENTITY_MIN_SDK_VERSION, CAMPAIGN_CART_ANALYTICS_VOCABULARY_SDK_VERSION, DL_EVENTS, DL_EVENT_NAMES, DL_EVENT_NAME_SET, isKnownDlEvent, } from "./analytics-vocabulary.js";
+// ── Phases ─────────────────────────────────────────────────────────────────
+/**
+ * Run a RuleSet against a normalized spec. Returns the flat list of
+ * violations across all rules; callers choose their failure policy (throw on
+ * any error, collect for UI, etc.).
+ *
+ *   const violations = runRules(normalize(spec), allRules)
+ *   if (violations.some(v => v.severity === 'error')) { ... }
+ */
+export function runRules(spec, rules) {
+    const out = [];
+    for (const rule of rules) {
+        for (const violation of rule.check(spec)) {
+            out.push(violation);
+        }
+    }
+    return out;
+}
+/**
+ * Backwards-compatible entry point: normalize → run all rules.
+ *
+ * Equivalent to `runRules(normalize(input), allRules)`. Catches NormalizeError
+ * and surfaces it as a single error-severity Violation so legacy callers that
+ * expect a flat array don't need to handle exceptions.
+ */
+export function validateSpec(input) {
+    let spec;
+    try {
+        spec = normalize(input);
+    }
+    catch (err) {
+        if (err instanceof NormalizeError) {
+            return [
+                {
+                    ruleId: 'Normalize',
+                    severity: 'error',
+                    message: err.message,
+                    path: '',
+                },
+            ];
+        }
+        throw err;
+    }
+    return runRules(spec, allRules);
+}

package/campaign-spec/dist/normalize.d.ts

@@ -0,0 +1,22 @@
+/**
+ * normalize — the single phase that takes an authoring CampaignSpec and emits
+ * the canonical v4.2 funnels[] shape that rules operate on.
+ *
+ * Today this is near-empty: v4.3 already uses funnels[]. The phase exists so
+ * future authoring evolutions have one place to land their migration.
+ *
+ * v4.1 (funnel_pages[]) is intentionally NOT supported — see
+ * ../docs/adr/002-drop-v41-spec-support.md. Inputs without `funnels[]` fail
+ * the structural assertion below.
+ */
+import type { CampaignSpec } from './types.ts';
+/**
+ * Thrown when input is structurally unrecognizable as a CampaignSpec.
+ * Distinct from rule violations: a violation means "this spec is wrong";
+ * a NormalizeError means "this isn't a spec at all (or it's an unsupported
+ * legacy version)."
+ */
+export declare class NormalizeError extends Error {
+    constructor(message: string);
+}
+export declare function normalize(input: unknown): CampaignSpec;

package/campaign-spec/dist/normalize.js

@@ -0,0 +1,41 @@
+/**
+ * normalize — the single phase that takes an authoring CampaignSpec and emits
+ * the canonical v4.2 funnels[] shape that rules operate on.
+ *
+ * Today this is near-empty: v4.3 already uses funnels[]. The phase exists so
+ * future authoring evolutions have one place to land their migration.
+ *
+ * v4.1 (funnel_pages[]) is intentionally NOT supported — see
+ * ../docs/adr/002-drop-v41-spec-support.md. Inputs without `funnels[]` fail
+ * the structural assertion below.
+ */
+/**
+ * Thrown when input is structurally unrecognizable as a CampaignSpec.
+ * Distinct from rule violations: a violation means "this spec is wrong";
+ * a NormalizeError means "this isn't a spec at all (or it's an unsupported
+ * legacy version)."
+ */
+export class NormalizeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NormalizeError';
+    }
+}
+export function normalize(input) {
+    if (input == null || typeof input !== 'object') {
+        throw new NormalizeError('CampaignSpec must be an object.');
+    }
+    const obj = input;
+    // v4.1 detection: top-level funnel_pages without funnels[] means a legacy
+    // spec. We reject explicitly to make the migration visible.
+    if (!Array.isArray(obj.funnels) && Array.isArray(obj.funnel_pages)) {
+        throw new NormalizeError('CampaignSpec uses legacy v4.1 funnel_pages topology. v4.1 is not supported (ADR-002). ' +
+            'Migrate the spec to v4.2+ funnels[] before validating.');
+    }
+    if (!Array.isArray(obj.funnels)) {
+        throw new NormalizeError('CampaignSpec is missing funnels[]. Expected canonical v4.2+ topology.');
+    }
+    // Future migrations (v5 → v4, etc.) land here. Today the shape is already
+    // canonical, so pass through.
+    return obj;
+}