@nextcommerce/campaigns-os 1.33.0

package/campaign-spec/dist/rules/schema-version.d.ts

@@ -0,0 +1,21 @@
+/**
+ * SchemaVersion — requires spec.schema_version and validates it against the
+ * supported lineage matrix.
+ *
+ * The missing-value message text is inherited verbatim from the pre-#110
+ * validator at migration time so the strangler swap was bit-for-bit invisible
+ * to callers; the wording is now canonical. Membership validation against
+ * SUPPORTED_SCHEMA_VERSIONS is the strict layer added on top: an unsupported
+ * lineage errors here at authoring/export time instead of surfacing as
+ * downstream shape drift.
+ *
+ * SUPPORTED_SCHEMA_VERSIONS must stay identical to the schema_version enum in
+ * schemas/campaign-spec.v4.schema.json (and compatibility.json's campaign_spec
+ * range). The rule stays pure (no filesystem), so the constant duplicates the
+ * schema enum — the sync test in ../test/rules/schema-version.test.ts is the
+ * drift gate, following the UnknownTopLevelFields pattern.
+ */
+import type { Rule } from '../types.ts';
+/** Supported CampaignSpec lineage versions — keep in sync with the v4 JSON Schema enum. */
+export declare const SUPPORTED_SCHEMA_VERSIONS: readonly string[];
+export declare const SchemaVersion: Rule;

package/campaign-spec/dist/rules/schema-version.js

@@ -0,0 +1,53 @@
+/**
+ * SchemaVersion — requires spec.schema_version and validates it against the
+ * supported lineage matrix.
+ *
+ * The missing-value message text is inherited verbatim from the pre-#110
+ * validator at migration time so the strangler swap was bit-for-bit invisible
+ * to callers; the wording is now canonical. Membership validation against
+ * SUPPORTED_SCHEMA_VERSIONS is the strict layer added on top: an unsupported
+ * lineage errors here at authoring/export time instead of surfacing as
+ * downstream shape drift.
+ *
+ * SUPPORTED_SCHEMA_VERSIONS must stay identical to the schema_version enum in
+ * schemas/campaign-spec.v4.schema.json (and compatibility.json's campaign_spec
+ * range). The rule stays pure (no filesystem), so the constant duplicates the
+ * schema enum — the sync test in ../test/rules/schema-version.test.ts is the
+ * drift gate, following the UnknownTopLevelFields pattern.
+ */
+/** Supported CampaignSpec lineage versions — keep in sync with the v4 JSON Schema enum. */
+export const SUPPORTED_SCHEMA_VERSIONS = Object.freeze(['4.2', '4.3']);
+export const SchemaVersion = {
+    id: 'SchemaVersion',
+    severity: 'error',
+    tags: ['fast', 'spec-only'],
+    check(spec) {
+        if (!spec.schema_version) {
+            return [
+                {
+                    ruleId: 'SchemaVersion',
+                    severity: 'error',
+                    message: 'Missing schema_version',
+                    path: '/schema_version',
+                },
+            ];
+        }
+        if (!SUPPORTED_SCHEMA_VERSIONS.includes(spec.schema_version)) {
+            return [
+                {
+                    ruleId: 'SchemaVersion',
+                    severity: 'error',
+                    message: `Unsupported schema_version ${JSON.stringify(spec.schema_version)}. ` +
+                        `Supported versions: ${SUPPORTED_SCHEMA_VERSIONS.join(', ')}.`,
+                    path: '/schema_version',
+                    data: {
+                        value: spec.schema_version,
+                        supported: [...SUPPORTED_SCHEMA_VERSIONS],
+                        check: 'schema-version-supported',
+                    },
+                },
+            ];
+        }
+        return [];
+    },
+};

package/campaign-spec/dist/rules/sdk-version.d.ts

