@nextcommerce/campaigns-os 1.33.0

package/campaign-spec/dist/rules/funnel-hypothesis-length.d.ts

@@ -0,0 +1,22 @@
+/**
+ * FunnelHypothesisLength — enforces the [10, 500] character bound on each
+ * funnel's `hypothesis` field. Short hypotheses signal a draft funnel that
+ * hasn't been thought through; long ones suggest the wrong field is being
+ * used.
+ *
+ * A hypothesis states what one path is testing against another, so it is
+ * required only when the spec has two or more funnels. A single-funnel spec
+ * may omit it (#294). Absent means null, undefined, or a string that is
+ * empty after trimming: editors clear a text field to "", not to null, and
+ * an optional field should not fail on the way an editor spells "nothing".
+ * When a real value is present the length bound still applies regardless of
+ * funnel count, and both bounds measure the trimmed value, so padding can
+ * neither rescue a short hypothesis nor sink a long one. The schema already
+ * types the field as optional; this rule owns the conditional requirement.
+ *
+ * Message text inherited verbatim from the pre-#110 validator at migration
+ * time — substrings ("at least 10 chars", "at most 500 chars") are matched
+ * by caller tests.
+ */
+import type { Rule } from '../types.ts';
+export declare const FunnelHypothesisLength: Rule;

package/campaign-spec/dist/rules/funnel-hypothesis-length.js

@@ -0,0 +1,60 @@
+/**
+ * FunnelHypothesisLength — enforces the [10, 500] character bound on each
+ * funnel's `hypothesis` field. Short hypotheses signal a draft funnel that
+ * hasn't been thought through; long ones suggest the wrong field is being
+ * used.
+ *
+ * A hypothesis states what one path is testing against another, so it is
+ * required only when the spec has two or more funnels. A single-funnel spec
+ * may omit it (#294). Absent means null, undefined, or a string that is
+ * empty after trimming: editors clear a text field to "", not to null, and
+ * an optional field should not fail on the way an editor spells "nothing".
+ * When a real value is present the length bound still applies regardless of
+ * funnel count, and both bounds measure the trimmed value, so padding can
+ * neither rescue a short hypothesis nor sink a long one. The schema already
+ * types the field as optional; this rule owns the conditional requirement.
+ *
+ * Message text inherited verbatim from the pre-#110 validator at migration
+ * time — substrings ("at least 10 chars", "at most 500 chars") are matched
+ * by caller tests.
+ */
+const MIN_LENGTH = 10;
+const MAX_LENGTH = 500;
+// Below this many funnels there is nothing to compare, so no hypothesis is owed.
+const MIN_FUNNELS_FOR_REQUIRED = 2;
+export const FunnelHypothesisLength = {
+    id: 'FunnelHypothesisLength',
+    severity: 'error',
+    tags: ['fast', 'spec-only'],
+    check(spec) {
+        const violations = [];
+        const hypothesisRequired = spec.funnels.length >= MIN_FUNNELS_FOR_REQUIRED;
+        spec.funnels.forEach((funnel, idx) => {
+            const fid = funnel.id || '(unnamed)';
+            const hyp = funnel.hypothesis == null ? '' : String(funnel.hypothesis).trim();
+            const absent = hyp === '';
+            if (absent && !hypothesisRequired)
+                return;
+            const path = `/funnels/${idx}/hypothesis`;
+            if (hyp.length < MIN_LENGTH) {
+                violations.push({
+                    ruleId: 'FunnelHypothesisLength',
+                    severity: 'error',
+                    message: `Funnel "${fid}" — hypothesis must be at least ${MIN_LENGTH} chars (got ${hyp.length}).`,
+                    path,
+                    data: { funnelId: fid, length: hyp.length, min: MIN_LENGTH },
+                });
+            }
+            else if (hyp.length > MAX_LENGTH) {
+                violations.push({
+                    ruleId: 'FunnelHypothesisLength',
+                    severity: 'error',
+                    message: `Funnel "${fid}" — hypothesis must be at most ${MAX_LENGTH} chars (got ${hyp.length}).`,
+                    path,
+                    data: { funnelId: fid, length: hyp.length, max: MAX_LENGTH },
+                });
+            }
+        });
+        return violations;
+    },
+};

package/campaign-spec/dist/rules/funnel-identity.d.ts

