@nextcommerce/campaigns-os 1.33.0

package/campaign-spec/dist/rules/page-id-uniqueness.js

@@ -0,0 +1,47 @@
+/**
+ * PageIdUniqueness — page IDs must be globally unique across all funnels
+ * because routing targets (next_page, success_url, on_accept, on_decline)
+ * reference pages by id alone with no funnel scope.
+ *
+ * Reports each duplicated id exactly once, at the path of the SECOND
+ * occurrence (the offender, not the original). Pages without an id are
+ * silently skipped — that's a different concern (page identity, not yet
+ * extracted as its own rule).
+ *
+ * Message text inherited verbatim from the pre-#110 validator at migration time.
+ */
+export const PageIdUniqueness = {
+    id: 'PageIdUniqueness',
+    severity: 'error',
+    tags: ['fast', 'structure', 'spec-only'],
+    check(spec) {
+        const seen = new Map();
+        const reported = new Set();
+        const violations = [];
+        spec.funnels.forEach((funnel, funnelIdx) => {
+            const pages = funnel.pages ?? [];
+            pages.forEach((page, pageIdx) => {
+                if (!page.id)
+                    return;
+                if (seen.has(page.id) && !reported.has(page.id)) {
+                    reported.add(page.id);
+                    violations.push({
+                        ruleId: 'PageIdUniqueness',
+                        severity: 'error',
+                        message: `Duplicate page id "${page.id}" across funnels — page IDs must be globally unique.`,
+                        path: `/funnels/${funnelIdx}/pages/${pageIdx}/id`,
+                        data: {
+                            pageId: page.id,
+                            firstOccurrence: seen.get(page.id),
+                            secondOccurrence: { funnelIdx, pageIdx },
+                        },
+                    });
+                }
+                else if (!seen.has(page.id)) {
+                    seen.set(page.id, { funnelIdx, pageIdx });
+                }
+            });
+        });
+        return violations;
+    },
+};

package/campaign-spec/dist/rules/promo-code-input-validation.d.ts

@@ -0,0 +1,8 @@
+/**
+ * PromoCodeInputValidation — validates checkout-level `promo_code_input`
+ * configuration. This mirrors the mapped-offer integrity checks for exit
+ * intent because both surfaces apply a voucher/code-backed Offer through the
+ * same Campaign Cart SDK/Campaigns API pricing path.
+ */
+import type { Rule } from '../types.ts';
+export declare const PromoCodeInputValidation: Rule;

package/campaign-spec/dist/rules/promo-code-input-validation.js