@@ -0,0 +1,26 @@
+/**
+ * SdkVersion — requires a strict released SDK version on the spec for export.
+ *
+ * Two acceptable locations: spec.global_config.sdk_version (CANONICAL —
+ * 33/33 real Map Builder exports declare it there) or
+ * spec.runtime.sdk_version (accepted alias, seen only in local drafts and
+ * always redundant there). Either being present satisfies the presence
+ * requirement; the missing-everywhere violation path points at the canonical
+ * home.
+ *
+ * Strictness mirrors the downstream Page Kit SDK-version checkpoint
+ * (src/page-kit-sdk-version.mjs) via the shared parser in
+ * ../sdk-version-parse.ts, so external authors get the same rejection at
+ * authoring/export time that the checkpoint would deliver after Build Packet
+ * preparation:
+ *   - missing everywhere            → error (message unchanged — the "SDK
+ *     version is required" substring is matched by caller tests)
+ *   - non-string / empty / padded / prerelease / non-canonical → error at the
+ *     location carrying the bad value (one violation per bad location)
+ *   - conflicting dual declarations → error (escalated from the former
+ *     warning; the checkpoint already treats conflicts as non-waivable, and
+ *     every real dual-declaration spec in the corpus agrees)
+ *   - both present and equal        → passes (real drafts do this)
+ */
+import type { Rule } from '../types.ts';
+export declare const SdkVersion: Rule;

package/campaign-spec/dist/rules/sdk-version.js

@@ -0,0 +1,96 @@
+/**
+ * SdkVersion — requires a strict released SDK version on the spec for export.
+ *
+ * Two acceptable locations: spec.global_config.sdk_version (CANONICAL —
+ * 33/33 real Map Builder exports declare it there) or
+ * spec.runtime.sdk_version (accepted alias, seen only in local drafts and
+ * always redundant there). Either being present satisfies the presence
+ * requirement; the missing-everywhere violation path points at the canonical
+ * home.
+ *
+ * Strictness mirrors the downstream Page Kit SDK-version checkpoint
+ * (src/page-kit-sdk-version.mjs) via the shared parser in
+ * ../sdk-version-parse.ts, so external authors get the same rejection at
+ * authoring/export time that the checkpoint would deliver after Build Packet
+ * preparation:
+ *   - missing everywhere            → error (message unchanged — the "SDK
+ *     version is required" substring is matched by caller tests)
+ *   - non-string / empty / padded / prerelease / non-canonical → error at the
+ *     location carrying the bad value (one violation per bad location)
+ *   - conflicting dual declarations → error (escalated from the former
+ *     warning; the checkpoint already treats conflicts as non-waivable, and
+ *     every real dual-declaration spec in the corpus agrees)
+ *   - both present and equal        → passes (real drafts do this)
+ */
+import { describeSdkVersionRejection, parseSdkVersion } from "../sdk-version-parse.js";
+function displayValue(value) {
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    try {
+        return String(JSON.stringify(value));
+    }
+    catch {
+        return String(value);
+    }
+}
+export const SdkVersion = {
+    id: 'SdkVersion',
+    severity: 'error',
+    tags: ['fast', 'spec-only'],
+    check(spec) {
+        const globalConfig = spec.global_config;
+        const runtime = spec.runtime;
+        const hasCanonical = globalConfig != null && Object.hasOwn(globalConfig, 'sdk_version');
+        const hasAlias = runtime != null && Object.hasOwn(runtime, 'sdk_version');
+        if (!hasCanonical && !hasAlias) {
+            return [
+                {
+                    ruleId: 'SdkVersion',
+                    severity: 'error',
+                    message: 'SDK version is required for spec export.',
+                    path: '/global_config/sdk_version',
+                },
+            ];
+        }
+        const violations = [];
+        const declarations = [
+            ...(hasCanonical
+                ? [{ location: 'global_config.sdk_version', path: '/global_config/sdk_version', value: globalConfig.sdk_version }]
+                : []),
+            ...(hasAlias
+                ? [{ location: 'runtime.sdk_version', path: '/runtime/sdk_version', value: runtime.sdk_version }]
+                : []),
+        ];
+        for (const declaration of declarations) {
+            const parsed = parseSdkVersion(declaration.value);
+            if (parsed.ok)
+                continue;
+            violations.push({
+                ruleId: 'SdkVersion',
+                severity: 'error',
+                message: `${declaration.location} must be a released semantic version in canonical ` +
+                    `MAJOR.MINOR.PATCH form; got ${displayValue(declaration.value)} ` +
+                    `(${describeSdkVersionRejection(parsed.reason)}).`,
+                path: declaration.path,
+                data: { value: declaration.value, reason: parsed.reason, check: 'sdk-version-strict' },
+            });
+        }
+        if (violations.length > 0)
+            return violations;
+        const canonical = globalConfig?.sdk_version;
+        const alias = runtime?.sdk_version;
+        if (hasCanonical && hasAlias && canonical !== alias) {
+            return [
+                {
+                    ruleId: 'SdkVersion',
+                    severity: 'error',
+                    message: `Conflicting SDK version declarations: global_config.sdk_version=${canonical} vs ` +
+                        `runtime.sdk_version=${alias}. global_config is canonical — align or remove the runtime alias.`,
+                    path: '/runtime/sdk_version',
+                    data: { global_config: canonical, runtime: alias, check: 'sdk-version-conflict' },
+                },
+            ];
+        }
+        return [];
+    },
+};