@@ -0,0 +1,15 @@
+/**
+ * FunnelIdentity — enforces per-funnel identity invariants:
+ *   - id is present
+ *   - id is globally unique across funnels
+ *   - name is present (non-empty after trim)
+ *
+ * One rule, multiple potential violations. Message text was preserved
+ * verbatim from the pre-#110 validator at migration time and is now the
+ * canonical wording — caller tests across the repo match these substrings.
+ *
+ * Note: hypothesis length is a separate concern (FunnelHypothesisLength) so
+ * each can be filtered independently by tag.
+ */
+import type { Rule } from '../types.ts';
+export declare const FunnelIdentity: Rule;

package/campaign-spec/dist/rules/funnel-identity.js

@@ -0,0 +1,57 @@
+/**
+ * FunnelIdentity — enforces per-funnel identity invariants:
+ *   - id is present
+ *   - id is globally unique across funnels
+ *   - name is present (non-empty after trim)
+ *
+ * One rule, multiple potential violations. Message text was preserved
+ * verbatim from the pre-#110 validator at migration time and is now the
+ * canonical wording — caller tests across the repo match these substrings.
+ *
+ * Note: hypothesis length is a separate concern (FunnelHypothesisLength) so
+ * each can be filtered independently by tag.
+ */
+export const FunnelIdentity = {
+    id: 'FunnelIdentity',
+    severity: 'error',
+    tags: ['fast', 'structure', 'spec-only'],
+    check(spec) {
+        const violations = [];
+        const seenIds = new Set();
+        spec.funnels.forEach((funnel, idx) => {
+            const fid = funnel.id || '(unnamed)';
+            const path = `/funnels/${idx}`;
+            if (!funnel.id) {
+                violations.push({
+                    ruleId: 'FunnelIdentity',
+                    severity: 'error',
+                    message: 'Funnel is missing an id.',
+                    path: `${path}/id`,
+                    data: { funnelId: fid, funnelIdx: idx },
+                });
+            }
+            else if (seenIds.has(funnel.id)) {
+                violations.push({
+                    ruleId: 'FunnelIdentity',
+                    severity: 'error',
+                    message: `Duplicate funnel id "${funnel.id}".`,
+                    path: `${path}/id`,
+                    data: { funnelId: funnel.id, funnelIdx: idx },
+                });
+            }
+            else {
+                seenIds.add(funnel.id);
+            }
+            if (!funnel.name || String(funnel.name).trim() === '') {
+                violations.push({
+                    ruleId: 'FunnelIdentity',
+                    severity: 'error',
+                    message: `Funnel "${fid}" — name is required.`,
+                    path: `${path}/name`,
+                    data: { funnelId: fid, funnelIdx: idx },
+                });
+            }
+        });
+        return violations;
+    },
+};

package/campaign-spec/dist/rules/funnel-weight-sum.d.ts

@@ -0,0 +1,20 @@
+/**
+ * FunnelWeightSum — flags funnel weight problems.
+ *
+ * Two failure modes, both emitted under the same rule id:
+ *   1. Per-funnel weight outside [0, 100] or non-finite.
+ *      → Violation at /funnels/<idx>/weight, severity error.
+ *   2. Aggregate sum of valid weights != 100 (± 0.01 tolerance for float input
+ *      like 33.33 + 33.33 + 33.34).
+ *      → Violation at /funnels, severity error.
+ *
+ * Tags: fast, structure, spec-only. Cheap enough for per-keystroke Map
+ * Builder contexts (Decision: this is the "fast" rule shape we promised).
+ *
+ * NOTE: This rule could be split into FunnelWeightRange (per-funnel) and
+ * FunnelWeightSum (aggregate) for finer composition. Kept fused for now —
+ * the two checks share traversal and tend to fire together; splitting is
+ * cheap to do later when a caller actually needs to subset.
+ */
+import type { Rule } from '../types.ts';
+export declare const FunnelWeightSum: Rule;

package/campaign-spec/dist/rules/funnel-weight-sum.js