@@ -0,0 +1,126 @@
+/**
+ * PromoCodeInputValidation — validates checkout-level `promo_code_input`
+ * configuration. This mirrors the mapped-offer integrity checks for exit
+ * intent because both surfaces apply a voucher/code-backed Offer through the
+ * same Campaign Cart SDK/Campaigns API pricing path.
+ */
+function isTruthyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function offerDisplayName(offer) {
+    return offer.name || offer.code || String(offer.ref_id) || '(unnamed offer)';
+}
+function buildOfferIndex(offers) {
+    const byRefId = new Map();
+    const byCode = new Map();
+    for (const offer of offers) {
+        byRefId.set(String(offer.ref_id), offer);
+        if (offer.code)
+            byCode.set(String(offer.code).toUpperCase(), offer);
+    }
+    return { byRefId, byCode };
+}
+export const PromoCodeInputValidation = {
+    id: 'PromoCodeInputValidation',
+    severity: 'error',
+    tags: ['fast', 'references', 'spec-only'],
+    check(spec) {
+        const catalog = spec.offers ?? [];
+        const index = buildOfferIndex(catalog);
+        const violations = [];
+        spec.funnels.forEach((funnel, funnelIdx) => {
+            const pages = funnel.pages ?? [];
+            pages.forEach((page, pageIdx) => {
+                const promo = page.promo_code_input;
+                if (!promo?.enabled)
+                    return;
+                const path = `/funnels/${funnelIdx}/pages/${pageIdx}/promo_code_input`;
+                const ref = promo.offer_ref_id;
+                const code = promo.offer_code;
+                const refOffer = ref ? index.byRefId.get(String(ref)) : null;
+                const codeOffer = code ? index.byCode.get(String(code).toUpperCase()) : null;
+                if (page.type !== 'checkout') {
+                    violations.push({
+                        ruleId: 'PromoCodeInputValidation',
+                        severity: 'warning',
+                        message: `"${page.label}" — Promo code input is configured on a non-checkout page.`,
+                        path,
+                        data: { pageId: page.id, check: 'placement', pageType: page.type },
+                    });
+                }
+                if (!ref) {
+                    violations.push({
+                        ruleId: 'PromoCodeInputValidation',
+                        severity: 'error',
+                        message: `"${page.label}" — Promo code input enabled but no offer assigned.`,
+                        path: `${path}/offer_ref_id`,
+                        data: { pageId: page.id, check: 'missing_ref' },
+                    });
+                }
+                if (!code) {
+                    violations.push({
+                        ruleId: 'PromoCodeInputValidation',
+                        severity: 'error',
+                        message: `"${page.label}" — Promo code input enabled but no offer code assigned.`,
+                        path: `${path}/offer_code`,
+                        data: { pageId: page.id, check: 'missing_code' },
+                    });
+                }
+                if (catalog.length > 0 && ref && !refOffer) {
+                    violations.push({
+                        ruleId: 'PromoCodeInputValidation',
+                        severity: 'error',
+                        message: `"${page.label}" — Promo code input offer "${ref || code}" is not present in campaign offers. Refresh API data or choose a valid offer.`,
+                        path: `${path}/offer_ref_id`,
+                        data: { pageId: page.id, check: 'ref_not_in_catalog', refId: ref },
+                    });
+                }
+                if (catalog.length > 0 && code && !codeOffer) {
+                    violations.push({
+                        ruleId: 'PromoCodeInputValidation',
+                        severity: 'error',
+                        message: `"${page.label}" — Promo code input offer code "${code}" is not present in campaign offers. Refresh API data or choose a valid offer.`,
+                        path: `${path}/offer_code`,
+                        data: { pageId: page.id, check: 'code_not_in_catalog', code },
+                    });
+                }
+                if (refOffer && !isTruthyString(refOffer.code)) {
+                    violations.push({
+                        ruleId: 'PromoCodeInputValidation',
+                        severity: 'error',
+                        message: `"${page.label}" — Promo code input offer "${offerDisplayName(refOffer)}" has no voucher/code to apply at checkout.`,
+                        path: `${path}/offer_ref_id`,
+                        data: { pageId: page.id, check: 'ref_offer_lacks_code', refId: ref },
+                    });
+                }
+                if (refOffer &&
+                    isTruthyString(code) &&
+                    isTruthyString(refOffer.code) &&
+                    String(code).toUpperCase() !== String(refOffer.code).toUpperCase()) {
+                    violations.push({
+                        ruleId: 'PromoCodeInputValidation',
+                        severity: 'error',
+                        message: `"${page.label}" — Promo code input offer code "${code}" does not match campaign offer code "${refOffer.code}".`,
+                        path: `${path}/offer_code`,
+                        data: {
+                            pageId: page.id,
+                            check: 'code_ref_mismatch',
+                            providedCode: code,
+                            expectedCode: refOffer.code,
+                        },
+                    });
+                }
+                if (catalog.length === 0) {
+                    violations.push({
+                        ruleId: 'PromoCodeInputValidation',
+                        severity: 'warning',
+                        message: `"${page.label}" — Promo code input offer cannot be verified because campaign offers are missing from the spec.`,
+                        path,
+                        data: { pageId: page.id, check: 'empty_catalog' },
+                    });
+                }
+            });
+        });
+        return violations;
+    },
+};

package/campaign-spec/dist/rules/promo-codes-shape.d.ts

@@ -0,0 +1,30 @@
+/**
+ * PromoCodesShape — validates per-funnel `promo_codes` rosters introduced
+ * in Slice 4c.
+ *
+ * The starter templates' promo-banner.js / promo-timer.js ship with a
+ * hardcoded `const sales = [...]` array (17 seasonal entries with demo
+ * codes like SUMMER26, BF26, EXIT10). The build-side replacement step
+ * regenerates this array from `funnels[].promo_codes` so each merchant
+ * carries their own calendar in the spec rather than inheriting demo
+ * defaults.
+ *
+ * Hint posture: warning severity, never blocks a build. The build
+ * agent applies the replacement only when the spec carries a non-empty
+ * roster; otherwise the template's demo sales array passes through
+ * untouched.
+ *
+ * Validation surface:
+ *   - empty id / code (the two required identity fields)
+ *   - duplicate id within a funnel
+ *   - duplicate code within a funnel (codes should be unique so the
+ *     "first matching range wins" priority is deterministic)
+ *   - starts_at / ends_at parse as a Date (non-ISO strings warn)
+ *   - starts_at > ends_at (inverted range)
+ *
+ * The rule does NOT validate visual fields (title, emoji, colors, etc.)
+ * beyond "if present, must be a string" — those are presentation copy
+ * and the build renders whatever the author wrote.
+ */
+import type { Rule } from '../types.ts';
+export declare const PromoCodesShape: Rule;