package/campaign-spec/dist/rules/shipping-countries-shape.d.ts

@@ -0,0 +1,10 @@
+/**
+ * ShippingCountriesShape — campaign.available_shipping_countries must be
+ * either the literal string "all", an array of country codes, or absent.
+ * Anything else (a single string, an object, a number) is malformed.
+ *
+ * Warning severity. Message text inherited verbatim from the pre-#110
+ * validator at migration time.
+ */
+import type { Rule } from '../types.ts';
+export declare const ShippingCountriesShape: Rule;

package/campaign-spec/dist/rules/shipping-countries-shape.js

@@ -0,0 +1,30 @@
+/**
+ * ShippingCountriesShape — campaign.available_shipping_countries must be
+ * either the literal string "all", an array of country codes, or absent.
+ * Anything else (a single string, an object, a number) is malformed.
+ *
+ * Warning severity. Message text inherited verbatim from the pre-#110
+ * validator at migration time.
+ */
+function isValidShape(countries) {
+    return countries == null || countries === 'all' || Array.isArray(countries);
+}
+export const ShippingCountriesShape = {
+    id: 'ShippingCountriesShape',
+    severity: 'warning',
+    tags: ['fast', 'spec-only'],
+    check(spec) {
+        const countries = spec.campaign?.available_shipping_countries;
+        if (isValidShape(countries))
+            return [];
+        return [
+            {
+                ruleId: 'ShippingCountriesShape',
+                severity: 'warning',
+                message: 'Shipping countries must be "all" or an array of country codes.',
+                path: '/campaign/available_shipping_countries',
+                data: { received: countries },
+            },
+        ];
+    },
+};

package/campaign-spec/dist/rules/shipping-methods-present.d.ts

@@ -0,0 +1,10 @@
+/**
+ * ShippingMethodsPresent — warn when the spec declares no shipping methods.
+ * Missing/undefined or empty array both fire; matches legacy behaviour.
+ *
+ * Warning severity (not error) — the campaign can still ship technically,
+ * the warning surfaces that the operator hasn't chosen methods yet.
+ * Message text inherited verbatim from the pre-#110 validator at migration time.
+ */
+import type { Rule } from '../types.ts';
+export declare const ShippingMethodsPresent: Rule;

package/campaign-spec/dist/rules/shipping-methods-present.js

@@ -0,0 +1,26 @@
+/**
+ * ShippingMethodsPresent — warn when the spec declares no shipping methods.
+ * Missing/undefined or empty array both fire; matches legacy behaviour.
+ *
+ * Warning severity (not error) — the campaign can still ship technically,
+ * the warning surfaces that the operator hasn't chosen methods yet.
+ * Message text inherited verbatim from the pre-#110 validator at migration time.
+ */
+export const ShippingMethodsPresent = {
+    id: 'ShippingMethodsPresent',
+    severity: 'warning',
+    tags: ['fast', 'spec-only'],
+    check(spec) {
+        const methods = spec.shipping_methods ?? [];
+        if (methods.length > 0)
+            return [];
+        return [
+            {
+                ruleId: 'ShippingMethodsPresent',
+                severity: 'warning',
+                message: 'No shipping methods selected.',
+                path: '/shipping_methods',
+            },
+        ];
+    },
+};