@@ -0,0 +1,66 @@
+/**
+ * FunnelWeightSum — flags funnel weight problems.
+ *
+ * Two failure modes, both emitted under the same rule id:
+ *   1. Per-funnel weight outside [0, 100] or non-finite.
+ *      → Violation at /funnels/<idx>/weight, severity error.
+ *   2. Aggregate sum of valid weights != 100 (± 0.01 tolerance for float input
+ *      like 33.33 + 33.33 + 33.34).
+ *      → Violation at /funnels, severity error.
+ *
+ * Tags: fast, structure, spec-only. Cheap enough for per-keystroke Map
+ * Builder contexts (Decision: this is the "fast" rule shape we promised).
+ *
+ * NOTE: This rule could be split into FunnelWeightRange (per-funnel) and
+ * FunnelWeightSum (aggregate) for finer composition. Kept fused for now —
+ * the two checks share traversal and tend to fire together; splitting is
+ * cheap to do later when a caller actually needs to subset.
+ */
+const SUM_TOLERANCE = 0.01;
+const EXPECTED_SUM = 100;
+function toFiniteWeight(value) {
+    const num = typeof value === 'number' ? value : Number(value);
+    return Number.isFinite(num) ? num : null;
+}
+export const FunnelWeightSum = {
+    id: 'FunnelWeightSum',
+    severity: 'error',
+    tags: ['fast', 'structure', 'spec-only'],
+    check(spec) {
+        const violations = [];
+        let sum = 0;
+        let anyInRange = false;
+        spec.funnels.forEach((funnel, idx) => {
+            const weight = toFiniteWeight(funnel.weight);
+            if (weight == null || weight < 0 || weight > EXPECTED_SUM) {
+                // Message text is the canonical wording, inherited from the pre-#110
+                // validator at migration time. Caller tests across the repo match on
+                // this substring; improvements land in a follow-up when needed.
+                violations.push({
+                    ruleId: 'FunnelWeightSum',
+                    severity: 'error',
+                    message: `Funnel "${funnel.id ?? '(unnamed)'}" — weight must be a number in [0, 100] (got ${funnel.weight}).`,
+                    path: `/funnels/${idx}/weight`,
+                    data: { funnelId: funnel.id, weight: funnel.weight },
+                });
+                return;
+            }
+            anyInRange = true;
+            sum += weight;
+        });
+        // If no funnels had a valid weight, the sum check would be meaningless;
+        // the per-funnel violations carry the signal.
+        if (spec.funnels.length > 0 && anyInRange) {
+            if (Math.abs(sum - EXPECTED_SUM) > SUM_TOLERANCE) {
+                violations.push({
+                    ruleId: 'FunnelWeightSum',
+                    severity: 'error',
+                    message: `Funnel weights must sum to 100 (got ${sum}).`,
+                    path: '/funnels',
+                    data: { sum, expected: EXPECTED_SUM, tolerance: SUM_TOLERANCE },
+                });
+            }
+        }
+        return violations;
+    },
+};

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

