Rules Engine

The rules engine is the heart of Presage. It evaluates declarative conditions against the current UserContext and returns the appropriate action.

How Rules Work

Each rule targets a specific adaptation point (identified by adaptationId). When a component resolves that adaptation point, the engine:

1. Filters rules by adaptationId
2. Sorts by priority (highest first)
3. Evaluates each rule’s conditions against the UserContext
4. Returns the action of the first matching rule
5. Returns null if no rule matches (the component falls back to its default variant)

const rule: AdaptationRule = {
  id: 'enterprise-advanced-dashboard',
  adaptationId: 'dashboard',
  priority: 10,
  conditions: {
    all: [
      { field: 'traits.plan', operator: 'eq', value: 'enterprise' },
      { field: 'signals.sessionCount', operator: 'gte', value: 10 },
    ],
  },
  action: { type: 'show', variantId: 'advanced' },
}

All 14 Operators

Equality

Operator	Description	Example
eq	Strict equality (===)	{ field: 'traits.role', operator: 'eq', value: 'admin' }
neq	Strict inequality (!==)	{ field: 'traits.plan', operator: 'neq', value: 'free' }

Numeric Comparison

All numeric operators require both the field value and the comparison value to be numbers.

Operator	Description	Example
gt	Greater than	{ field: 'signals.sessionCount', operator: 'gt', value: 5 }
gte	Greater than or equal	{ field: 'signals.totalEvents', operator: 'gte', value: 100 }
lt	Less than	{ field: 'signals.daysSinceSignup', operator: 'lt', value: 7 }
lte	Less than or equal	{ field: 'traits.companySize', operator: 'lte', value: 50 }

Set Membership

Operator	Description	Example
in	Value is in the provided array	{ field: 'traits.plan', operator: 'in', value: ['pro', 'enterprise'] }
notIn	Value is not in the provided array	{ field: 'traits.role', operator: 'notIn', value: ['viewer', 'guest'] }

String & Array

Operator	Description	Example
contains	String includes substring, or array includes element	{ field: 'traits.company', operator: 'contains', value: 'Corp' }
notContains	Inverse of contains	{ field: 'traits.locale', operator: 'notContains', value: 'zh' }

Existence

Operator	Description	Example
exists	Value is not undefined or null	{ field: 'traits.company', operator: 'exists', value: true }
notExists	Value is undefined or null	{ field: 'traits.signupDate', operator: 'notExists', value: true }

Range

Operator	Description	Example
between	Number is within [min, max] (inclusive)	{ field: 'signals.sessionCount', operator: 'between', value: [5, 20] }

Pattern Matching

Operator	Description	Example
matches	String matches a regular expression	{ field: 'traits.company', operator: 'matches', value: '^Acme.*' }

Boolean Logic

all — AND

Every condition in the array must match:

conditions: {
  all: [
    { field: 'traits.role', operator: 'eq', value: 'admin' },
    { field: 'traits.plan', operator: 'eq', value: 'enterprise' },
    { field: 'signals.sessionCount', operator: 'gte', value: 5 },
  ],
}

any — OR

At least one condition must match:

conditions: {
  any: [
    { field: 'maturity', operator: 'eq', value: 'new' },
    { field: 'maturity', operator: 'eq', value: 'onboarding' },
  ],
}

not — Negation

Inverts the result of a condition or group:

conditions: {
  not: { field: 'traits.plan', operator: 'eq', value: 'free' },
}

Nested Conditions

Groups can be nested to express complex logic:

// (admin AND enterprise) OR (power user with 50+ sessions)
conditions: {
  any: [
    {
      all: [
        { field: 'traits.role', operator: 'eq', value: 'admin' },
        { field: 'traits.plan', operator: 'eq', value: 'enterprise' },
      ],
    },
    {
      all: [
        { field: 'maturity', operator: 'eq', value: 'power' },
        { field: 'signals.sessionCount', operator: 'gte', value: 50 },
      ],
    },
  ],
}

Priority Ordering

Rules are evaluated from highest priority to lowest. The first match wins.

const rules = [
  {
    id: 'vip-override',
    adaptationId: 'dashboard',
    priority: 100,        // Evaluated first
    conditions: { all: [{ field: 'traits.role', operator: 'eq', value: 'vip' }] },
    action: { type: 'show', variantId: 'vip-dashboard' },
  },
  {
    id: 'enterprise-dashboard',
    adaptationId: 'dashboard',
    priority: 50,         // Evaluated second
    conditions: { all: [{ field: 'traits.plan', operator: 'eq', value: 'enterprise' }] },
    action: { type: 'show', variantId: 'advanced' },
  },
  {
    id: 'default-dashboard',
    adaptationId: 'dashboard',
    priority: 1,          // Catch-all
    conditions: {},       // Empty group matches everything
    action: { type: 'show', variantId: 'standard' },
  },
]

Tip

Use a catch-all rule with low priority and empty conditions as an explicit fallback. This makes the intent clearer than relying on defaultVariant.

Field Paths

Fields use dot-notation to access nested values in the UserContext:

Path	Resolves to
maturity	context.maturity (a string)
traits.role	context.traits.role
traits.companySize	context.traits.companySize
signals.sessionCount	context.signals.sessionCount
signals.featureUsage.export	context.signals.featureUsage.export
signals.clickMap.nav-settings	context.signals.clickMap['nav-settings']

Action Types

show

Selects a specific variant to render:

action: { type: 'show', variantId: 'guided-tour' }

hide

Hides the adaptation point entirely:

action: { type: 'hide' }

reorder

Reorders items (used with AdaptiveNav):

action: { type: 'reorder', order: ['analytics', 'settings', 'home'] }

modify

Passes arbitrary props to the matched component:

action: { type: 'modify', props: { showBetaBadge: true, maxItems: 10 } }

Best Practices

1. Name rules descriptively — new-user-guided-tour is clearer than rule-1
2. Use priority gaps — Leave room between priorities (10, 20, 30) so you can insert rules later without renumbering
3. Keep conditions shallow — Deeply nested boolean trees are hard to debug; prefer flatter structures
4. Test rules in isolation — The RulesEngine class can be instantiated directly for unit testing
5. Prefer in over multiple eq — { operator: 'in', value: ['pro', 'enterprise'] } is cleaner than two any conditions