package/campaign-spec/dist/rules/store-profile-shape.d.ts

@@ -0,0 +1,30 @@
+/**
+ * StoreProfileShape — light validation for two campaign-level store
+ * profile fields introduced in Slice 4f.
+ *
+ * 1. campaign.store_phone_tel must be a `tel:`-prefixed URI containing
+ *    a digit-shaped number when present. The build wires this value
+ *    into `<a href="tel:...">` attributes; a value without the scheme
+ *    renders a broken link, and a value containing HTML metacharacters
+ *    or alternative schemes (javascript:, data:) is rejected as a
+ *    defense-in-depth measure for downstream templates that may skip
+ *    href escaping. Accepted shape: `tel:` then optional `+`, then a
+ *    sequence of at least 4 chars drawn from digits, spaces, dashes,
+ *    parens, and dots.
+ *
+ * 2. campaign.allowed_domains shape check: when present, must be a
+ *    non-empty array of hostname strings. The Campaigns API treats
+ *    domain allowlisting as the access boundary for public-by-design
+ *    keys; the spec carries the allowlist so the build packet can bind
+ *    config.js to the right surface.
+ *
+ *    Scope note: this rule fires only when allowed_domains is
+ *    explicitly set. Absence is silent — a missing allowlist is
+ *    common in pre-launch / draft specs and belongs to a separate
+ *    launch-readiness check, not a shape rule. The launch gate
+ *    can be added later without changing this rule's contract.
+ *
+ * Both checks are warning severity. Never blocks a build.
+ */
+import type { Rule } from '../types.ts';
+export declare const StoreProfileShape: Rule;

package/campaign-spec/dist/rules/store-profile-shape.js