@@ -0,0 +1,69 @@
+/**
+ * Rule registry — preset RuleSet constants.
+ *
+ * Callers either pick a preset (allRules / fastRules / specOnlyRules) or
+ * filter inline:
+ *
+ *   const myRules = allRules.filter(r => r.tags.includes('fast'))
+ *
+ * Tags are a closed taxonomy (see ../types.ts). To add a rule:
+ *   1. Create rules/<your-rule>.ts exporting a `Rule`.
+ *   2. Add it to `allRules` below.
+ *   3. fastRules / specOnlyRules pick up via tag filter automatically.
+ *
+ * Rules are listed in a stable order — the order callers see violations in
+ * for a multi-rule run. Keep cheap/metadata checks first so they surface
+ * before downstream complaints.
+ */
+import type { RuleSet } from '../types.ts';
+export { SchemaVersion, SUPPORTED_SCHEMA_VERSIONS } from './schema-version.ts';
+export { SdkVersion } from './sdk-version.ts';
+export { UnknownTopLevelFields, KNOWN_TOP_LEVEL_FIELDS, KNOWN_CAMPAIGN_FIELDS } from './unknown-top-level-fields.ts';
+export { CampaignMetadata } from './campaign-metadata.ts';
+export { FunnelCount } from './funnel-count.ts';
+export { FunnelIdentity } from './funnel-identity.ts';
+export { FunnelHypothesisLength } from './funnel-hypothesis-length.ts';
+export { FunnelWeightSum } from './funnel-weight-sum.ts';
+export { PageCount } from './page-count.ts';
+export { ThankYouRequirement } from './thank-you-requirement.ts';
+export { PageIdUniqueness } from './page-id-uniqueness.ts';
+export { UpsellHasPackages } from './upsell-has-packages.ts';
+export { UpsellRoutingComplete } from './upsell-routing-complete.ts';
+export { RouteFieldIgnoredForPageType } from './route-field-ignored-for-page-type.ts';
+export { CheckoutHasSuccessUrl } from './checkout-has-success-url.ts';
+export { UpsellWithoutCheckout } from './upsell-without-checkout.ts';
+export { DownsellWithoutUpsell } from './downsell-without-upsell.ts';
+export { PackagePricingSanity } from './package-pricing-sanity.ts';
+export { ShippingMethodsPresent } from './shipping-methods-present.ts';
+export { ShippingCountriesShape } from './shipping-countries-shape.ts';
+export { OfferRefIntegrity } from './offer-ref-integrity.ts';
+export { ExitIntentValidation } from './exit-intent-validation.ts';
+export { PromoCodeInputValidation } from './promo-code-input-validation.ts';
+export { DesignSourceShape } from './design-source-shape.ts';
+export { AssemblyHintsShape } from './assembly-hints-shape.ts';
+export { PromoCodesShape } from './promo-codes-shape.ts';
+export { VariantLabelsShape } from './variant-labels-shape.ts';
+export { StoreProfileShape } from './store-profile-shape.ts';
+export { AnalyticsContractShape } from './analytics-contract-shape.ts';
+export { CycleDetection } from './cycle-detection.ts';
+/**
+ * Every rule in the registry. Callers should generally compose subsets from
+ * this rather than importing individual rules — it's the stable surface.
+ *
+ * Order: metadata/identity checks first (cheap, frame the spec), then
+ * structural checks (count, weights), then topology (cycles). Violations
+ * surface in this order so operators see "your schema_version is missing"
+ * before "your routing has a cycle."
+ */
+export declare const allRules: RuleSet;
+/**
+ * Cheap rules safe for per-keystroke Map Builder contexts. Selected by the
+ * `fast` tag. Graph traversal rules (CycleDetection) intentionally absent.
+ */
+export declare const fastRules: RuleSet;
+/**
+ * Rules that run against the spec alone, no live deployment needed. Used by
+ * QA spec-only mode and any CI context without a deployed URL. Selected by
+ * the `spec-only` tag.
+ */
+export declare const specOnlyRules: RuleSet;

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

