@nextcommerce/campaigns-os 1.33.0

package/campaign-spec/dist/rules/analytics-contract-shape.js

@@ -0,0 +1,303 @@
+/**
+ * AnalyticsContractShape — validates the optional top-level `analytics` block
+ * when present. The block declares a campaign's analytics/attribution/param
+ * contract so doctor + QA can validate against intent (cf. the Chamelo Shield
+ * `?reviews=n`-has-no-handler QA finding and the Walla Sound Redtrack param
+ * conflict — both are gaps that had no declared contract to check against).
+ *
+ * The block is fully OPTIONAL — a spec without `analytics` is silent (SDK
+ * defaults apply, exactly as today). When `analytics` IS set, this rule catches
+ * authoring drift before doctor/QA see it. Every check is `warning` severity:
+ * authoring guidance, not a build blocker (matches DesignSourceShape).
+ *
+ * Checks:
+ *   0. If `analytics` is present but not a plain object (a non-plain-object
+ *      value: string, array, number, boolean, boxed primitive, class instance,
+ *      etc.), warn once and stop — there is no contract shape to inspect.
+ *      Genuinely-absent `analytics` stays silent (optional, non-gating).
+ *   1. `mode`, if present, is one of auto | manual | disabled.
+ *   2. Each provider: `blockedEvents` (when present) is a string[], and each
+ *      entry is a known SDK `dl_*` event (a misspelled/legacy name like
+ *      "purchase" blocks nothing — the original drift bug this keystone closes);
+ *      an enabled gtm provider should declare `containerId`, facebook `pixelId`,
+ *      custom `endpoint` (warning — the id is what doctor/QA bind to).
+ *   3. Each `out_of_band_pixels[]` entry has a non-empty `vendor`.
+ *   4. Each `manual_events[]` entry has a non-empty `event`; if it names a
+ *      `page`, that page id must exist; a purchase manual event SHOULD name a
+ *      page (the first-upsell placement footgun — beacons lost in the
+ *      checkout→upsell redirect when placed on checkout).
+ *   5. Each `params.content[]` entry has a non-empty `name`; referenced `pages`
+ *      must exist (a content param pointing at a missing page is the
+ *      `?reviews=n`-with-no-handler gap, inverted).
+ *   6. `params.tracking.click_id`, when present, declares both `inbound` and
+ *      `maps_to` (half a mapping silently drops the affiliate click id).
+ *   7. `params.tracking.preserve` / `utmTransfer.paramsToCopy`, when present,
+ *      are string[].
+ *   8. If analytics is active (the block is present and mode is not
+ *      "disabled"; missing mode means SDK defaults apply), runtime/global_config
+ *      sdk_version should be an exact released semver >= the SDK identity
+ *      baseline so events carry campaign/session ids.
+ */
+import { CAMPAIGN_CART_ANALYTICS_IDENTITY_MIN_SDK_VERSION, isKnownDlEvent, } from "../analytics-vocabulary.js";
+const VALID_MODES = new Set(['auto', 'manual', 'disabled']);
+const PURCHASE_EVENT = /^(?:dl_)?purchase$/i;
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((v) => typeof v === 'string');
+}
+function isPlainAnalyticsObject(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function parseReleasedVersion(version) {
+    const match = version.trim().match(/^v?(\d+)\.(\d+)\.(\d+)$/);
+    if (!match)
+        return null;
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+function compareVersions(a, b) {
+    const left = parseReleasedVersion(a);
+    const right = parseReleasedVersion(b);
+    if (!left || !right)
+        return null;
+    for (let i = 0; i < 3; i += 1) {
+        if (left[i] > right[i])
+            return 1;
+        if (left[i] < right[i])
+            return -1;
+    }
+    return 0;
+}
+function sdkVersionRef(spec) {
+    const runtimeVersion = spec.runtime?.sdk_version;
+    if (isNonEmptyString(runtimeVersion))
+        return { version: runtimeVersion, path: '/runtime/sdk_version' };
+    const globalVersion = spec.global_config?.sdk_version;
+    if (isNonEmptyString(globalVersion))
+        return { version: globalVersion, path: '/global_config/sdk_version' };
+    return null;
+}
+function analyticsContractIsActive(analytics) {
+    // A present analytics block with no mode still means "SDK defaults apply";
+    // either supported explicit disable mechanism opts out of the SDK identity
+    // baseline check.
+    return analytics.enabled !== false && analytics.mode !== 'disabled';
+}
+function collectPageIds(spec) {
+    const pageIds = new Set();
+    const checkoutPageIds = new Set();
+    for (const funnel of spec.funnels ?? []) {
+        for (const page of funnel.pages ?? []) {
+            if (isNonEmptyString(page.id)) {
+                pageIds.add(page.id);
+                if (page.type === 'checkout')
+                    checkoutPageIds.add(page.id);
+            }
+        }
+    }
+    return { pageIds, checkoutPageIds };
+}
+export const AnalyticsContractShape = {
+    id: 'AnalyticsContractShape',
+    severity: 'warning',
+    // Dual tag is intentional and matches every sibling pure-spec rule
+    // (StoreProfileShape, DesignSourceShape, AssemblyHintsShape, …): the rule is
+    // cheap enough for per-keystroke Map Builder (`fast`) AND needs no live
+    // deployment (`spec-only`). `fastRules`/`specOnlyRules` are mutually-exclusive
+    // FILTERED VIEWS of `allRules` (see rules/index.ts) — a validation pass runs
+    // exactly one RuleSet, and `allRules` lists each rule once, so a dual-tagged
+    // rule never double-runs. (Surfaced in a downstream consumer-PR review.)
+    tags: ['fast', 'spec-only'],
+    check(spec) {
+        const violations = [];
+        const analytics = spec.analytics;
+        // Genuinely-absent analytics stays silent: the block is OPTIONAL and
+        // non-gating (SDK defaults apply). But a PRESENT-but-non-object value
+        // (`analytics: "auto"`, an array, a primitive) is authoring drift the
+        // author wants to hear about — warn, then stop (no shape to inspect).
+        if (analytics === undefined || analytics === null)
+            return violations;
+        // Reject any non-plain-object value: primitives, arrays, and boxed
+        // primitives (new String("auto") passes `typeof === 'object'` but is not a
+        // plain contract block). Only Object.prototype and null-prototype objects
+        // are accepted as valid analytics blocks.
+        if (!isPlainAnalyticsObject(analytics)) {
+            const label = Array.isArray(analytics) ? 'an array' : typeof analytics !== 'object' ? typeof analytics : 'a non-plain object';
+            violations.push({
+                ruleId: 'AnalyticsContractShape',
+                severity: 'warning',
+                message: 'analytics must be an object (the analytics/attribution contract block); got ' + label + '.',
+                path: '/analytics',
+                data: { check: 'analytics-shape' },
+            });
+            return violations;
+        }
+        const warn = (message, path, check, data = {}) => {
+            violations.push({
+                ruleId: 'AnalyticsContractShape',
+                severity: 'warning',
+                message,
+                path,
+                data: { check, ...data },
+            });
+        };
+        // 8. SDK identity baseline
+        const versionRef = sdkVersionRef(spec);
+        if (analyticsContractIsActive(analytics) && versionRef) {
+            const comparison = compareVersions(versionRef.version, CAMPAIGN_CART_ANALYTICS_IDENTITY_MIN_SDK_VERSION);
+            if (comparison === null) {
+                warn(`analytics is declared, but Campaign Cart SDK version "${versionRef.version}" is not an exact released semver pin. Use a concrete release such as "${CAMPAIGN_CART_ANALYTICS_IDENTITY_MIN_SDK_VERSION}" so Campaigns OS can verify whether campaign_* identifiers and ncsid-backed campaign_session_id are stamped on every event.`, versionRef.path, 'sdk-version-unparseable', {
+                    sdkVersion: versionRef.version,
+                    expectedFormat: 'MAJOR.MINOR.PATCH',
+                    minimumSdkVersion: CAMPAIGN_CART_ANALYTICS_IDENTITY_MIN_SDK_VERSION,
+                });
+            }
+            else if (comparison < 0) {
+                warn(`analytics is declared, but Campaign Cart SDK ${versionRef.version} is below ${CAMPAIGN_CART_ANALYTICS_IDENTITY_MIN_SDK_VERSION}. campaign_* identifiers and ncsid-backed campaign_session_id are stamped on every event starting in ${CAMPAIGN_CART_ANALYTICS_IDENTITY_MIN_SDK_VERSION}; upgrade the SDK for analytics attribution/joinability or record the intentional pin.`, versionRef.path, 'sdk-identity-baseline', {
+                    sdkVersion: versionRef.version,
+                    minimumSdkVersion: CAMPAIGN_CART_ANALYTICS_IDENTITY_MIN_SDK_VERSION,
+                });
+            }
+        }
+        // 1. mode
+        if (analytics.mode !== undefined && !VALID_MODES.has(String(analytics.mode))) {
+            warn(`analytics.mode "${String(analytics.mode)}" is not recognized; expected auto | manual | disabled.`, '/analytics/mode', 'mode-invalid', { mode: analytics.mode });
+        }
+        // 2. providers
+        const providers = analytics.providers;
+        if (providers && typeof providers === 'object' && !Array.isArray(providers)) {
+            for (const [kind, provider] of Object.entries(providers)) {
+                if (!provider || typeof provider !== 'object')
+                    continue;
+                const base = `/analytics/providers/${kind}`;
+                // Asymmetry accepted by design (downstream consumer-PR review): a
+                // provider with `enabled:false` that still carries containerId/pixelId/
+                // endpoint gets no signal. A disabled provider keeping its id is a
+                // legitimate, common pattern (staged rollout, env-toggled, kept for
+                // reference) — flagging it would be noise, and "off accidentally" is not
+                // distinguishable from "off by design" at spec level. We only validate
+                // ENABLED providers' binding ids; disabled providers are left alone.
+                const enabled = provider.enabled !== false;
+                if (provider.blockedEvents !== undefined && !isStringArray(provider.blockedEvents)) {
+                    warn(`analytics.providers.${kind}.blockedEvents must be an array of event-name strings.`, `${base}/blockedEvents`, 'blocked-events-shape', { kind });
+                }
+                else if (isStringArray(provider.blockedEvents)) {
+                    // Each blocked event must be a known SDK dl_* event. blockedEvents
+                    // matches by EXACT event name at runtime, so a misspelled or legacy
+                    // name (e.g. "purchase" instead of "dl_purchase") silently blocks
+                    // nothing — caught here at doctor time, not in production.
+                    const blocked = provider.blockedEvents;
+                    blocked.forEach((evt, i) => {
+                        if (!isKnownDlEvent(evt)) {
+                            warn(`analytics.providers.${kind}.blockedEvents[${i}] "${evt}" is not a known SDK dl_* event. blockedEvents matches by exact event name, so a misspelled or legacy name (e.g. "purchase" instead of "dl_purchase") blocks nothing.`, `${base}/blockedEvents/${i}`, 'blocked-event-unknown', { kind, event: evt });
+                        }
+                    });
+                }
+                if (enabled && kind === 'gtm' && !isNonEmptyString(provider.containerId)) {
+                    warn(`analytics.providers.gtm is enabled but has no containerId (e.g. "GTM-…"); doctor/QA bind to it.`, `${base}/containerId`, 'gtm-container-missing', { kind });
+                }
+                if (enabled && kind === 'facebook' && !isNonEmptyString(provider.pixelId)) {
+                    warn(`analytics.providers.facebook is enabled but has no pixelId; doctor/QA bind to it.`, `${base}/pixelId`, 'facebook-pixel-missing', { kind });
+                }
+                if (enabled && kind === 'custom' && !isNonEmptyString(provider.endpoint)) {
+                    warn(`analytics.providers.custom is enabled but has no endpoint URL.`, `${base}/endpoint`, 'custom-endpoint-missing', { kind });
+                }
+            }
+        }
+        const { pageIds, checkoutPageIds } = collectPageIds(spec);
+        // 3. out_of_band_pixels
+        if (analytics.out_of_band_pixels !== undefined) {
+            if (!Array.isArray(analytics.out_of_band_pixels)) {
+                warn(`analytics.out_of_band_pixels must be an array.`, '/analytics/out_of_band_pixels', 'oob-not-array');
+            }
+            else {
+                analytics.out_of_band_pixels.forEach((pixel, i) => {
+                    if (!pixel || typeof pixel !== 'object' || !isNonEmptyString(pixel.vendor)) {
+                        warn(`out_of_band_pixels[${i}] is missing a vendor (e.g. "everflow", "triplepixel").`, `/analytics/out_of_band_pixels/${i}/vendor`, 'oob-vendor-missing', { index: i });
+                    }
+                });
+            }
+        }
+        // 4. manual_events
+        if (analytics.manual_events !== undefined) {
+            if (!Array.isArray(analytics.manual_events)) {
+                warn(`analytics.manual_events must be an array.`, '/analytics/manual_events', 'manual-events-not-array');
+            }
+            else {
+                analytics.manual_events.forEach((evt, i) => {
+                    const base = `/analytics/manual_events/${i}`;
+                    if (!evt || typeof evt !== 'object' || !isNonEmptyString(evt.event)) {
+                        warn(`manual_events[${i}] is missing an event name.`, `${base}/event`, 'manual-event-name-missing', { index: i });
+                        return;
+                    }
+                    if (isNonEmptyString(evt.page) && !pageIds.has(evt.page)) {
+                        warn(`manual_events[${i}] (${evt.event}) names page "${evt.page}", which is not a page id in this spec.`, `${base}/page`, 'manual-event-page-unknown', { index: i, page: evt.page });
+                    }
+                    if (PURCHASE_EVENT.test(evt.event) && !isNonEmptyString(evt.page)) {
+                        warn(`manual_events[${i}] is a purchase fire but declares no page. Purchase beacons placed on checkout are lost in the checkout→upsell redirect — declare the page they live on (typically the first upsell).`, `${base}/page`, 'manual-purchase-page-missing', { index: i });
+                    }
+                    if (PURCHASE_EVENT.test(evt.event) && isNonEmptyString(evt.page) && checkoutPageIds.has(evt.page)) {
+                        warn(`manual_events[${i}] is a purchase fire on checkout page "${evt.page}". Purchase beacons on checkout are lost in the checkout→upsell redirect — move the fire to the first upsell page.`, `${base}/page`, 'manual-purchase-on-checkout', { index: i, page: evt.page });
+                    }
+                });
+            }
+        }
+        // 5 + 6. params
+        const params = analytics.params;
+        if (params && typeof params === 'object') {
+            const content = params.content;
+            if (content !== undefined) {
+                if (!Array.isArray(content)) {
+                    warn(`analytics.params.content must be an array.`, '/analytics/params/content', 'content-not-array');
+                }
+                else {
+                    content.forEach((cp, i) => {
+                        const base = `/analytics/params/content/${i}`;
+                        if (!cp || typeof cp !== 'object' || !isNonEmptyString(cp.name)) {
+                            warn(`params.content[${i}] is missing a param name.`, `${base}/name`, 'content-name-missing', { index: i });
+                            return;
+                        }
+                        if (cp.pages !== undefined && !Array.isArray(cp.pages)) {
+                            warn(`params.content[${i}] (?${cp.name}) pages must be an array of page-id strings.`, `${base}/pages`, 'content-pages-shape', { index: i, name: cp.name });
+                        }
+                        else if (Array.isArray(cp.pages) && cp.pages.length === 0) {
+                            // Explicit empty array applies to no page — a silent no-op the
+                            // author almost certainly didn't intend. Omit `pages` to apply to
+                            // all pages, or list the ids to scope to.
+                            warn(`params.content[${i}] (?${cp.name}) has an empty pages array, so it applies to no page. Omit pages to apply to all pages, or list the page ids it should scope to.`, `${base}/pages`, 'content-pages-empty', { index: i, name: cp.name });
+                        }
+                        else {
+                            for (const pageRef of cp.pages ?? []) {
+                                if (!pageIds.has(pageRef)) {
+                                    warn(`params.content[${i}] (?${cp.name}) references page "${pageRef}", which is not a page id in this spec.`, `${base}/pages`, 'content-page-unknown', { index: i, name: cp.name, page: pageRef });
+                                }
+                            }
+                        }
+                    });
+                }
+            }
+            const tracking = params.tracking;
+            if (tracking && typeof tracking === 'object') {
+                if (tracking.preserve !== undefined && !isStringArray(tracking.preserve)) {
+                    warn(`analytics.params.tracking.preserve must be an array of param-name strings.`, '/analytics/params/tracking/preserve', 'preserve-shape');
+                }
+                const clickId = tracking.click_id;
+                if (clickId && typeof clickId === 'object') {
+                    if (!isNonEmptyString(clickId.inbound) || !isNonEmptyString(clickId.maps_to)) {
+                        warn(`analytics.params.tracking.click_id needs both "inbound" (the querystring param) and "maps_to" (the SDK attribution field); half a mapping silently drops the affiliate click id.`, '/analytics/params/tracking/click_id', 'click-id-incomplete');
+                    }
+                }
+            }
+        }
+        // 7. utmTransfer.paramsToCopy
+        const utm = analytics.utmTransfer;
+        if (utm && typeof utm === 'object' && utm.paramsToCopy !== undefined && !isStringArray(utm.paramsToCopy)) {
+            warn(`analytics.utmTransfer.paramsToCopy must be an array of param-name strings.`, '/analytics/utmTransfer/paramsToCopy', 'utm-params-shape');
+        }
+        return violations;
+    },
+};

package/campaign-spec/dist/rules/assembly-hints-shape.d.ts

@@ -0,0 +1,42 @@
+/**
+ * AssemblyHintsShape — validates the optional authoring-time build hints
+ * introduced in Slice 4a and extended in Slice 4b:
+ *
+ *   1. campaign.preferred_template_family — which starter family the
+ *      campaign was authored against. Already read by campaigns-os
+ *      preferredTemplateFamily() (three locations); this rule blesses
+ *      the convention and warns when the value isn't a recognized
+ *      family.
+ *   2. page.upsell_template_pattern — per-page UI variant hint
+ *      (mv | bundle_tier_pills | bundle_tier_cards | single). Warns
+ *      when set on a non-upsell page (meaningless) or when the value
+ *      isn't recognized.
+ *   3. page.upsell_mv_tiers — per-page MV tier range `{min, max}`
+ *      declaring the inclusive quantity-tier subset to render. Warns
+ *      when set on a non-upsell page, when shape is malformed (missing
+ *      field, non-integer, non-positive), or when min > max.
+ *
+ * All three are HINTS, not contracts. The build agent uses them as
+ * defaults; CLI/operator overrides win. Hence the warning severity
+ * across the board — these never block a build, they just nudge
+ * authoring quality.
+ *
+ * Doctrine note: template family is fundamentally a build-time
+ * decision and CLI/operator overrides always win. Authoring-time
+ * hints are allowed because designers / campaign owners often know
+ * the answer at authoring time, and re-deciding at build was
+ * repeated friction — hence warning severity, never a build blocker.
+ *
+ * Cross-field constraint enforcement (upsell_mv_tiers min <= max): the
+ * JSON Schema (schemas/campaign-runtime-build-packet.v0.schema.json)
+ * does NOT express this constraint — plain JSON Schema 2020-12 cannot
+ * say "field A must be less than or equal to field B" without
+ * $data-style extensions. Defense in depth lives at two layers
+ * instead: this rule warns the author at authoring/QA time, and the
+ * campaigns-os consumer's normalizedMvTiers() silently drops the field
+ * when min > max so a half-state spec never reaches the build agent
+ * through the packet. Both layers must stay aligned; loosening either
+ * one is a contract change worth a coordinated PR.
+ */
+import type { Rule } from '../types.ts';
+export declare const AssemblyHintsShape: Rule;

package/campaign-spec/dist/rules/assembly-hints-shape.js

@@ -0,0 +1,191 @@
+/**
+ * AssemblyHintsShape — validates the optional authoring-time build hints
+ * introduced in Slice 4a and extended in Slice 4b:
+ *
+ *   1. campaign.preferred_template_family — which starter family the
+ *      campaign was authored against. Already read by campaigns-os
+ *      preferredTemplateFamily() (three locations); this rule blesses
+ *      the convention and warns when the value isn't a recognized
+ *      family.
+ *   2. page.upsell_template_pattern — per-page UI variant hint
+ *      (mv | bundle_tier_pills | bundle_tier_cards | single). Warns
+ *      when set on a non-upsell page (meaningless) or when the value
+ *      isn't recognized.
+ *   3. page.upsell_mv_tiers — per-page MV tier range `{min, max}`
+ *      declaring the inclusive quantity-tier subset to render. Warns
+ *      when set on a non-upsell page, when shape is malformed (missing
+ *      field, non-integer, non-positive), or when min > max.
+ *
+ * All three are HINTS, not contracts. The build agent uses them as
+ * defaults; CLI/operator overrides win. Hence the warning severity
+ * across the board — these never block a build, they just nudge
+ * authoring quality.
+ *
+ * Doctrine note: template family is fundamentally a build-time
+ * decision and CLI/operator overrides always win. Authoring-time
+ * hints are allowed because designers / campaign owners often know
+ * the answer at authoring time, and re-deciding at build was
+ * repeated friction — hence warning severity, never a build blocker.
+ *
+ * Cross-field constraint enforcement (upsell_mv_tiers min <= max): the
+ * JSON Schema (schemas/campaign-runtime-build-packet.v0.schema.json)
+ * does NOT express this constraint — plain JSON Schema 2020-12 cannot
+ * say "field A must be less than or equal to field B" without
+ * $data-style extensions. Defense in depth lives at two layers
+ * instead: this rule warns the author at authoring/QA time, and the
+ * campaigns-os consumer's normalizedMvTiers() silently drops the field
+ * when min > max so a half-state spec never reaches the build agent
+ * through the packet. Both layers must stay aligned; loosening either
+ * one is a contract change worth a coordinated PR.
+ */
+import { KNOWN_TEMPLATE_FAMILY_HINTS } from "../types.js";
+const KNOWN_TEMPLATE_FAMILIES = new Set(KNOWN_TEMPLATE_FAMILY_HINTS);
+const KNOWN_UPSELL_PATTERNS = new Set([
+    'mv',
+    'bundle_tier_pills',
+    'bundle_tier_cards',
+    'single',
+]);
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function isPositiveInteger(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 1;
+}
+export const AssemblyHintsShape = {
+    id: 'AssemblyHintsShape',
+    severity: 'warning',
+    tags: ['fast', 'spec-only'],
+    check(spec) {
+        const violations = [];
+        // 1. Campaign-level template family hint.
+        const templateFamily = spec.campaign?.preferred_template_family;
+        if (templateFamily !== undefined) {
+            if (!isNonEmptyString(templateFamily)) {
+                violations.push({
+                    ruleId: 'AssemblyHintsShape',
+                    severity: 'warning',
+                    message: 'campaign.preferred_template_family is set but empty; remove the field or set it to a known family.',
+                    path: '/campaign/preferred_template_family',
+                    data: { check: 'template-family-empty' },
+                });
+            }
+            else if (!KNOWN_TEMPLATE_FAMILIES.has(templateFamily)) {
+                violations.push({
+                    ruleId: 'AssemblyHintsShape',
+                    severity: 'warning',
+                    message: `campaign.preferred_template_family "${templateFamily}" is not in the known set (${[...KNOWN_TEMPLATE_FAMILIES].sort().join(', ')}). The build agent will still try to use it as a hint, but consider correcting the value if this is a typo.`,
+                    path: '/campaign/preferred_template_family',
+                    data: { check: 'template-family-unknown', value: templateFamily },
+                });
+            }
+        }
+        // 2. Per-page upsell template pattern.
+        spec.funnels.forEach((funnel, funnelIdx) => {
+            const pages = funnel.pages ?? [];
+            pages.forEach((page, pageIdx) => {
+                const pattern = page.upsell_template_pattern;
+                if (pattern === undefined)
+                    return;
+                const path = `/funnels/${funnelIdx}/pages/${pageIdx}/upsell_template_pattern`;
+                const pageLabel = page.label || page.id || '(unnamed page)';
+                if (!isNonEmptyString(pattern)) {
+                    violations.push({
+                        ruleId: 'AssemblyHintsShape',
+                        severity: 'warning',
+                        message: `"${pageLabel}" — upsell_template_pattern is set but empty; remove the field or pick one of: ${[...KNOWN_UPSELL_PATTERNS].join(', ')}.`,
+                        path,
+                        data: { pageId: page.id, check: 'pattern-empty' },
+                    });
+                    return;
+                }
+                if (page.type !== 'upsell') {
+                    violations.push({
+                        ruleId: 'AssemblyHintsShape',
+                        severity: 'warning',
+                        message: `"${pageLabel}" — upsell_template_pattern is set on a non-upsell page (type=${page.type}). The hint is meaningful only on upsell pages; remove it or move it to an upsell page.`,
+                        path,
+                        data: { pageId: page.id, pageType: page.type, check: 'pattern-on-non-upsell' },
+                    });
+                }
+                if (!KNOWN_UPSELL_PATTERNS.has(pattern)) {
+                    violations.push({
+                        ruleId: 'AssemblyHintsShape',
+                        severity: 'warning',
+                        message: `"${pageLabel}" — upsell_template_pattern "${pattern}" is not in the known set (${[...KNOWN_UPSELL_PATTERNS].join(', ')}). Build will use it as a hint, but confirm the value matches a template-family variant.`,
+                        path,
+                        data: { pageId: page.id, check: 'pattern-unknown', value: pattern },
+                    });
+                }
+            });
+            // 3. Per-page MV upsell tier range.
+            pages.forEach((page, pageIdx) => {
+                const tiers = page.upsell_mv_tiers;
+                if (tiers === undefined)
+                    return;
+                const path = `/funnels/${funnelIdx}/pages/${pageIdx}/upsell_mv_tiers`;
+                const pageLabel = page.label || page.id || '(unnamed page)';
+                if (tiers === null || typeof tiers !== 'object' || Array.isArray(tiers)) {
+                    violations.push({
+                        ruleId: 'AssemblyHintsShape',
+                        severity: 'warning',
+                        message: `"${pageLabel}" — upsell_mv_tiers must be an object with numeric "min" and "max" fields; got ${Array.isArray(tiers) ? 'array' : typeof tiers}.`,
+                        path,
+                        data: { pageId: page.id, check: 'tiers-bad-shape' },
+                    });
+                    return;
+                }
+                const tiersObj = tiers;
+                const hasMin = 'min' in tiersObj;
+                const hasMax = 'max' in tiersObj;
+                // Extract to local bindings so TS can narrow across the type-guard
+                // calls below. Property accessors on a shared object don't carry
+                // narrowing through subsequent reads, which is what forced the
+                // earlier `as number` cast at the range check; local bindings fix
+                // that and the cast goes away.
+                const min = tiersObj.min;
+                const max = tiersObj.max;
+                if (page.type !== 'upsell') {
+                    violations.push({
+                        ruleId: 'AssemblyHintsShape',
+                        severity: 'warning',
+                        message: `"${pageLabel}" — upsell_mv_tiers is set on a non-upsell page (type=${page.type}). The hint is meaningful only on upsell pages; remove it or move it to an upsell page.`,
+                        path,
+                        data: { pageId: page.id, pageType: page.type, check: 'tiers-on-non-upsell' },
+                    });
+                }
+                if (!hasMin || !hasMax) {
+                    violations.push({
+                        ruleId: 'AssemblyHintsShape',
+                        severity: 'warning',
+                        message: `"${pageLabel}" — upsell_mv_tiers is missing ${!hasMin && !hasMax ? 'both "min" and "max"' : !hasMin ? '"min"' : '"max"'}; declare both as positive integers (e.g. {"min": 1, "max": 5}) or remove the field.`,
+                        path,
+                        data: { pageId: page.id, check: 'tiers-missing-field', hasMin, hasMax },
+                    });
+                    return;
+                }
+                if (!isPositiveInteger(min) || !isPositiveInteger(max)) {
+                    violations.push({
+                        ruleId: 'AssemblyHintsShape',
+                        severity: 'warning',
+                        message: `"${pageLabel}" — upsell_mv_tiers requires positive integers for "min" and "max"; got min=${JSON.stringify(min)}, max=${JSON.stringify(max)}.`,
+                        path,
+                        data: { pageId: page.id, check: 'tiers-bad-type', min, max },
+                    });
+                    return;
+                }
+                // min and max are narrowed to number here via the type guards above.
+                if (min > max) {
+                    violations.push({
+                        ruleId: 'AssemblyHintsShape',
+                        severity: 'warning',
+                        message: `"${pageLabel}" — upsell_mv_tiers has min=${min} greater than max=${max}; swap the values or fix the range.`,
+                        path,
+                        data: { pageId: page.id, check: 'tiers-bad-range', min, max },
+                    });
+                }
+            });
+        });
+        return violations;
+    },
+};

package/campaign-spec/dist/rules/campaign-metadata.d.ts

@@ -0,0 +1,14 @@
+/**
+ * CampaignMetadata — bundles two campaign-level metadata warnings:
+ *   1. Missing payment_env_key — required for spec export
+ *   2. Missing ref_id — needed for multi-campaign API disambiguation
+ *
+ * Both are warning severity. Bundled into one rule because they share a
+ * domain (campaign metadata completeness) and no caller has expressed
+ * a need to subset them. If that need shows up, split into
+ * CampaignPaymentKey and CampaignRefId.
+ *
+ * Message text inherited verbatim from the pre-#110 validator at migration time.
+ */
+import type { Rule } from '../types.ts';
+export declare const CampaignMetadata: Rule;

package/campaign-spec/dist/rules/campaign-metadata.js

@@ -0,0 +1,40 @@
+/**
+ * CampaignMetadata — bundles two campaign-level metadata warnings:
+ *   1. Missing payment_env_key — required for spec export
+ *   2. Missing ref_id — needed for multi-campaign API disambiguation
+ *
+ * Both are warning severity. Bundled into one rule because they share a
+ * domain (campaign metadata completeness) and no caller has expressed
+ * a need to subset them. If that need shows up, split into
+ * CampaignPaymentKey and CampaignRefId.
+ *
+ * Message text inherited verbatim from the pre-#110 validator at migration time.
+ */
+export const CampaignMetadata = {
+    id: 'CampaignMetadata',
+    severity: 'warning',
+    tags: ['fast', 'spec-only'],
+    check(spec) {
+        const violations = [];
+        const campaign = spec.campaign ?? {};
+        if (!campaign.payment_env_key) {
+            violations.push({
+                ruleId: 'CampaignMetadata',
+                severity: 'warning',
+                message: 'No campaign loaded — campaign key required for spec export.',
+                path: '/campaign/payment_env_key',
+                data: { missing: 'payment_env_key' },
+            });
+        }
+        if (campaign.ref_id == null) {
+            violations.push({
+                ruleId: 'CampaignMetadata',
+                severity: 'warning',
+                message: 'Campaign has no numeric ref_id; API refresh cannot disambiguate multi-campaign responses.',
+                path: '/campaign/ref_id',
+                data: { missing: 'ref_id' },
+            });
+        }
+        return violations;
+    },
+};

package/campaign-spec/dist/rules/checkout-has-success-url.d.ts

@@ -0,0 +1,31 @@
+/**
+ * CheckoutHasSuccessUrl — when the spec includes any upsell page, every
+ * checkout must declare SOME forward route so the runtime knows where to send
+ * the shopper after order placement.
+ *
+ * The check is on the shopper being able to continue, NOT on which field
+ * carried that intent. `success_url` and `next_page` express the same edge, and
+ * twelve pages across ten certified fixtures use `next_page` on their checkout
+ * — warning at those told authors to rename a field they had already filled in
+ * correctly. A
+ * campaign is a free-form journey; the tool has no business having an opinion
+ * about the field name when the route is unambiguous.
+ *
+ * The "any upsell present" precondition is the legacy heuristic for
+ * "this spec needs a multi-step post-checkout flow." Specs without upsells
+ * route to thankyou via the default thankyou path and don't need a
+ * checkout-level forward route declared.
+ *
+ * "Forward route" is whatever campaign-spec/routing.ts resolves — the same
+ * resolver that source intake and the QA topology extractor consume. Narrowing
+ * this rule is only safe because that edge now actually wires; narrowed alone
+ * it would have removed the sole signal on a still-dropped edge.
+ *
+ * The rule ID keeps its original name for consumer stability even though the
+ * condition is now field-agnostic. The violation path points at the page, not
+ * at /success_url, because no single field is the answer any more.
+ *
+ * Warning severity (not error) — preserves legacy classification.
+ */
+import type { Rule } from '../types.ts';
+export declare const CheckoutHasSuccessUrl: Rule;