package/campaign-spec/dist/rules/promo-codes-shape.js

@@ -0,0 +1,187 @@
+/**
+ * PromoCodesShape — validates per-funnel `promo_codes` rosters introduced
+ * in Slice 4c.
+ *
+ * The starter templates' promo-banner.js / promo-timer.js ship with a
+ * hardcoded `const sales = [...]` array (17 seasonal entries with demo
+ * codes like SUMMER26, BF26, EXIT10). The build-side replacement step
+ * regenerates this array from `funnels[].promo_codes` so each merchant
+ * carries their own calendar in the spec rather than inheriting demo
+ * defaults.
+ *
+ * Hint posture: warning severity, never blocks a build. The build
+ * agent applies the replacement only when the spec carries a non-empty
+ * roster; otherwise the template's demo sales array passes through
+ * untouched.
+ *
+ * Validation surface:
+ *   - empty id / code (the two required identity fields)
+ *   - duplicate id within a funnel
+ *   - duplicate code within a funnel (codes should be unique so the
+ *     "first matching range wins" priority is deterministic)
+ *   - starts_at / ends_at parse as a Date (non-ISO strings warn)
+ *   - starts_at > ends_at (inverted range)
+ *
+ * The rule does NOT validate visual fields (title, emoji, colors, etc.)
+ * beyond "if present, must be a string" — those are presentation copy
+ * and the build renders whatever the author wrote.
+ */
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function isValidDateString(value) {
+    if (typeof value !== 'string')
+        return false;
+    if (value.trim().length === 0)
+        return false;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed);
+}
+const VISUAL_STRING_FIELDS = [
+    'title',
+    'emoji',
+    'offer1',
+    'offer2',
+    'top_bar_bg',
+    'highlight_color',
+    'banner_text',
+    'banner_text_sec',
+    'limited_time',
+];
+export const PromoCodesShape = {
+    id: 'PromoCodesShape',
+    severity: 'warning',
+    tags: ['fast', 'spec-only'],
+    check(spec) {
+        const violations = [];
+        spec.funnels.forEach((funnel, funnelIdx) => {
+            const codes = funnel.promo_codes;
+            if (codes === undefined)
+                return;
+            const funnelLabel = funnel.name || funnel.id || `funnel ${funnelIdx}`;
+            if (!Array.isArray(codes)) {
+                violations.push({
+                    ruleId: 'PromoCodesShape',
+                    severity: 'warning',
+                    message: `"${funnelLabel}" — promo_codes must be an array; got ${codes === null ? 'null' : typeof codes}.`,
+                    path: `/funnels/${funnelIdx}/promo_codes`,
+                    data: { funnelId: funnel.id, check: 'promo-codes-bad-shape' },
+                });
+                return;
+            }
+            const seenIds = new Set();
+            const seenCodes = new Set();
+            codes.forEach((entry, entryIdx) => {
+                const path = `/funnels/${funnelIdx}/promo_codes/${entryIdx}`;
+                if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+                    violations.push({
+                        ruleId: 'PromoCodesShape',
+                        severity: 'warning',
+                        message: `"${funnelLabel}" — promo_codes[${entryIdx}] must be an object; got ${entry === null ? 'null' : Array.isArray(entry) ? 'array' : typeof entry}.`,
+                        path,
+                        data: { funnelId: funnel.id, index: entryIdx, check: 'promo-entry-bad-shape' },
+                    });
+                    return;
+                }
+                const promo = entry;
+                if (!isNonEmptyString(promo.id)) {
+                    violations.push({
+                        ruleId: 'PromoCodesShape',
+                        severity: 'warning',
+                        message: `"${funnelLabel}" — promo_codes[${entryIdx}].id is required and must be a non-empty string.`,
+                        path: `${path}/id`,
+                        data: { funnelId: funnel.id, index: entryIdx, check: 'promo-id-missing' },
+                    });
+                }
+                else {
+                    if (seenIds.has(promo.id)) {
+                        violations.push({
+                            ruleId: 'PromoCodesShape',
+                            severity: 'warning',
+                            message: `"${funnelLabel}" — promo_codes[${entryIdx}].id "${promo.id}" duplicates an earlier entry; ids must be unique within a funnel.`,
+                            path: `${path}/id`,
+                            data: { funnelId: funnel.id, index: entryIdx, check: 'promo-id-duplicate', value: promo.id },
+                        });
+                    }
+                    seenIds.add(promo.id);
+                }
+                if (!isNonEmptyString(promo.code)) {
+                    violations.push({
+                        ruleId: 'PromoCodesShape',
+                        severity: 'warning',
+                        message: `"${funnelLabel}" — promo_codes[${entryIdx}].code is required and must be a non-empty string.`,
+                        path: `${path}/code`,
+                        data: { funnelId: funnel.id, index: entryIdx, check: 'promo-code-missing' },
+                    });
+                }
+                else {
+                    const codeUpper = promo.code.toUpperCase();
+                    if (seenCodes.has(codeUpper)) {
+                        violations.push({
+                            ruleId: 'PromoCodesShape',
+                            severity: 'warning',
+                            message: `"${funnelLabel}" — promo_codes[${entryIdx}].code "${promo.code}" duplicates an earlier entry (case-insensitive); ordering decides priority so duplicates are ambiguous.`,
+                            path: `${path}/code`,
+                            data: { funnelId: funnel.id, index: entryIdx, check: 'promo-code-duplicate', value: promo.code },
+                        });
+                    }
+                    seenCodes.add(codeUpper);
+                }
+                // Date validation: when present, must parse. Both fields are optional;
+                // missing one is fine ("starts now" or "no end").
+                const hasStarts = promo.starts_at !== undefined && promo.starts_at !== null && promo.starts_at !== '';
+                const hasEnds = promo.ends_at !== undefined && promo.ends_at !== null && promo.ends_at !== '';
+                const startsOk = !hasStarts || isValidDateString(promo.starts_at);
+                const endsOk = !hasEnds || isValidDateString(promo.ends_at);
+                if (hasStarts && !startsOk) {
+                    violations.push({
+                        ruleId: 'PromoCodesShape',
+                        severity: 'warning',
+                        message: `"${funnelLabel}" — promo_codes[${entryIdx}].starts_at "${promo.starts_at}" is not a valid ISO date string.`,
+                        path: `${path}/starts_at`,
+                        data: { funnelId: funnel.id, index: entryIdx, check: 'promo-starts-at-bad', value: promo.starts_at },
+                    });
+                }
+                if (hasEnds && !endsOk) {
+                    violations.push({
+                        ruleId: 'PromoCodesShape',
+                        severity: 'warning',
+                        message: `"${funnelLabel}" — promo_codes[${entryIdx}].ends_at "${promo.ends_at}" is not a valid ISO date string.`,
+                        path: `${path}/ends_at`,
+                        data: { funnelId: funnel.id, index: entryIdx, check: 'promo-ends-at-bad', value: promo.ends_at },
+                    });
+                }
+                if (hasStarts && hasEnds && startsOk && endsOk) {
+                    const startsAt = Date.parse(promo.starts_at);
+                    const endsAt = Date.parse(promo.ends_at);
+                    if (startsAt > endsAt) {
+                        violations.push({
+                            ruleId: 'PromoCodesShape',
+                            severity: 'warning',
+                            message: `"${funnelLabel}" — promo_codes[${entryIdx}] starts_at "${promo.starts_at}" is after ends_at "${promo.ends_at}"; swap the values or fix the range.`,
+                            path,
+                            data: { funnelId: funnel.id, index: entryIdx, check: 'promo-range-inverted', starts_at: promo.starts_at, ends_at: promo.ends_at },
+                        });
+                    }
+                }
+                // Visual presentation fields: if present, must be a string. We don't
+                // narrow the values (e.g. color format), since author intent is
+                // freeform copy / brand color choice.
+                for (const field of VISUAL_STRING_FIELDS) {
+                    if (promo[field] === undefined)
+                        continue;
+                    if (typeof promo[field] !== 'string') {
+                        violations.push({
+                            ruleId: 'PromoCodesShape',
+                            severity: 'warning',
+                            message: `"${funnelLabel}" — promo_codes[${entryIdx}].${field} must be a string; got ${typeof promo[field]}.`,
+                            path: `${path}/${field}`,
+                            data: { funnelId: funnel.id, index: entryIdx, field, check: 'promo-visual-bad-type' },
+                        });
+                    }
+                }
+            });
+        });
+        return violations;
+    },
+};