@@ -0,0 +1,127 @@
+/**
+ * StoreProfileShape — light validation for two campaign-level store
+ * profile fields introduced in Slice 4f.
+ *
+ * 1. campaign.store_phone_tel must be a `tel:`-prefixed URI containing
+ *    a digit-shaped number when present. The build wires this value
+ *    into `<a href="tel:...">` attributes; a value without the scheme
+ *    renders a broken link, and a value containing HTML metacharacters
+ *    or alternative schemes (javascript:, data:) is rejected as a
+ *    defense-in-depth measure for downstream templates that may skip
+ *    href escaping. Accepted shape: `tel:` then optional `+`, then a
+ *    sequence of at least 4 chars drawn from digits, spaces, dashes,
+ *    parens, and dots.
+ *
+ * 2. campaign.allowed_domains shape check: when present, must be a
+ *    non-empty array of hostname strings. The Campaigns API treats
+ *    domain allowlisting as the access boundary for public-by-design
+ *    keys; the spec carries the allowlist so the build packet can bind
+ *    config.js to the right surface.
+ *
+ *    Scope note: this rule fires only when allowed_domains is
+ *    explicitly set. Absence is silent — a missing allowlist is
+ *    common in pre-launch / draft specs and belongs to a separate
+ *    launch-readiness check, not a shape rule. The launch gate
+ *    can be added later without changing this rule's contract.
+ *
+ * Both checks are warning severity. Never blocks a build.
+ */
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+// `tel:` followed by optional `+`, then 4+ chars of digits / space / dash /
+// parens / dot. Rejects HTML metachars, javascript:/data: schemes, control
+// chars, and obvious garbage. Liberal enough for international formats
+// (e.g. "tel:+44 (0)20 7946 0958"); strict enough to keep a downstream
+// `<a href>` safe even if a template skips escaping.
+const TEL_URI_REGEX = /^tel:\+?[0-9 .()\-]{4,}$/i;
+export const StoreProfileShape = {
+    id: 'StoreProfileShape',
+    severity: 'warning',
+    tags: ['fast', 'spec-only'],
+    check(spec) {
+        const violations = [];
+        const campaign = spec.campaign;
+        // 1. tel: prefix on store_phone_tel.
+        if (campaign?.store_phone_tel !== undefined) {
+            const value = campaign.store_phone_tel;
+            if (typeof value !== 'string') {
+                violations.push({
+                    ruleId: 'StoreProfileShape',
+                    severity: 'warning',
+                    message: `campaign.store_phone_tel must be a string (got ${value === null ? 'null' : typeof value}).`,
+                    path: '/campaign/store_phone_tel',
+                    data: { check: 'store-phone-tel-bad-type' },
+                });
+            }
+            else if (!isNonEmptyString(value)) {
+                violations.push({
+                    ruleId: 'StoreProfileShape',
+                    severity: 'warning',
+                    message: 'campaign.store_phone_tel is set but empty; remove the field or set a tel:-prefixed value (e.g. "tel:+18005551234").',
+                    path: '/campaign/store_phone_tel',
+                    data: { check: 'store-phone-tel-empty' },
+                });
+            }
+            else {
+                const trimmed = value.trim();
+                if (!trimmed.toLowerCase().startsWith('tel:')) {
+                    violations.push({
+                        ruleId: 'StoreProfileShape',
+                        severity: 'warning',
+                        message: `campaign.store_phone_tel "${value}" must be a tel: URI (e.g. "tel:+18005551234"); without the scheme it renders a broken link in <a href> attributes.`,
+                        path: '/campaign/store_phone_tel',
+                        data: { check: 'store-phone-tel-missing-scheme', value },
+                    });
+                }
+                else if (!TEL_URI_REGEX.test(trimmed)) {
+                    violations.push({
+                        ruleId: 'StoreProfileShape',
+                        severity: 'warning',
+                        message: `campaign.store_phone_tel "${value}" is not a recognized tel: number. Use digits, spaces, dashes, parens, and dots only (e.g. "tel:+18005551234" or "tel:+44 (0)20 7946 0958"); HTML metacharacters and alternative schemes (javascript:, data:) are rejected as a defense-in-depth measure.`,
+                        path: '/campaign/store_phone_tel',
+                        data: { check: 'store-phone-tel-bad-content', value },
+                    });
+                }
+            }
+        }
+        // 2. allowed_domains shape (when present — absence is silent; see header
+        //    note about scope).
+        const domains = campaign?.allowed_domains;
+        if (domains === undefined || domains === null) {
+            // Intentionally silent — launch-readiness check lives elsewhere.
+        }
+        else if (!Array.isArray(domains)) {
+            violations.push({
+                ruleId: 'StoreProfileShape',
+                severity: 'warning',
+                message: `campaign.allowed_domains must be an array of hostnames; got ${typeof domains}.`,
+                path: '/campaign/allowed_domains',
+                data: { check: 'allowed-domains-bad-shape', value: domains },
+            });
+        }
+        else if (domains.length === 0) {
+            violations.push({
+                ruleId: 'StoreProfileShape',
+                severity: 'warning',
+                message: 'campaign.allowed_domains is empty. Add at least one production hostname (e.g. "store.example.com") before launch so the SDK key has a valid origin.',
+                path: '/campaign/allowed_domains',
+                data: { check: 'allowed-domains-empty' },
+            });
+        }
+        else {
+            domains.forEach((domain, idx) => {
+                if (!isNonEmptyString(domain)) {
+                    violations.push({
+                        ruleId: 'StoreProfileShape',
+                        severity: 'warning',
+                        message: `campaign.allowed_domains[${idx}] must be a non-empty hostname string; got ${JSON.stringify(domain)}.`,
+                        path: `/campaign/allowed_domains/${idx}`,
+                        data: { check: 'allowed-domain-bad-entry', index: idx, value: domain },
+                    });
+                }
+            });
+        }
+        return violations;
+    },
+};

package/campaign-spec/dist/rules/thank-you-requirement.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ThankYouRequirement — every spec must include at least one thank-you page
+ * (terminal node of the funnel topology). Downgrades to a warning when the
+ * spec is a partial build (build_scope.mode === 'partial'), because partial
+ * builds may legitimately end on a non-terminal page that routes into an
+ * existing downstream campaign.
+ *
+ * Only fires when the spec has at least one page — if there are zero pages
+ * altogether, PageCount handles that signal and this rule stays silent to
+ * avoid double-reporting.
+ *
+ * Message text and the partial-scope severity downgrade are inherited
+ * verbatim from the pre-#110 validator at migration time.
+ */
+import type { Rule } from '../types.ts';
+export declare const ThankYouRequirement: Rule;

