@startsimpli/funnels 0.1.3 → 0.1.5

package/src/core/engine.test.ts

@@ -0,0 +1,1087 @@
+/**
+ * @startsimpli/funnels - FunnelEngine Tests
+ *
+ * Comprehensive test suite for the core funnel execution engine.
+ * Tests generic entity processing with arbitrary field structures.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { FunnelEngine } from './engine';
+import type { Funnel, FunnelStage } from '../types';
+
+// ============================================================================
+// Mock Entities (Generic Objects)
+// ============================================================================
+
+// Mock investor entities
+interface MockInvestor {
+  id: string;
+  name: string;
+  firm: {
+    name: string;
+    stage: string;
+    aum_usd: number;
+  };
+  location: string;
+  tags?: string[];
+  active: boolean;
+}
+
+// Mock recipe entities
+interface MockRecipe {
+  id: string;
+  title: string;
+  cuisine: string;
+  difficulty: string;
+  prep_time_minutes: number;
+  tags?: string[];
+  vegetarian: boolean;
+}
+
+// Generic arbitrary entity
+interface GenericEntity {
+  id: string;
+  [key: string]: any;
+}
+
+// ============================================================================
+// Test Helpers
+// ============================================================================
+
+function createMockInvestors(): MockInvestor[] {
+  return [
+    {
+      id: '1',
+      name: 'Alice Johnson',
+      firm: { name: 'Acme Ventures', stage: 'Series A', aum_usd: 100_000_000 },
+      location: 'San Francisco',
+      active: true,
+    },
+    {
+      id: '2',
+      name: 'Bob Smith',
+      firm: { name: 'Beta Capital', stage: 'Seed', aum_usd: 50_000_000 },
+      location: 'New York',
+      active: true,
+    },
+    {
+      id: '3',
+      name: 'Carol Davis',
+      firm: { name: 'Gamma Fund', stage: 'Series B', aum_usd: 500_000_000 },
+      location: 'Boston',
+      active: false,
+    },
+  ];
+}
+
+function createMockRecipes(): MockRecipe[] {
+  return [
+    {
+      id: '1',
+      title: 'Pasta Carbonara',
+      cuisine: 'Italian',
+      difficulty: 'easy',
+      prep_time_minutes: 30,
+      vegetarian: false,
+    },
+    {
+      id: '2',
+      title: 'Vegetable Curry',
+      cuisine: 'Indian',
+      difficulty: 'medium',
+      prep_time_minutes: 45,
+      vegetarian: true,
+    },
+    {
+      id: '3',
+      title: 'Chocolate Cake',
+      cuisine: 'American',
+      difficulty: 'hard',
+      prep_time_minutes: 90,
+      vegetarian: true,
+    },
+  ];
+}
+
+// ============================================================================
+// Tests: Empty Funnel
+// ============================================================================
+
+describe('FunnelEngine - Empty Funnel', () => {
+  it('should handle funnel with no stages', () => {
+    const engine = new FunnelEngine<MockInvestor>();
+    const entities = createMockInvestors();
+
+    const funnel: Funnel<MockInvestor> = {
+      id: 'funnel-1',
+      name: 'Empty Funnel',
+      status: 'active',
+      input_type: 'any',
+      stages: [],
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    };
+
+    const result = engine.execute(funnel, entities);
+
+    expect(result.total_input).toBe(3);
+    expect(result.total_matched).toBe(3); // No exclusions
+    expect(result.total_excluded).toBe(0);
+    expect(result.matched.length).toBe(3);
+    expect(result.excluded.length).toBe(0);
+    expect(Object.keys(result.stage_stats).length).toBe(0);
+  });
+
+  it('should handle empty entity array', () => {
+    const engine = new FunnelEngine<MockInvestor>();
+
+    const funnel: Funnel<MockInvestor> = {
+      id: 'funnel-1',
+      name: 'Test Funnel',
+      status: 'active',
+      input_type: 'any',
+      stages: [
+        {
+          id: 'stage-1',
+          order: 0,
+          name: 'Filter Stage',
+          filter_logic: 'AND',
+          rules: [],
+          match_action: 'continue',
+          no_match_action: 'exclude',
+        },
+      ],
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    };
+
+    const result = engine.execute(funnel, []);
+
+    expect(result.total_input).toBe(0);
+    expect(result.total_matched).toBe(0);
+    expect(result.total_excluded).toBe(0);
+  });
+});
+
+// ============================================================================
+// Tests: Single Stage
+// ============================================================================
+
+describe('FunnelEngine - Single Stage', () => {
+  it('should process single stage with no rules (always match)', () => {
+    const engine = new FunnelEngine<MockInvestor>();
+    const entities = createMockInvestors();
+
+    const funnel: Funnel<MockInvestor> = {
+      id: 'funnel-1',
+      name: 'Single Stage Funnel',
+      status: 'active',
+      input_type: 'any',
+      stages: [
+        {
+          id: 'stage-1',
+          order: 0,
+          name: 'Pass All',
+          filter_logic: 'AND',
+          rules: [], // No rules = always match
+          match_action: 'continue',
+          no_match_action: 'exclude',
+        },
+      ],
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    };
+
+    const result = engine.execute(funnel, entities);
+
+    expect(result.total_matched).toBe(3);
+    expect(result.stage_stats['stage-1'].input_count).toBe(3);
+    expect(result.stage_stats['stage-1'].matched_count).toBe(3);
+    expect(result.stage_stats['stage-1'].not_matched_count).toBe(0);
+  });
+
+  it('should apply match_action: output (stop processing)', () => {
+    const engine = new FunnelEngine<MockInvestor>();
+    const entities = createMockInvestors();
+
+    const funnel: Funnel<MockInvestor> = {
+      id: 'funnel-1',
+      name: 'Output Stage',
+      status: 'active',
+      input_type: 'any',
+      stages: [
+        {
+          id: 'stage-1',
+          order: 0,
+          name: 'Output All',
+          filter_logic: 'AND',
+          rules: [],
+          match_action: 'output', // Stop processing
+          no_match_action: 'exclude',
+        },
+      ],
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    };
+
+    const result = engine.execute(funnel, entities);
+
+    expect(result.total_matched).toBe(3);
+    expect(result.matched.every(r => r.stage_results?.length === 1)).toBe(true);
+    expect(result.matched.every(r => r.stage_results![0].continued === false)).toBe(true);
+  });
+
+  it('should apply match_action: tag (add tags and exclude)', () => {
+    const engine = new FunnelEngine<MockInvestor>();
+    const entities = createMockInvestors();
+
+    const funnel: Funnel<MockInvestor> = {
+      id: 'funnel-1',
+      name: 'Tag Stage',
+      status: 'active',
+      input_type: 'any',
+      stages: [
+        {
+          id: 'stage-1',
+          order: 0,
+          name: 'Tag All',
+          filter_logic: 'AND',
+          rules: [],
+          match_action: 'tag',
+          no_match_action: 'exclude',
+          match_tags: ['qualified'],
+        },
+      ],
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    };
+
+    const result = engine.execute(funnel, entities);
+
+    // Entities are tagged but excluded (match_action: tag stops processing)
+    expect(result.total_excluded).toBe(3);
+    expect(result.excluded.every(r => r.accumulated_tags.includes('qualified'))).toBe(true);
+  });
+
+  it('should apply match_action: tag_continue (add tags and continue)', () => {
+    const engine = new FunnelEngine<MockInvestor>();
+    const entities = createMockInvestors();
+
+    const funnel: Funnel<MockInvestor> = {
+      id: 'funnel-1',
+      name: 'Tag Continue Stage',
+      status: 'active',
+      input_type: 'any',
+      stages: [
+        {
+          id: 'stage-1',
+          order: 0,
+          name: 'Tag and Continue',
+          filter_logic: 'AND',
+          rules: [],
+          match_action: 'tag_continue',
+          no_match_action: 'exclude',
+          match_tags: ['processed'],
+        },
+      ],
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    };
+
+    const result = engine.execute(funnel, entities);
+
+    expect(result.total_matched).toBe(3);
+    expect(result.matched.every(r => r.accumulated_tags.includes('processed'))).toBe(true);
+    expect(result.matched.every(r => r.stage_results![0].continued === true)).toBe(true);
+  });
+
+  it('should apply no_match_action: exclude', () => {
+    const engine = new FunnelEngine<MockInvestor>();
+    const entities = createMockInvestors();
+
+    const funnel: Funnel<MockInvestor> = {
+      id: 'funnel-1',
+      name: 'Exclude Stage',
+      status: 'active',
+      input_type: 'any',
+      stages: [
+        {
+          id: 'stage-1',
+          order: 0,
+          name: 'Never Match',
+          filter_logic: 'AND',
+          rules: [],
+          match_action: 'continue',
+          no_match_action: 'exclude',
+          custom_evaluator: () => false, // Always false
+        },
+      ],
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    };
+
+    const result = engine.execute(funnel, entities);
+
+    expect(result.total_excluded).toBe(3);
+    expect(result.excluded.every(r => r.excluded_at_stage === 'stage-1')).toBe(true);
+  });
+
+  it('should apply no_match_action: tag_exclude', () => {
+    const engine = new FunnelEngine<MockInvestor>();
+    const entities = createMockInvestors();
+
+    const funnel: Funnel<MockInvestor> = {
+      id: 'funnel-1',
+      name: 'Tag Exclude Stage',
+      status: 'active',
+      input_type: 'any',
+      stages: [
+        {
+          id: 'stage-1',
+          order: 0,
+          name: 'Tag on No Match',
+          filter_logic: 'AND',
+          rules: [],
+          match_action: 'continue',
+          no_match_action: 'tag_exclude',
+          no_match_tags: ['rejected'],
+          custom_evaluator: () => false,
+        },
+      ],
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    };
+
+    const result = engine.execute(funnel, entities);
+
+    expect(result.total_excluded).toBe(3);
+    expect(result.excluded.every(r => r.accumulated_tags.includes('rejected'))).toBe(true);
+  });
+
+  it('should add match_context when rules match', () => {
+    const engine = new FunnelEngine<MockInvestor>();
+    const entities = createMockInvestors();
+
+    const funnel: Funnel<MockInvestor> = {
+      id: 'funnel-1',
+      name: 'Context Stage',
+      status: 'active',
+      input_type: 'any',
+      stages: [
+        {
+          id: 'stage-1',
+          order: 0,
+          name: 'Add Context',
+          filter_logic: 'AND',
+          rules: [],
+          match_action: 'continue',
+          no_match_action: 'exclude',
+          match_context: { tier: 'premium', score: 100 },
+        },
+      ],
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    };
+
+    const result = engine.execute(funnel, entities);
+
+    expect(result.matched.every(r => r.context.tier === 'premium')).toBe(true);
+    expect(result.matched.every(r => r.context.score === 100)).toBe(true);
+  });
+});
+
+// ============================================================================
+// Tests: Multi-Stage
+// ============================================================================
+
+describe('FunnelEngine - Multi-Stage', () => {
+  it('should process multiple stages in order', () => {
+    const engine = new FunnelEngine<MockRecipe>();
+    const entities = createMockRecipes();
+
+    const funnel: Funnel<MockRecipe> = {
+      id: 'funnel-1',
+      name: 'Multi-Stage Funnel',
+      status: 'active',
+      input_type: 'any',
+      stages: [
+        {
+          id: 'stage-1',
+          order: 0,
+          name: 'Stage 1',
+          filter_logic: 'AND',
+          rules: [],
+          match_action: 'continue',
+          no_match_action: 'exclude',
+          match_tags: ['stage-1'],
+        },
+        {
+          id: 'stage-2',
+          order: 1,
+          name: 'Stage 2',
+          filter_logic: 'AND',
+          rules: [],
+          match_action: 'continue',
+          no_match_action: 'exclude',
+          match_tags: ['stage-2'],
+        },
+        {
+          id: 'stage-3',
+          order: 2,
+          name: 'Stage 3',
+          filter_logic: 'AND',
+          rules: [],
+          match_action: 'output',
+          no_match_action: 'exclude',
+          match_tags: ['stage-3'],
+        },
+      ],
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    };
+
+    const result = engine.execute(funnel, entities);
+
+    expect(result.total_matched).toBe(3);
+    expect(result.matched.every(r => r.stage_results?.length === 3)).toBe(true);
+    expect(result.matched.every(r =>
+      r.accumulated_tags.includes('stage-1') &&
+      r.accumulated_tags.includes('stage-2') &&
+      r.accumulated_tags.includes('stage-3')
+    )).toBe(true);
+  });
+
+  it('should exclude entities at intermediate stages', () => {
+    const engine = new FunnelEngine<MockInvestor>();
+    const entities = createMockInvestors();
+
+    const funnel: Funnel<MockInvestor> = {
+      id: 'funnel-1',
+      name: 'Filtering Funnel',
+      status: 'active',
+      input_type: 'any',
+      stages: [
+        {
+          id: 'stage-1',
+          order: 0,
+          name: 'Pass All',
+          filter_logic: 'AND',
+          rules: [],
+          match_action: 'continue',
+          no_match_action: 'exclude',
+        },
+        {
+          id: 'stage-2',
+          order: 1,
+          name: 'Filter Some',
+          filter_logic: 'AND',
+          rules: [],
+          match_action: 'continue',
+          no_match_action: 'exclude',
+          custom_evaluator: (entity) => entity.id === '1' || entity.id === '2',
+        },
+        {
+          id: 'stage-3',
+          order: 2,
+          name: 'Final Filter',
+          filter_logic: 'AND',
+          rules: [],
+          match_action: 'output',
+          no_match_action: 'exclude',
+          custom_evaluator: (entity) => entity.id === '1',
+        },
+      ],
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    };
+
+    const result = engine.execute(funnel, entities);
+
+    expect(result.total_matched).toBe(1);
+    expect(result.matched[0].entity.id).toBe('1');
+    expect(result.total_excluded).toBe(2);
+
+    // Check exclusion stages
+    const excludedAtStage2 = result.excluded.find(r => r.excluded_at_stage === 'stage-2');
+    const excludedAtStage3 = result.excluded.find(r => r.excluded_at_stage === 'stage-3');
+
+    expect(excludedAtStage2?.entity.id).toBe('3');
+    expect(excludedAtStage3?.entity.id).toBe('2');
+  });
+
+  it('should respect stage order even if stages are unsorted', () => {
+    const engine = new FunnelEngine<GenericEntity>();
+    const entities: GenericEntity[] = [
+      { id: '1', value: 10 },
+      { id: '2', value: 20 },
+    ];
+
+    const funnel: Funnel<GenericEntity> = {
+      id: 'funnel-1',
+      name: 'Unsorted Stages',
+      status: 'active',
+      input_type: 'any',
+      stages: [
+        {
+          id: 'stage-3',
+          order: 2,
+          name: 'Third Stage',
+          filter_logic: 'AND',
+          rules: [],
+          match_action: 'continue',
+          no_match_action: 'exclude',
+          match_tags: ['third'],
+        },
+        {
+          id: 'stage-1',
+          order: 0,
+          name: 'First Stage',
+          filter_logic: 'AND',
+          rules: [],
+          match_action: 'continue',
+          no_match_action: 'exclude',
+          match_tags: ['first'],
+        },
+        {
+          id: 'stage-2',
+          order: 1,
+          name: 'Second Stage',
+          filter_logic: 'AND',
+          rules: [],
+          match_action: 'continue',
+          no_match_action: 'exclude',
+          match_tags: ['second'],
+        },
+      ],
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    };
+
+    const result = engine.execute(funnel, entities);
+
+    // Tags should be added in order: first, second, third
+    expect(result.matched[0].accumulated_tags).toEqual(['first', 'second', 'third']);
+  });
+});
+
+// ============================================================================
+// Tests: AND Logic
+// ============================================================================
+
+describe('FunnelEngine - AND Logic', () => {
+  it('should require all rules to match with AND logic', () => {
+    const engine = new FunnelEngine<GenericEntity>();
+    const entities: GenericEntity[] = [
+      { id: '1', value: 10, active: true },
+      { id: '2', value: 20, active: false },
+      { id: '3', value: 30, active: true },
+    ];
+
+    const funnel: Funnel<GenericEntity> = {
+      id: 'funnel-1',
+      name: 'AND Logic Funnel',
+      status: 'active',
+      input_type: 'any',
+      stages: [
+        {
+          id: 'stage-1',
+          order: 0,
+          name: 'AND Stage',
+          filter_logic: 'AND',
+          rules: [
+            { field_path: 'value', operator: 'gte', value: 20 },
+            { field_path: 'active', operator: 'is_true', value: null },
+          ],
+          match_action: 'output',
+          no_match_action: 'exclude',
+        },
+      ],
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    };
+
+    // Mock rule evaluator to use custom_evaluator
+    const stageWithEvaluator: FunnelStage<GenericEntity> = {
+      ...funnel.stages[0],
+      custom_evaluator: (entity) => entity.value >= 20 && entity.active === true,
+    };
+
+    funnel.stages[0] = stageWithEvaluator;
+
+    const result = engine.execute(funnel, entities);
+
+    // Only entity 3 matches both conditions
+    expect(result.total_matched).toBe(1);
+    expect(result.matched[0].entity.id).toBe('3');
+  });
+});
+
+// ============================================================================
+// Tests: OR Logic
+// ============================================================================
+
+describe('FunnelEngine - OR Logic', () => {
+  it('should require at least one rule to match with OR logic', () => {
+    const engine = new FunnelEngine<GenericEntity>();
+    const entities: GenericEntity[] = [
+      { id: '1', value: 10, active: true },
+      { id: '2', value: 20, active: false },
+      { id: '3', value: 5, active: false },
+    ];
+
+    const funnel: Funnel<GenericEntity> = {
+      id: 'funnel-1',
+      name: 'OR Logic Funnel',
+      status: 'active',
+      input_type: 'any',
+      stages: [
+        {
+          id: 'stage-1',
+          order: 0,
+          name: 'OR Stage',
+          filter_logic: 'OR',
+          rules: [
+            { field_path: 'value', operator: 'gte', value: 20 },
+            { field_path: 'active', operator: 'is_true', value: null },
+          ],
+          match_action: 'output',
+          no_match_action: 'exclude',
+        },
+      ],
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    };
+
+    // Mock rule evaluator
+    const stageWithEvaluator: FunnelStage<GenericEntity> = {
+      ...funnel.stages[0],
+      custom_evaluator: (entity) => entity.value >= 20 || entity.active === true,
+    };
+
+    funnel.stages[0] = stageWithEvaluator;
+
+    const result = engine.execute(funnel, entities);
+
+    // Entities 1 and 2 match (1 has active=true, 2 has value>=20)
+    expect(result.total_matched).toBe(2);
+    expect(result.matched.map(r => r.entity.id).sort()).toEqual(['1', '2']);
+  });
+});
+
+// ============================================================================
+// Tests: Tags
+// ============================================================================
+
+describe('FunnelEngine - Tags', () => {
+  it('should accumulate tags across stages', () => {
+    const engine = new FunnelEngine<GenericEntity>();
+    const entities: GenericEntity[] = [{ id: '1', value: 10 }];
+
+    const funnel: Funnel<GenericEntity> = {
+      id: 'funnel-1',
+      name: 'Tag Accumulation',
+      status: 'active',
+      input_type: 'any',
+      stages: [
+        {
+          id: 'stage-1',
+          order: 0,
+          name: 'Stage 1',
+          filter_logic: 'AND',
+          rules: [],
+          match_action: 'continue',
+          no_match_action: 'exclude',
+          match_tags: ['tag-1', 'tag-2'],
+        },
+        {
+          id: 'stage-2',
+          order: 1,
+          name: 'Stage 2',
+          filter_logic: 'AND',
+          rules: [],
+          match_action: 'continue',
+          no_match_action: 'exclude',
+          match_tags: ['tag-3'],
+        },
+      ],
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    };
+
+    const result = engine.execute(funnel, entities);
+
+    expect(result.matched[0].accumulated_tags).toEqual(['tag-1', 'tag-2', 'tag-3']);
+  });
+
+  it('should apply completion tags to matched entities', () => {
+    const engine = new FunnelEngine<GenericEntity>();
+    const entities: GenericEntity[] = [
+      { id: '1', value: 10 },
+      { id: '2', value: 20 },
+    ];
+
+    const funnel: Funnel<GenericEntity> = {
+      id: 'funnel-1',
+      name: 'Completion Tags',
+      status: 'active',
+      input_type: 'any',
+      stages: [
+        {
+          id: 'stage-1',
+          order: 0,
+          name: 'Filter',
+          filter_logic: 'AND',
+          rules: [],
+          match_action: 'output',
+          no_match_action: 'exclude',
+          custom_evaluator: (entity) => entity.value >= 20,
+        },
+      ],
+      completion_tags: ['completed', 'qualified'],
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    };
+
+    const result = engine.execute(funnel, entities);
+
+    expect(result.total_matched).toBe(1);
+    expect(result.matched[0].accumulated_tags).toContain('completed');
+    expect(result.matched[0].accumulated_tags).toContain('qualified');
+  });
+
+  it('should count tagged entities correctly', () => {
+    const engine = new FunnelEngine<GenericEntity>();
+    const entities: GenericEntity[] = [
+      { id: '1', value: 10 },
+      { id: '2', value: 20 },
+      { id: '3', value: 30 },
+    ];
+
+    const funnel: Funnel<GenericEntity> = {
+      id: 'funnel-1',
+      name: 'Tag Counting',
+      status: 'active',
+      input_type: 'any',
+      stages: [
+        {
+          id: 'stage-1',
+          order: 0,
+          name: 'Tag Some',
+          filter_logic: 'AND',
+          rules: [],
+          match_action: 'continue',
+          no_match_action: 'continue',
+          match_tags: ['tagged'],
+          custom_evaluator: (entity) => entity.value >= 20,
+        },
+      ],
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    };
+
+    const result = engine.execute(funnel, entities);
+
+    expect(result.total_tagged).toBe(2); // Entities 2 and 3
+  });
+});
+
+// ============================================================================
+// Tests: Exclusions
+// ============================================================================
+
+describe('FunnelEngine - Exclusions', () => {
+  it('should track which stage excluded each entity', () => {
+    const engine = new FunnelEngine<GenericEntity>();
+    const entities: GenericEntity[] = [
+      { id: '1', value: 10 },
+      { id: '2', value: 20 },
+      { id: '3', value: 30 },
+    ];
+
+    const funnel: Funnel<GenericEntity> = {
+      id: 'funnel-1',
+      name: 'Exclusion Tracking',
+      status: 'active',
+      input_type: 'any',
+      stages: [
+        {
+          id: 'stage-1',
+          order: 0,
+          name: 'Stage 1',
+          filter_logic: 'AND',
+          rules: [],
+          match_action: 'continue',
+          no_match_action: 'exclude',
+          custom_evaluator: (entity) => entity.value >= 20,
+        },
+        {
+          id: 'stage-2',
+          order: 1,
+          name: 'Stage 2',
+          filter_logic: 'AND',
+          rules: [],
+          match_action: 'output',
+          no_match_action: 'exclude',
+          custom_evaluator: (entity) => entity.value >= 30,
+        },
+      ],
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    };
+
+    const result = engine.execute(funnel, entities);
+
+    expect(result.total_matched).toBe(1);
+    expect(result.matched[0].entity.id).toBe('3');
+
+    const excludedAtStage1 = result.excluded.find(r => r.excluded_at_stage === 'stage-1');
+    const excludedAtStage2 = result.excluded.find(r => r.excluded_at_stage === 'stage-2');
+
+    expect(excludedAtStage1?.entity.id).toBe('1');
+    expect(excludedAtStage2?.entity.id).toBe('2');
+  });
+
+  it('should stop processing excluded entities', () => {
+    const engine = new FunnelEngine<GenericEntity>();
+    const entities: GenericEntity[] = [{ id: '1', value: 10 }];
+
+    const funnel: Funnel<GenericEntity> = {
+      id: 'funnel-1',
+      name: 'Stop After Exclusion',
+      status: 'active',
+      input_type: 'any',
+      stages: [
+        {
+          id: 'stage-1',
+          order: 0,
+          name: 'Exclude',
+          filter_logic: 'AND',
+          rules: [],
+          match_action: 'continue',
+          no_match_action: 'exclude',
+          custom_evaluator: () => false,
+        },
+        {
+          id: 'stage-2',
+          order: 1,
+          name: 'Should Not Reach',
+          filter_logic: 'AND',
+          rules: [],
+          match_action: 'output',
+          no_match_action: 'exclude',
+          match_tags: ['unreachable'],
+        },
+      ],
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    };
+
+    const result = engine.execute(funnel, entities);
+
+    expect(result.excluded[0].stage_results?.length).toBe(1); // Only stage-1
+    expect(result.excluded[0].accumulated_tags).not.toContain('unreachable');
+  });
+});
+
+// ============================================================================
+// Tests: Statistics
+// ============================================================================
+
+describe('FunnelEngine - Statistics', () => {
+  it('should track stage statistics correctly', () => {
+    const engine = new FunnelEngine<GenericEntity>();
+    const entities: GenericEntity[] = [
+      { id: '1', value: 10 },
+      { id: '2', value: 20 },
+      { id: '3', value: 30 },
+    ];
+
+    const funnel: Funnel<GenericEntity> = {
+      id: 'funnel-1',
+      name: 'Stats Funnel',
+      status: 'active',
+      input_type: 'any',
+      stages: [
+        {
+          id: 'stage-1',
+          order: 0,
+          name: 'Filter Stage',
+          filter_logic: 'AND',
+          rules: [],
+          match_action: 'continue',
+          no_match_action: 'exclude',
+          match_tags: ['qualified'],
+          custom_evaluator: (entity) => entity.value >= 20,
+        },
+      ],
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    };
+
+    const result = engine.execute(funnel, entities);
+
+    const stats = result.stage_stats['stage-1'];
+
+    expect(stats.input_count).toBe(3);
+    expect(stats.matched_count).toBe(2);
+    expect(stats.not_matched_count).toBe(1);
+    expect(stats.excluded_count).toBe(1);
+    expect(stats.tagged_count).toBe(2);
+    expect(stats.continued_count).toBe(2);
+    expect(stats.duration_ms).toBeGreaterThanOrEqual(0);
+  });
+
+  it('should track execution duration', () => {
+    const engine = new FunnelEngine<GenericEntity>();
+    const entities: GenericEntity[] = [{ id: '1', value: 10 }];
+
+    const funnel: Funnel<GenericEntity> = {
+      id: 'funnel-1',
+      name: 'Duration Test',
+      status: 'active',
+      input_type: 'any',
+      stages: [
+        {
+          id: 'stage-1',
+          order: 0,
+          name: 'Test Stage',
+          filter_logic: 'AND',
+          rules: [],
+          match_action: 'output',
+          no_match_action: 'exclude',
+        },
+      ],
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    };
+
+    const result = engine.execute(funnel, entities);
+
+    expect(result.duration_ms).toBeGreaterThanOrEqual(0);
+    expect(typeof result.duration_ms).toBe('number');
+  });
+});
+
+// ============================================================================
+// Tests: Custom Evaluators
+// ============================================================================
+
+describe('FunnelEngine - Custom Evaluators', () => {
+  it('should use custom_evaluator when provided', () => {
+    const engine = new FunnelEngine<MockRecipe>();
+    const entities = createMockRecipes();
+
+    const funnel: Funnel<MockRecipe> = {
+      id: 'funnel-1',
+      name: 'Custom Eval Funnel',
+      status: 'active',
+      input_type: 'any',
+      stages: [
+        {
+          id: 'stage-1',
+          order: 0,
+          name: 'Quick Recipes',
+          filter_logic: 'AND',
+          rules: [],
+          match_action: 'output',
+          no_match_action: 'exclude',
+          custom_evaluator: (recipe) => recipe.prep_time_minutes <= 45,
+        },
+      ],
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    };
+
+    const result = engine.execute(funnel, entities);
+
+    expect(result.total_matched).toBe(2); // Pasta and Curry
+    expect(result.matched.every(r => r.entity.prep_time_minutes <= 45)).toBe(true);
+  });
+
+  it('should handle custom_evaluator errors gracefully', () => {
+    const engine = new FunnelEngine<GenericEntity>();
+    const entities: GenericEntity[] = [{ id: '1', value: 10 }];
+
+    const funnel: Funnel<GenericEntity> = {
+      id: 'funnel-1',
+      name: 'Error Handling',
+      status: 'active',
+      input_type: 'any',
+      stages: [
+        {
+          id: 'stage-1',
+          order: 0,
+          name: 'Throw Error',
+          filter_logic: 'AND',
+          rules: [],
+          match_action: 'output',
+          no_match_action: 'exclude',
+          custom_evaluator: () => {
+            throw new Error('Evaluator failed');
+          },
+        },
+      ],
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    };
+
+    const result = engine.execute(funnel, entities);
+
+    // Should treat error as no match
+    expect(result.total_matched).toBe(0);
+    expect(result.total_excluded).toBe(1);
+  });
+});
+
+// ============================================================================
+// Tests: Generic Entity Types
+// ============================================================================
+
+describe('FunnelEngine - Generic Entity Types', () => {
+  it('should work with arbitrary entity structures', () => {
+    interface ArbitraryEntity {
+      uuid: string;
+      nested: {
+        deep: {
+          value: number;
+        };
+      };
+      list: string[];
+    }
+
+    const engine = new FunnelEngine<ArbitraryEntity>();
+    const entities: ArbitraryEntity[] = [
+      {
+        uuid: 'abc-123',
+        nested: { deep: { value: 42 } },
+        list: ['a', 'b', 'c'],
+      },
+    ];
+
+    const funnel: Funnel<ArbitraryEntity> = {
+      id: 'funnel-1',
+      name: 'Arbitrary Funnel',
+      status: 'active',
+      input_type: 'any',
+      stages: [
+        {
+          id: 'stage-1',
+          order: 0,
+          name: 'Test Stage',
+          filter_logic: 'AND',
+          rules: [],
+          match_action: 'output',
+          no_match_action: 'exclude',
+        },
+      ],
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    };
+
+    const result = engine.execute(funnel, entities);
+
+    expect(result.total_matched).toBe(1);
+    expect(result.matched[0].entity.uuid).toBe('abc-123');
+    expect(result.matched[0].entity.nested.deep.value).toBe(42);
+  });
+});