package/campaign-spec/dist/rules/route-field-ignored-for-page-type.d.ts

@@ -0,0 +1,33 @@
+/**
+ * RouteFieldIgnoredForPageType — a page declares a forward-route field its
+ * type cannot satisfy, so routing skips it.
+ *
+ * Today that means exactly one shape: `success_url` on a page that is not a
+ * checkout. `success_url` means "where the shopper goes after payment
+ * succeeds", and only a checkout takes payment, so on a `select` or `landing`
+ * page the field names an event that never happens there (campaigns-os#234).
+ * Routing therefore ignores it and `next_page` wins.
+ *
+ * Why this rule exists at all. Before #234 the stray field silently OUTRANKED
+ * the page's real next step — a select page declaring `next_page: checkout`
+ * and `success_url: upsell` wired the upsell and skipped payment. #234 fixes
+ * the routing, but a spec author who wrote the field still gets behaviour they
+ * did not ask for, just the safe kind now. RouteTargetResolves only catches
+ * this when the target does not resolve; when both targets are real pages it
+ * has nothing to say. A comment removed in #233 assumed a rule already covered
+ * the case. It did not. This is that rule.
+ *
+ * Warning, not error. The build is correct either way — the field is inert,
+ * not broken — and it is overwhelmingly a copy-paste from the checkout below.
+ * Blocking on it would fail builds that ship fine.
+ *
+ * The set of ignored fields comes from routing.ts via
+ * `inapplicableForwardFields`, and the field's meaning and permitted types
+ * from `describeForwardField` — never re-derived here. A rule that
+ * disagreed with the resolver about which fields are live would be worse than
+ * no rule, and a hand-written checkout-specific sentence would quietly become
+ * a lie the first time a second field or a second payment-bearing type joins
+ * the table.
+ */
+import type { Rule } from '../types.ts';
+export declare const RouteFieldIgnoredForPageType: Rule;