package/campaign-spec/dist/rules/thank-you-requirement.js

@@ -0,0 +1,50 @@
+/**
+ * ThankYouRequirement — every spec must include at least one thank-you page
+ * (terminal node of the funnel topology). Downgrades to a warning when the
+ * spec is a partial build (build_scope.mode === 'partial'), because partial
+ * builds may legitimately end on a non-terminal page that routes into an
+ * existing downstream campaign.
+ *
+ * Only fires when the spec has at least one page — if there are zero pages
+ * altogether, PageCount handles that signal and this rule stays silent to
+ * avoid double-reporting.
+ *
+ * Message text and the partial-scope severity downgrade are inherited
+ * verbatim from the pre-#110 validator at migration time.
+ */
+export const ThankYouRequirement = {
+    id: 'ThankYouRequirement',
+    severity: 'error',
+    tags: ['fast', 'structure', 'spec-only'],
+    check(spec) {
+        let hasThankYou = false;
+        let totalPages = 0;
+        for (const funnel of spec.funnels) {
+            const pages = funnel.pages ?? [];
+            totalPages += pages.length;
+            for (const page of pages) {
+                if (page.type === 'thankyou') {
+                    hasThankYou = true;
+                    break;
+                }
+            }
+            if (hasThankYou)
+                break;
+        }
+        // Silent when zero pages — PageCount already speaks to that.
+        if (hasThankYou || totalPages === 0)
+            return [];
+        const isPartialScope = spec.build_scope?.mode === 'partial';
+        return [
+            {
+                ruleId: 'ThankYouRequirement',
+                severity: isPartialScope ? 'warning' : 'error',
+                message: isPartialScope
+                    ? 'Spec has no Thank You page. Valid for partial builds when traffic continues to an existing downstream route.'
+                    : 'Funnel must end with a Thank You page.',
+                path: '/funnels',
+                data: { isPartialScope },
+            },
+        ];
+    },
+};

package/campaign-spec/dist/rules/unknown-top-level-fields.d.ts

@@ -0,0 +1,28 @@
+/**
+ * UnknownTopLevelFields — reports top-level spec keys and campaign.* keys
+ * that are not part of the known CampaignSpec v4 surface.
+ *
+ * Warning severity: unknown fields are legal (the schema is deliberately
+ * permissive — schemas/campaign-spec.v4.schema.json keeps
+ * additionalProperties open), but naming them surfaces dialect drift early
+ * instead of letting a misspelled or legacy key ride along silently.
+ * Rejection-at-export belongs to validation profiles in a later change.
+ *
+ * Skipped on purpose:
+ *   - keys starting with "_" (builder/ops annotations: _provenance,
+ *     _accept_label, ...);
+ *   - keys ending with "_note" (real exports use *_note keys as inline
+ *     annotations);
+ *   - sdk_hints interiors (template-handoff vocabulary lives there; this
+ *     rule only reads the top level and campaign.*).
+ *
+ * The known sets below MIRROR schemas/campaign-spec.v4.schema.json
+ * (top-level `properties` and `$defs.campaign.properties`). Rules stay pure
+ * and filesystem-free, so the sets are duplicated here; the sync test
+ * (test/rules/unknown-top-level-fields.test.ts) asserts they match the
+ * schema exactly — update both together.
+ */
+import type { Rule } from '../types.ts';
+export declare const KNOWN_TOP_LEVEL_FIELDS: readonly string[];
+export declare const KNOWN_CAMPAIGN_FIELDS: readonly string[];
+export declare const UnknownTopLevelFields: Rule;

package/campaign-spec/dist/rules/unknown-top-level-fields.js