@@ -0,0 +1,131 @@
+/**
+ * Rule registry — preset RuleSet constants.
+ *
+ * Callers either pick a preset (allRules / fastRules / specOnlyRules) or
+ * filter inline:
+ *
+ *   const myRules = allRules.filter(r => r.tags.includes('fast'))
+ *
+ * Tags are a closed taxonomy (see ../types.ts). To add a rule:
+ *   1. Create rules/<your-rule>.ts exporting a `Rule`.
+ *   2. Add it to `allRules` below.
+ *   3. fastRules / specOnlyRules pick up via tag filter automatically.
+ *
+ * Rules are listed in a stable order — the order callers see violations in
+ * for a multi-rule run. Keep cheap/metadata checks first so they surface
+ * before downstream complaints.
+ */
+import { SchemaVersion } from "./schema-version.js";
+import { SdkVersion } from "./sdk-version.js";
+import { UnknownTopLevelFields } from "./unknown-top-level-fields.js";
+import { FunnelCount } from "./funnel-count.js";
+import { FunnelIdentity } from "./funnel-identity.js";
+import { FunnelHypothesisLength } from "./funnel-hypothesis-length.js";
+import { FunnelWeightSum } from "./funnel-weight-sum.js";
+import { PageCount } from "./page-count.js";
+import { ThankYouRequirement } from "./thank-you-requirement.js";
+import { PageIdUniqueness } from "./page-id-uniqueness.js";
+import { UpsellHasPackages } from "./upsell-has-packages.js";
+import { UpsellRoutingComplete } from "./upsell-routing-complete.js";
+import { RouteTargetResolves } from "./route-target-resolves.js";
+import { RouteFieldIgnoredForPageType } from "./route-field-ignored-for-page-type.js";
+import { CheckoutHasSuccessUrl } from "./checkout-has-success-url.js";
+import { UpsellWithoutCheckout } from "./upsell-without-checkout.js";
+import { DownsellWithoutUpsell } from "./downsell-without-upsell.js";
+import { CampaignMetadata } from "./campaign-metadata.js";
+import { ShippingMethodsPresent } from "./shipping-methods-present.js";
+import { ShippingCountriesShape } from "./shipping-countries-shape.js";
+import { PackagePricingSanity } from "./package-pricing-sanity.js";
+import { OfferRefIntegrity } from "./offer-ref-integrity.js";
+import { ExitIntentValidation } from "./exit-intent-validation.js";
+import { PromoCodeInputValidation } from "./promo-code-input-validation.js";
+import { DesignSourceShape } from "./design-source-shape.js";
+import { AssemblyHintsShape } from "./assembly-hints-shape.js";
+import { PromoCodesShape } from "./promo-codes-shape.js";
+import { VariantLabelsShape } from "./variant-labels-shape.js";
+import { StoreProfileShape } from "./store-profile-shape.js";
+import { AnalyticsContractShape } from "./analytics-contract-shape.js";
+import { CycleDetection } from "./cycle-detection.js";
+export { SchemaVersion, SUPPORTED_SCHEMA_VERSIONS } from "./schema-version.js";
+export { SdkVersion } from "./sdk-version.js";
+export { UnknownTopLevelFields, KNOWN_TOP_LEVEL_FIELDS, KNOWN_CAMPAIGN_FIELDS } from "./unknown-top-level-fields.js";
+export { CampaignMetadata } from "./campaign-metadata.js";
+export { FunnelCount } from "./funnel-count.js";
+export { FunnelIdentity } from "./funnel-identity.js";
+export { FunnelHypothesisLength } from "./funnel-hypothesis-length.js";
+export { FunnelWeightSum } from "./funnel-weight-sum.js";
+export { PageCount } from "./page-count.js";
+export { ThankYouRequirement } from "./thank-you-requirement.js";
+export { PageIdUniqueness } from "./page-id-uniqueness.js";
+export { UpsellHasPackages } from "./upsell-has-packages.js";
+export { UpsellRoutingComplete } from "./upsell-routing-complete.js";
+export { RouteFieldIgnoredForPageType } from "./route-field-ignored-for-page-type.js";
+export { CheckoutHasSuccessUrl } from "./checkout-has-success-url.js";
+export { UpsellWithoutCheckout } from "./upsell-without-checkout.js";
+export { DownsellWithoutUpsell } from "./downsell-without-upsell.js";
+export { PackagePricingSanity } from "./package-pricing-sanity.js";
+export { ShippingMethodsPresent } from "./shipping-methods-present.js";
+export { ShippingCountriesShape } from "./shipping-countries-shape.js";
+export { OfferRefIntegrity } from "./offer-ref-integrity.js";
+export { ExitIntentValidation } from "./exit-intent-validation.js";
+export { PromoCodeInputValidation } from "./promo-code-input-validation.js";
+export { DesignSourceShape } from "./design-source-shape.js";
+export { AssemblyHintsShape } from "./assembly-hints-shape.js";
+export { PromoCodesShape } from "./promo-codes-shape.js";
+export { VariantLabelsShape } from "./variant-labels-shape.js";
+export { StoreProfileShape } from "./store-profile-shape.js";
+export { AnalyticsContractShape } from "./analytics-contract-shape.js";
+export { CycleDetection } from "./cycle-detection.js";
+/**
+ * Every rule in the registry. Callers should generally compose subsets from
+ * this rather than importing individual rules — it's the stable surface.
+ *
+ * Order: metadata/identity checks first (cheap, frame the spec), then
+ * structural checks (count, weights), then topology (cycles). Violations
+ * surface in this order so operators see "your schema_version is missing"
+ * before "your routing has a cycle."
+ */
+export const allRules = [
+    SchemaVersion,
+    SdkVersion,
+    UnknownTopLevelFields,
+    CampaignMetadata,
+    FunnelCount,
+    FunnelIdentity,
+    FunnelHypothesisLength,
+    FunnelWeightSum,
+    PageCount,
+    ThankYouRequirement,
+    PageIdUniqueness,
+    UpsellHasPackages,
+    UpsellRoutingComplete,
+    RouteTargetResolves,
+    RouteFieldIgnoredForPageType,
+    CheckoutHasSuccessUrl,
+    UpsellWithoutCheckout,
+    DownsellWithoutUpsell,
+    PackagePricingSanity,
+    ShippingMethodsPresent,
+    ShippingCountriesShape,
+    OfferRefIntegrity,
+    ExitIntentValidation,
+    PromoCodeInputValidation,
+    DesignSourceShape,
+    AssemblyHintsShape,
+    PromoCodesShape,
+    VariantLabelsShape,
+    StoreProfileShape,
+    AnalyticsContractShape,
+    CycleDetection,
+];
+/**
+ * Cheap rules safe for per-keystroke Map Builder contexts. Selected by the
+ * `fast` tag. Graph traversal rules (CycleDetection) intentionally absent.
+ */
+export const fastRules = allRules.filter((r) => r.tags.includes('fast'));
+/**
+ * Rules that run against the spec alone, no live deployment needed. Used by
+ * QA spec-only mode and any CI context without a deployed URL. Selected by
+ * the `spec-only` tag.
+ */
+export const specOnlyRules = allRules.filter((r) => r.tags.includes('spec-only'));