package/campaign-spec/dist/rules/route-field-ignored-for-page-type.js

@@ -0,0 +1,81 @@
+/**
+ * RouteFieldIgnoredForPageType — a page declares a forward-route field its
+ * type cannot satisfy, so routing skips it.
+ *
+ * Today that means exactly one shape: `success_url` on a page that is not a
+ * checkout. `success_url` means "where the shopper goes after payment
+ * succeeds", and only a checkout takes payment, so on a `select` or `landing`
+ * page the field names an event that never happens there (campaigns-os#234).
+ * Routing therefore ignores it and `next_page` wins.
+ *
+ * Why this rule exists at all. Before #234 the stray field silently OUTRANKED
+ * the page's real next step — a select page declaring `next_page: checkout`
+ * and `success_url: upsell` wired the upsell and skipped payment. #234 fixes
+ * the routing, but a spec author who wrote the field still gets behaviour they
+ * did not ask for, just the safe kind now. RouteTargetResolves only catches
+ * this when the target does not resolve; when both targets are real pages it
+ * has nothing to say. A comment removed in #233 assumed a rule already covered
+ * the case. It did not. This is that rule.
+ *
+ * Warning, not error. The build is correct either way — the field is inert,
+ * not broken — and it is overwhelmingly a copy-paste from the checkout below.
+ * Blocking on it would fail builds that ship fine.
+ *
+ * The set of ignored fields comes from routing.ts via
+ * `inapplicableForwardFields`, and the field's meaning and permitted types
+ * from `describeForwardField` — never re-derived here. A rule that
+ * disagreed with the resolver about which fields are live would be worse than
+ * no rule, and a hand-written checkout-specific sentence would quietly become
+ * a lie the first time a second field or a second payment-bearing type joins
+ * the table.
+ */
+import { describeForwardField, forwardRouteTarget, inapplicableForwardFields, } from "../routing.js";
+export const RouteFieldIgnoredForPageType = {
+    id: 'RouteFieldIgnoredForPageType',
+    severity: 'warning',
+    tags: ['fast', 'structure', 'spec-only'],
+    check(spec) {
+        const violations = [];
+        spec.funnels.forEach((funnel, funnelIdx) => {
+            const pages = funnel.pages ?? [];
+            pages.forEach((page, pageIdx) => {
+                const ignored = inapplicableForwardFields(page);
+                if (ignored.length === 0)
+                    return;
+                // Naming the field that actually wins is what makes this actionable:
+                // "ignored" alone leaves the author guessing where the shopper goes.
+                const winner = forwardRouteTarget(page);
+                const outcome = winner
+                    ? `This page routes forward to "${winner}" instead.`
+                    : 'This page has no forward route at all as a result.';
+                for (const field of ignored) {
+                    const applicability = describeForwardField(field);
+                    const honoured = (applicability?.requiredTypes ?? [])
+                        .map((type) => `"${type}"`)
+                        .join(' or ');
+                    const meaning = applicability?.meaning ?? 'something this page type cannot provide';
+                    // A page with no usable `type` reaches here too, and telling that
+                    // author about payment semantics points at the wrong defect: the
+                    // real problem is the missing required field, not the routing.
+                    const where = typeof page.type === 'string' && page.type.trim()
+                        ? `on a "${page.type}" page`
+                        : 'because this page declares no valid "type"';
+                    violations.push({
+                        ruleId: 'RouteFieldIgnoredForPageType',
+                        severity: 'warning',
+                        message: `"${field}" is ignored for routing ${where} — it means ${meaning}, which only ${honoured} can satisfy. ${outcome}`,
+                        path: `/funnels/${funnelIdx}/pages/${pageIdx}/${field}`,
+                        data: {
+                            pageId: page.id,
+                            pageType: page.type,
+                            field,
+                            target: page[field],
+                            routedTo: winner,
+                        },
+                    });
+                }
+            });
+        });
+        return violations;
+    },
+};