@@ -0,0 +1,114 @@
+/**
+ * UnknownTopLevelFields — reports top-level spec keys and campaign.* keys
+ * that are not part of the known CampaignSpec v4 surface.
+ *
+ * Warning severity: unknown fields are legal (the schema is deliberately
+ * permissive — schemas/campaign-spec.v4.schema.json keeps
+ * additionalProperties open), but naming them surfaces dialect drift early
+ * instead of letting a misspelled or legacy key ride along silently.
+ * Rejection-at-export belongs to validation profiles in a later change.
+ *
+ * Skipped on purpose:
+ *   - keys starting with "_" (builder/ops annotations: _provenance,
+ *     _accept_label, ...);
+ *   - keys ending with "_note" (real exports use *_note keys as inline
+ *     annotations);
+ *   - sdk_hints interiors (template-handoff vocabulary lives there; this
+ *     rule only reads the top level and campaign.*).
+ *
+ * The known sets below MIRROR schemas/campaign-spec.v4.schema.json
+ * (top-level `properties` and `$defs.campaign.properties`). Rules stay pure
+ * and filesystem-free, so the sets are duplicated here; the sync test
+ * (test/rules/unknown-top-level-fields.test.ts) asserts they match the
+ * schema exactly — update both together.
+ */
+export const KNOWN_TOP_LEVEL_FIELDS = [
+    'schema_version',
+    'builder_version',
+    'generated_at',
+    'campaign',
+    'global_config',
+    'runtime',
+    'funnels',
+    'funnel_pages',
+    'shipping_methods',
+    'offers',
+    'spec_identity',
+    'build_scope',
+    'analytics',
+    'slug',
+    'map_id',
+    'saved_at',
+    'deployment',
+    'draft',
+    'draft_notes',
+    'figma_url',
+];
+export const KNOWN_CAMPAIGN_FIELDS = [
+    'ref_id',
+    'id',
+    'name',
+    'slug',
+    'currency',
+    'language',
+    'payment_env_key',
+    'campaigns_api_key',
+    'available_payment_methods',
+    'available_express_payment_methods',
+    'available_currencies',
+    'available_shipping_countries',
+    'tracking',
+    'preferred_template_family',
+    'allowed_domains',
+    'route_root',
+    'store_url',
+    'store_name',
+    'store_contact',
+    'store_terms',
+    'store_shipping',
+    'store_privacy',
+    'store_returns',
+    'store_phone',
+    'store_phone_tel',
+    'footer_links',
+    'seo',
+];
+function skipKey(key) {
+    return key.startsWith('_') || key.endsWith('_note');
+}
+export const UnknownTopLevelFields = {
+    id: 'UnknownTopLevelFields',
+    severity: 'warning',
+    tags: ['fast', 'spec-only'],
+    check(spec) {
+        const violations = [];
+        const knownTop = new Set(KNOWN_TOP_LEVEL_FIELDS);
+        const knownCampaign = new Set(KNOWN_CAMPAIGN_FIELDS);
+        for (const key of Object.keys(spec)) {
+            if (skipKey(key) || knownTop.has(key))
+                continue;
+            violations.push({
+                ruleId: 'UnknownTopLevelFields',
+                severity: 'warning',
+                message: `Unknown top-level field "${key}" — not part of the CampaignSpec v4 surface. Check for a typo or a legacy key; unknown fields are carried through but never read.`,
+                path: `/${key}`,
+                data: { scope: 'top-level', key },
+            });
+        }
+        const campaign = spec.campaign;
+        if (campaign && typeof campaign === 'object' && !Array.isArray(campaign)) {
+            for (const key of Object.keys(campaign)) {
+                if (skipKey(key) || knownCampaign.has(key))
+                    continue;
+                violations.push({
+                    ruleId: 'UnknownTopLevelFields',
+                    severity: 'warning',
+                    message: `Unknown campaign field "campaign.${key}" — not part of the CampaignSpec v4 surface. Check for a typo or a legacy key; unknown fields are carried through but never read.`,
+                    path: `/campaign/${key}`,
+                    data: { scope: 'campaign', key },
+                });
+            }
+        }
+        return violations;
+    },
+};

package/campaign-spec/dist/rules/upsell-has-packages.d.ts

@@ -0,0 +1,9 @@
+/**
+ * UpsellHasPackages — upsell and downsell pages must declare at least one
+ * package, since the runtime renders a bundle/offer selector for these page
+ * types and an empty packages array has nothing to show.
+ *
+ * Message text inherited verbatim from the pre-#110 validator at migration time.
+ */
+import type { Rule } from '../types.ts';
+export declare const UpsellHasPackages: Rule;