package/campaign-spec/dist/rules/offer-ref-integrity.d.ts

@@ -0,0 +1,13 @@
+/**
+ * OfferRefIntegrity — page-level `offers[]` entries must reference ref_ids
+ * that exist in the spec's `offers[]` catalog. If an offer ref doesn't
+ * resolve, the runtime can't render the offer and the page silently degrades.
+ *
+ * Warning severity (not error) — preserves legacy classification. The
+ * mismatch usually means the spec is stale relative to the upstream API and
+ * needs a refresh.
+ *
+ * Message text inherited verbatim from the pre-#110 validator at migration time.
+ */
+import type { Rule } from '../types.ts';
+export declare const OfferRefIntegrity: Rule;

package/campaign-spec/dist/rules/offer-ref-integrity.js

@@ -0,0 +1,59 @@
+/**
+ * OfferRefIntegrity — page-level `offers[]` entries must reference ref_ids
+ * that exist in the spec's `offers[]` catalog. If an offer ref doesn't
+ * resolve, the runtime can't render the offer and the page silently degrades.
+ *
+ * Warning severity (not error) — preserves legacy classification. The
+ * mismatch usually means the spec is stale relative to the upstream API and
+ * needs a refresh.
+ *
+ * Message text inherited verbatim from the pre-#110 validator at migration time.
+ */
+function buildRefIdIndex(catalog) {
+    const set = new Set();
+    for (const offer of catalog) {
+        // Catalog offers without a ref_id (e.g. package_ref_id-keyed offers) are
+        // excluded from the index — indexing String(undefined) would let a page
+        // offer that also lacks ref_id "resolve" against "undefined" and turn the
+        // whole rule into a silent pass.
+        if (offer.ref_id === undefined || offer.ref_id === null)
+            continue;
+        set.add(String(offer.ref_id));
+    }
+    return set;
+}
+export const OfferRefIntegrity = {
+    id: 'OfferRefIntegrity',
+    severity: 'warning',
+    tags: ['fast', 'references', 'spec-only'],
+    check(spec) {
+        const catalog = spec.offers ?? [];
+        const refIds = buildRefIdIndex(catalog);
+        const violations = [];
+        spec.funnels.forEach((funnel, funnelIdx) => {
+            const pages = funnel.pages ?? [];
+            pages.forEach((page, pageIdx) => {
+                if (!page.offers || page.offers.length === 0)
+                    return;
+                page.offers.forEach((offer, offerIdx) => {
+                    // Page offers with no ref_id are skipped, not flagged: offer identity
+                    // canonicalization between ref_id and package_ref_id is deliberately
+                    // deferred to a later decision pass, so this rule only judges refs
+                    // that actually exist.
+                    if (offer.ref_id === undefined || offer.ref_id === null)
+                        return;
+                    if (!refIds.has(String(offer.ref_id))) {
+                        violations.push({
+                            ruleId: 'OfferRefIntegrity',
+                            severity: 'warning',
+                            message: `"${page.label}" — Offer ref ${offer.ref_id} not found in campaign offers. Refresh API data to sync.`,
+                            path: `/funnels/${funnelIdx}/pages/${pageIdx}/offers/${offerIdx}/ref_id`,
+                            data: { pageId: page.id, refId: offer.ref_id },
+                        });
+                    }
+                });
+            });
+        });
+        return violations;
+    },
+};