package/campaign-spec/dist/rules/route-target-resolves.d.ts

@@ -0,0 +1,32 @@
+/**
+ * RouteTargetResolves — every declared routing target must name a page that
+ * exists in the same funnel.
+ *
+ * Nothing checked this before, and the cost was real: six certified fixtures
+ * declared `next_page: "upsell-bundle-stepper.html"` on a checkout whose funnel
+ * has no such page (its upsell is `upsell-stepper` — the name was copied from
+ * the MV families, which do have that page). Source intake resolves an unknown
+ * target by falling back to treating the raw string as a route, so those six
+ * emitted a confident `next_url` to a route nothing serves: a shopper reaching
+ * the end of checkout would land on a 404.
+ *
+ * The old CheckoutHasSuccessUrl covered this only by accident — it demanded
+ * `success_url`, and these pages had none — so narrowing that rule to "has any
+ * forward route" removed the last signal. This rule is the deliberate
+ * replacement, and it checks the thing that actually matters: not which field
+ * carried the intent, but whether the shopper can get where it points.
+ *
+ * Warning, not error. A campaign is a free-form journey and the resolver
+ * intentionally passes through absolute URLs and fragments; a target this rule
+ * cannot resolve is worth surfacing, but blocking a build on it would strand
+ * exactly the unconventional authors the routing work exists to support.
+ *
+ * Targets are matched against page IDs and against the routes pages actually
+ * serve (`page_url`), tolerating the corpus's `.html` suffix dialect
+ * (`upsell-stepper.html` matches page `upsell-stepper`) because intake's route
+ * fallback resolves that shape correctly. Absolute http(s) URLs, `#`
+ * fragments and rooted paths are deliberate off-graph destinations and are
+ * never flagged.
+ */
+import type { Rule } from '../types.ts';
+export declare const RouteTargetResolves: Rule;

package/campaign-spec/dist/rules/route-target-resolves.js

@@ -0,0 +1,112 @@
+/**
+ * RouteTargetResolves — every declared routing target must name a page that
+ * exists in the same funnel.
+ *
+ * Nothing checked this before, and the cost was real: six certified fixtures
+ * declared `next_page: "upsell-bundle-stepper.html"` on a checkout whose funnel
+ * has no such page (its upsell is `upsell-stepper` — the name was copied from
+ * the MV families, which do have that page). Source intake resolves an unknown
+ * target by falling back to treating the raw string as a route, so those six
+ * emitted a confident `next_url` to a route nothing serves: a shopper reaching
+ * the end of checkout would land on a 404.
+ *
+ * The old CheckoutHasSuccessUrl covered this only by accident — it demanded
+ * `success_url`, and these pages had none — so narrowing that rule to "has any
+ * forward route" removed the last signal. This rule is the deliberate
+ * replacement, and it checks the thing that actually matters: not which field
+ * carried the intent, but whether the shopper can get where it points.
+ *
+ * Warning, not error. A campaign is a free-form journey and the resolver
+ * intentionally passes through absolute URLs and fragments; a target this rule
+ * cannot resolve is worth surfacing, but blocking a build on it would strand
+ * exactly the unconventional authors the routing work exists to support.
+ *
+ * Targets are matched against page IDs and against the routes pages actually
+ * serve (`page_url`), tolerating the corpus's `.html` suffix dialect
+ * (`upsell-stepper.html` matches page `upsell-stepper`) because intake's route
+ * fallback resolves that shape correctly. Absolute http(s) URLs, `#`
+ * fragments and rooted paths are deliberate off-graph destinations and are
+ * never flagged.
+ */
+import { ROUTE_FIELDS, inapplicableForwardFields } from "../routing.js";
+/**
+ * Destinations that deliberately leave this spec's page graph. A rooted path is
+ * the partial-scope pattern ThankYouRequirement documents — "traffic continues
+ * to an existing downstream route" — and flagging it would fire this rule on a
+ * legitimate, supported shape.
+ */
+function isOffGraphTarget(target) {
+    return target.startsWith('#') || target.startsWith('/') || /^https?:\/\//i.test(target);
+}
+/**
+ * Strip the surrounding slashes and any `.html` suffix, so a target, a page ID
+ * and a declared `page_url` can be compared on equal terms. Case is preserved
+ * deliberately: intake's lookup is case-sensitive, and folding case here would
+ * make the rule PASS targets the build then fails to resolve — a false negative
+ * is worse than the false positive it would avoid.
+ */
+function normalizeRouteish(value) {
+    const trimmed = value.trim().replace(/^\/+|\/+$/g, '');
+    return trimmed.toLowerCase().endsWith('.html') ? trimmed.slice(0, -'.html'.length) : trimmed;
+}
+/**
+ * Everything a target may legitimately name: a page's ID, or the route it
+ * actually serves. Matching IDs alone flagged a working link — a page with an
+ * explicit `page_url` is reached at that route, and intake resolves a target
+ * naming it correctly, so the rule must too.
+ */
+function resolvableNames(pages) {
+    const names = new Set();
+    for (const page of pages) {
+        if (page.id) {
+            names.add(page.id);
+            names.add(normalizeRouteish(page.id));
+        }
+        const route = page.page_url;
+        if (typeof route === 'string' && route.trim())
+            names.add(normalizeRouteish(route));
+    }
+    names.delete('');
+    return names;
+}
+export const RouteTargetResolves = {
+    id: 'RouteTargetResolves',
+    severity: 'warning',
+    tags: ['fast', 'structure', 'spec-only'],
+    check(spec) {
+        const violations = [];
+        spec.funnels.forEach((funnel, funnelIdx) => {
+            const pages = funnel.pages ?? [];
+            const known = resolvableNames(pages);
+            pages.forEach((page, pageIdx) => {
+                // A field the page's type cannot satisfy is inert: routing skips it, so
+                // the built page does NOT link to its target and this rule's message
+                // ("the built page would link to a route nothing serves") would be
+                // false. RouteFieldIgnoredForPageType owns that shape. Reading the
+                // exclusion from the resolver keeps the two rules from telling an
+                // author opposite stories about the same field (#234).
+                const inert = new Set(inapplicableForwardFields(page));
+                for (const field of ROUTE_FIELDS) {
+                    if (inert.has(field))
+                        continue;
+                    const raw = page[field];
+                    if (typeof raw !== 'string')
+                        continue;
+                    const target = raw.trim();
+                    if (!target || isOffGraphTarget(target))
+                        continue;
+                    if (known.has(target) || known.has(normalizeRouteish(target)))
+                        continue;
+                    violations.push({
+                        ruleId: 'RouteTargetResolves',
+                        severity: 'warning',
+                        message: `Routing target "${target}" resolves to no page in this funnel; the built page would link to a route nothing serves.`,
+                        path: `/funnels/${funnelIdx}/pages/${pageIdx}/${field}`,
+                        data: { pageId: page.id, field, target },
+                    });
+                }
+            });
+        });
+        return violations;
+    },
+};