package/campaign-spec/dist/rules/package-pricing-sanity.d.ts

@@ -0,0 +1,12 @@
+/**
+ * PackagePricingSanity — per-package sanity check: a package with price_retail
+ * explicitly set to $0 while price > 0 is almost certainly a data entry error
+ * (the retail and sale prices got swapped, or someone meant to leave retail
+ * unset rather than zero it out).
+ *
+ * Warning severity. Message text inherited verbatim from the pre-#110
+ * validator. Note the parseFloat() coercion — packages sometimes
+ * arrive with string-typed prices from upstream CSV imports.
+ */
+import type { Rule } from '../types.ts';
+export declare const PackagePricingSanity: Rule;

package/campaign-spec/dist/rules/package-pricing-sanity.js

@@ -0,0 +1,42 @@
+/**
+ * PackagePricingSanity — per-package sanity check: a package with price_retail
+ * explicitly set to $0 while price > 0 is almost certainly a data entry error
+ * (the retail and sale prices got swapped, or someone meant to leave retail
+ * unset rather than zero it out).
+ *
+ * Warning severity. Message text inherited verbatim from the pre-#110
+ * validator. Note the parseFloat() coercion — packages sometimes
+ * arrive with string-typed prices from upstream CSV imports.
+ */
+export const PackagePricingSanity = {
+    id: 'PackagePricingSanity',
+    severity: 'warning',
+    tags: ['fast', 'spec-only'],
+    check(spec) {
+        const violations = [];
+        spec.funnels.forEach((funnel, funnelIdx) => {
+            const pages = funnel.pages ?? [];
+            pages.forEach((page, pageIdx) => {
+                if (!page.packages)
+                    return;
+                page.packages.forEach((pkg, pkgIdx) => {
+                    if (pkg.price_retail === undefined)
+                        return;
+                    const retail = parseFloat(String(pkg.price_retail));
+                    const price = parseFloat(String(pkg.price));
+                    if (retail === 0 && price > 0) {
+                        const name = pkg.name || pkg.ref_id;
+                        violations.push({
+                            ruleId: 'PackagePricingSanity',
+                            severity: 'warning',
+                            message: `"${page.label}" — Package "${name}" has retail price $0.00. Verify pricing with offers model.`,
+                            path: `/funnels/${funnelIdx}/pages/${pageIdx}/packages/${pkgIdx}/price_retail`,
+                            data: { pageId: page.id, packageName: name, price, priceRetail: retail },
+                        });
+                    }
+                });
+            });
+        });
+        return violations;
+    },
+};

package/campaign-spec/dist/rules/page-count.d.ts

@@ -0,0 +1,11 @@
+/**
+ * PageCount — requires at least one page somewhere in the spec (aggregated
+ * across all funnels). When this fails, every downstream page-level rule
+ * has nothing to check, so this is the first signal operators see.
+ *
+ * Message wording: "Funnel must have at least 1 page." Inherited verbatim
+ * from the pre-#110 validator. Reads as singular but the check is across
+ * the union of funnels.
+ */
+import type { Rule } from '../types.ts';
+export declare const PageCount: Rule;

package/campaign-spec/dist/rules/page-count.js

@@ -0,0 +1,31 @@
+/**
+ * PageCount — requires at least one page somewhere in the spec (aggregated
+ * across all funnels). When this fails, every downstream page-level rule
+ * has nothing to check, so this is the first signal operators see.
+ *
+ * Message wording: "Funnel must have at least 1 page." Inherited verbatim
+ * from the pre-#110 validator. Reads as singular but the check is across
+ * the union of funnels.
+ */
+export const PageCount = {
+    id: 'PageCount',
+    severity: 'error',
+    tags: ['fast', 'structure', 'spec-only'],
+    check(spec) {
+        let total = 0;
+        for (const funnel of spec.funnels) {
+            total += funnel.pages?.length ?? 0;
+        }
+        if (total > 0)
+            return [];
+        return [
+            {
+                ruleId: 'PageCount',
+                severity: 'error',
+                message: 'Funnel must have at least 1 page.',
+                path: '/funnels',
+                data: { totalPages: 0 },
+            },
+        ];
+    },
+};

package/campaign-spec/dist/rules/page-id-uniqueness.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ */
+import type { Rule } from '../types.ts';
+export declare const PageIdUniqueness: Rule;