@wildo-ai/saas-backend-lib 1.0.1

package/src/databases/services/__tests__/mongo-aggregation-compiler.test.ts

@@ -0,0 +1,918 @@
+/**
+ * Unit Tests for MongoAggregationCompilerBackendService
+ *
+ * Tests MongoDB pipeline compilation from AggregationExpression AST:
+ * - Basic GROUP BY with COUNT, SUM, AVG
+ * - Time dimensions with $dateTrunc and timezone
+ * - Numeric binning (step-based, boundary-based)
+ * - Measure-level filters ($cond)
+ * - Advanced aggregates (COUNT_DISTINCT, MEDIAN, STDDEV, VARIANCE, BOOL_AND/OR, STRING_AGG, ARRAY_AGG)
+ * - $lookup joins (simple and pipeline form)
+ * - HAVING clause placement (after $project, before $limit)
+ * - $setWindowFields for in-DB window functions
+ * - Sort stage (explicit orderBy, dimension sort, default)
+ * - $project stage (flatten _id, handle advanced aggregates)
+ *
+ * @see chart-system-architecture.md Milestone T.1
+ */
+
+import 'reflect-metadata';
+import { MongoAggregationCompilerBackendService } from '~wildo-backend-lib/databases/services/mongo-aggregation.backend.service';
+import {
+  AggregateFunction,
+  TimeGranularity,
+  SortDirection,
+  ComparisonOperator,
+  JoinType,
+  WindowFunctionType,
+} from '@wildo-ai/saas-models';
+import type {
+  AggregationExpression,
+  AggregationFieldRef,
+  AggregationDimensionNode,
+  AggregationMeasureNode,
+  AggregationJoinNode,
+  AggregationHavingNode,
+  AggregationWindowNode,
+} from '~wildo-backend-lib/databases/models/aggregation.backend.schemas';
+import { MockLoggerService } from '~wildo-backend-lib/monitoring/logger/services/__tests__/mock-logger.service';
+
+function createCompiler(): MongoAggregationCompilerBackendService {
+  return new MongoAggregationCompilerBackendService(new MockLoggerService() as any);
+}
+
+// ── Helpers ──────────────────────────────────────────────────
+
+function fieldRef(name: string, opts?: Partial<AggregationFieldRef>): AggregationFieldRef {
+  return {
+    logicalName: name,
+    physicalPath: opts?.physicalPath ?? name,
+    resourceType: opts?.resourceType ?? 'ORDERS',
+    isJoined: opts?.isJoined ?? false,
+    joinAlias: opts?.joinAlias,
+  };
+}
+
+function baseExpression(overrides?: Partial<AggregationExpression>): AggregationExpression {
+  return {
+    collection: 'orders',
+    resourceType: 'ORDERS',
+    dimensions: [],
+    measures: [],
+    joins: [],
+    windowFunctions: [],
+    having: [],
+    orderBy: [],
+    timezone: 'UTC',
+    timeoutMs: 30000,
+    ...overrides,
+  };
+}
+
+function findStage(stages: Record<string, unknown>[], key: string): Record<string, unknown> | undefined {
+  return stages.find(s => key in s);
+}
+
+function findAllStages(stages: Record<string, unknown>[], key: string): Record<string, unknown>[] {
+  return stages.filter(s => key in s);
+}
+
+// =============================================================================
+// TESTS
+// =============================================================================
+
+describe('MongoAggregationCompilerBackendService', () => {
+  let compiler: MongoAggregationCompilerBackendService;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    compiler = createCompiler();
+  });
+
+  // ── Basic GROUP BY ────────────────────────────────────────
+
+  describe('basic GROUP BY', () => {
+    it('should produce $group with COUNT(*)', () => {
+      const result = compiler.compile(baseExpression({
+        dimensions: [
+          { ref: 'status', field: fieldRef('status') } as AggregationDimensionNode,
+        ],
+        measures: [
+          { ref: '*_count', field: fieldRef('*'), aggregate: AggregateFunction.COUNT } as AggregationMeasureNode,
+        ],
+      }));
+
+      const group = findStage(result.stages, '$group');
+      expect(group).toBeDefined();
+
+      const groupBody = group!.$group as Record<string, unknown>;
+      expect((groupBody._id as Record<string, unknown>).status).toBe('$status');
+      expect(groupBody['*_count']).toEqual({ $sum: 1 });
+    });
+
+    it('should produce $group with SUM', () => {
+      const result = compiler.compile(baseExpression({
+        dimensions: [
+          { ref: 'category', field: fieldRef('category') } as AggregationDimensionNode,
+        ],
+        measures: [
+          { ref: 'amount_sum', field: fieldRef('amount'), aggregate: AggregateFunction.SUM } as AggregationMeasureNode,
+        ],
+      }));
+
+      const groupBody = (findStage(result.stages, '$group')!.$group as Record<string, unknown>);
+      expect(groupBody['amount_sum']).toEqual({ $sum: '$amount' });
+    });
+
+    it('should produce $group with AVG, MIN, MAX', () => {
+      const result = compiler.compile(baseExpression({
+        dimensions: [
+          { ref: 'status', field: fieldRef('status') } as AggregationDimensionNode,
+        ],
+        measures: [
+          { ref: 'avg_price', field: fieldRef('price'), aggregate: AggregateFunction.AVG } as AggregationMeasureNode,
+          { ref: 'min_price', field: fieldRef('price'), aggregate: AggregateFunction.MIN } as AggregationMeasureNode,
+          { ref: 'max_price', field: fieldRef('price'), aggregate: AggregateFunction.MAX } as AggregationMeasureNode,
+        ],
+      }));
+
+      const groupBody = (findStage(result.stages, '$group')!.$group as Record<string, unknown>);
+      expect(groupBody['avg_price']).toEqual({ $avg: '$price' });
+      expect(groupBody['min_price']).toEqual({ $min: '$price' });
+      expect(groupBody['max_price']).toEqual({ $max: '$price' });
+    });
+  });
+
+  // ── Time Dimensions ───────────────────────────────────────
+
+  describe('time dimensions', () => {
+    it('should use $dateTrunc for time dimension', () => {
+      const result = compiler.compile(baseExpression({
+        dimensions: [
+          {
+            ref: 'month',
+            field: fieldRef('createdAt'),
+            timeGranularity: TimeGranularity.MONTH,
+          } as AggregationDimensionNode,
+        ],
+        measures: [
+          { ref: 'count', field: fieldRef('*'), aggregate: AggregateFunction.COUNT } as AggregationMeasureNode,
+        ],
+      }));
+
+      const groupBody = (findStage(result.stages, '$group')!.$group as Record<string, unknown>);
+      const groupId = groupBody._id as Record<string, unknown>;
+      const dateTrunc = groupId.month as Record<string, unknown>;
+
+      expect(dateTrunc.$dateTrunc).toBeDefined();
+      const trunc = dateTrunc.$dateTrunc as Record<string, unknown>;
+      expect(trunc.date).toBe('$createdAt');
+      expect(trunc.unit).toBe('month');
+      expect(trunc.timezone).toBe('UTC');
+    });
+
+    it('should respect timezone in $dateTrunc', () => {
+      const result = compiler.compile(baseExpression({
+        dimensions: [
+          {
+            ref: 'day',
+            field: fieldRef('createdAt'),
+            timeGranularity: TimeGranularity.DAY,
+          } as AggregationDimensionNode,
+        ],
+        measures: [
+          { ref: 'count', field: fieldRef('*'), aggregate: AggregateFunction.COUNT } as AggregationMeasureNode,
+        ],
+        timezone: 'America/New_York',
+      }));
+
+      const groupBody = (findStage(result.stages, '$group')!.$group as Record<string, unknown>);
+      const groupId = groupBody._id as Record<string, unknown>;
+      const dateTrunc = groupId.day as Record<string, unknown>;
+      const trunc = dateTrunc.$dateTrunc as Record<string, unknown>;
+
+      expect(trunc.timezone).toBe('America/New_York');
+    });
+  });
+
+  // ── Numeric Binning ───────────────────────────────────────
+
+  describe('numeric binning', () => {
+    it('should produce floor(value/step)*step formula for step-based binning', () => {
+      const result = compiler.compile(baseExpression({
+        dimensions: [
+          {
+            ref: 'age_bin',
+            field: fieldRef('age'),
+            bin: { step: 10 },
+          } as AggregationDimensionNode,
+        ],
+        measures: [
+          { ref: 'count', field: fieldRef('*'), aggregate: AggregateFunction.COUNT } as AggregationMeasureNode,
+        ],
+      }));
+
+      const groupBody = (findStage(result.stages, '$group')!.$group as Record<string, unknown>);
+      const groupId = groupBody._id as Record<string, unknown>;
+      const binExpr = groupId.age_bin as Record<string, unknown>;
+
+      // Verify the exact formula: $multiply: [ $floor: { $divide: [field, 10] }, 10 ]
+      expect(binExpr.$multiply).toBeDefined();
+      const multiplyArgs = binExpr.$multiply as unknown[];
+      expect(multiplyArgs).toHaveLength(2);
+      expect(multiplyArgs[1]).toBe(10); // step value
+
+      const floorExpr = multiplyArgs[0] as Record<string, unknown>;
+      expect(floorExpr.$floor).toBeDefined();
+      const divideExpr = (floorExpr.$floor as Record<string, unknown>).$divide as unknown[];
+      expect(divideExpr[0]).toBe('$age');
+      expect(divideExpr[1]).toBe(10);
+    });
+
+    it('should produce $switch with correct branch labels for boundary-based binning', () => {
+      const result = compiler.compile(baseExpression({
+        dimensions: [
+          {
+            ref: 'price_range',
+            field: fieldRef('price'),
+            bin: { boundaries: [0, 50, 100, 500] },
+          } as AggregationDimensionNode,
+        ],
+        measures: [
+          { ref: 'count', field: fieldRef('*'), aggregate: AggregateFunction.COUNT } as AggregationMeasureNode,
+        ],
+      }));
+
+      const groupBody = (findStage(result.stages, '$group')!.$group as Record<string, unknown>);
+      const groupId = groupBody._id as Record<string, unknown>;
+      const binExpr = groupId.price_range as Record<string, unknown>;
+
+      expect(binExpr.$switch).toBeDefined();
+      const switchExpr = binExpr.$switch as { branches: Array<{ case: unknown; then: string }>; default: string };
+
+      // Verify branch count: "< 0", "0 - 50", "50 - 100", "100 - 500" = 4 branches (ASCII hyphen / >= — see buildBinExpression)
+      expect(switchExpr.branches).toHaveLength(4);
+
+      // First branch: price < 0
+      expect(switchExpr.branches[0].then).toBe('< 0');
+
+      // Middle branches: ranges
+      expect(switchExpr.branches[1].then).toBe('0 - 50');
+      expect(switchExpr.branches[2].then).toBe('50 - 100');
+      expect(switchExpr.branches[3].then).toBe('100 - 500');
+
+      // Default: ">= 500"
+      expect(switchExpr.default).toBe('>= 500');
+    });
+  });
+
+  // ── Measure-level Filters ─────────────────────────────────
+
+  describe('measure-level filters', () => {
+    it('should produce $sum: { $cond: [ {$eq: ["$status","completed"]}, 1, 0 ] } for filtered COUNT', () => {
+      const result = compiler.compile(baseExpression({
+        dimensions: [
+          { ref: 'status', field: fieldRef('status') } as AggregationDimensionNode,
+        ],
+        measures: [
+          {
+            ref: 'completed_count',
+            field: fieldRef('*'),
+            aggregate: AggregateFunction.COUNT,
+            filter: { status: 'completed' },
+          } as AggregationMeasureNode,
+        ],
+      }));
+
+      const groupBody = (findStage(result.stages, '$group')!.$group as Record<string, unknown>);
+      const acc = groupBody['completed_count'] as Record<string, unknown>;
+
+      // Verify: $sum: { $cond: [ filterExpr, 1, 0 ] }
+      const sumArg = acc.$sum as Record<string, unknown>;
+      expect(sumArg.$cond).toBeDefined();
+      const condArgs = sumArg.$cond as unknown[];
+      // condArgs[0] = filter expression ({ $eq: ['$status', 'completed'] })
+      // condArgs[1] = 1 (count this row)
+      // condArgs[2] = 0 (skip this row)
+      expect(condArgs[1]).toBe(1);
+      expect(condArgs[2]).toBe(0);
+
+      // The filter expression checks status == 'completed'
+      const filterExpr = condArgs[0] as Record<string, unknown>;
+      expect(filterExpr.$eq).toEqual(['$status', 'completed']);
+    });
+
+    it('should produce $sum: { $cond: [filterExpr, "$amount", null] } for filtered SUM', () => {
+      const result = compiler.compile(baseExpression({
+        dimensions: [
+          { ref: 'status', field: fieldRef('status') } as AggregationDimensionNode,
+        ],
+        measures: [
+          {
+            ref: 'active_amount',
+            field: fieldRef('amount'),
+            aggregate: AggregateFunction.SUM,
+            filter: { isActive: true },
+          } as AggregationMeasureNode,
+        ],
+      }));
+
+      const groupBody = (findStage(result.stages, '$group')!.$group as Record<string, unknown>);
+      const acc = groupBody['active_amount'] as Record<string, unknown>;
+
+      // Verify: $sum: { $cond: [filterExpr, "$amount", null] }
+      const condExpr = acc.$sum as Record<string, unknown>;
+      expect(condExpr.$cond).toBeDefined();
+      const condArgs = condExpr.$cond as unknown[];
+
+      // condArgs[1] = "$amount" (field value when filter matches)
+      // condArgs[2] = null (ignored by $sum)
+      expect(condArgs[1]).toBe('$amount');
+      expect(condArgs[2]).toBeNull();
+
+      // The filter expression checks isActive == true
+      const filterBody = condArgs[0] as Record<string, unknown>;
+      expect(filterBody.$eq).toEqual(['$isActive', true]);
+    });
+
+    it('should correctly handle multi-key filters (AND)', () => {
+      const result = compiler.compile(baseExpression({
+        dimensions: [
+          { ref: 'cat', field: fieldRef('category') } as AggregationDimensionNode,
+        ],
+        measures: [
+          {
+            ref: 'premium_active',
+            field: fieldRef('amount'),
+            aggregate: AggregateFunction.SUM,
+            filter: { isActive: true, tier: 'premium' },
+          } as AggregationMeasureNode,
+        ],
+      }));
+
+      const groupBody = (findStage(result.stages, '$group')!.$group as Record<string, unknown>);
+      const acc = groupBody['premium_active'] as Record<string, unknown>;
+      const condExpr = acc.$sum as Record<string, unknown>;
+      const condArgs = condExpr.$cond as unknown[];
+      const filterBody = condArgs[0] as Record<string, unknown>;
+
+      // Multi-key filter should produce $and
+      expect(filterBody.$and).toBeDefined();
+      expect((filterBody.$and as unknown[]).length).toBe(2);
+    });
+  });
+
+  // ── Advanced Aggregates ───────────────────────────────────
+
+  describe('advanced aggregates', () => {
+    it('COUNT_DISTINCT should use $addToSet + $size', () => {
+      const result = compiler.compile(baseExpression({
+        dimensions: [
+          { ref: 'status', field: fieldRef('status') } as AggregationDimensionNode,
+        ],
+        measures: [
+          {
+            ref: 'unique_users',
+            field: fieldRef('userId'),
+            aggregate: AggregateFunction.COUNT_DISTINCT,
+          } as AggregationMeasureNode,
+        ],
+      }));
+
+      // $group should have _distinct_unique_users
+      const groupBody = (findStage(result.stages, '$group')!.$group as Record<string, unknown>);
+      expect(groupBody['_distinct_unique_users']).toEqual({ $addToSet: '$userId' });
+
+      // $project should compute $size
+      const projectBody = (findStage(result.stages, '$project')!.$project as Record<string, unknown>);
+      expect(projectBody['unique_users']).toEqual({ $size: '$_distinct_unique_users' });
+    });
+
+    it('STDDEV should use $stdDevPop', () => {
+      const result = compiler.compile(baseExpression({
+        dimensions: [
+          { ref: 'cat', field: fieldRef('category') } as AggregationDimensionNode,
+        ],
+        measures: [
+          { ref: 'sd', field: fieldRef('price'), aggregate: AggregateFunction.STDDEV } as AggregationMeasureNode,
+        ],
+      }));
+
+      const groupBody = (findStage(result.stages, '$group')!.$group as Record<string, unknown>);
+      expect(groupBody['sd']).toEqual({ $stdDevPop: '$price' });
+    });
+
+    it('VARIANCE should use $stdDevPop + $pow in $project', () => {
+      const result = compiler.compile(baseExpression({
+        dimensions: [
+          { ref: 'cat', field: fieldRef('category') } as AggregationDimensionNode,
+        ],
+        measures: [
+          { ref: 'var', field: fieldRef('price'), aggregate: AggregateFunction.VARIANCE } as AggregationMeasureNode,
+        ],
+      }));
+
+      const groupBody = (findStage(result.stages, '$group')!.$group as Record<string, unknown>);
+      expect(groupBody['_stddev_var']).toEqual({ $stdDevPop: '$price' });
+
+      const projectBody = (findStage(result.stages, '$project')!.$project as Record<string, unknown>);
+      expect(projectBody['var']).toEqual({ $pow: ['$_stddev_var', 2] });
+    });
+  });
+
+  // ── $lookup Joins ─────────────────────────────────────────
+
+  describe('$lookup joins', () => {
+    it('should produce simple $lookup + $unwind for basic join', () => {
+      const result = compiler.compile(baseExpression({
+        joins: [
+          {
+            targetCollection: 'customers',
+            targetResourceType: 'CUSTOMERS',
+            foreignKeyField: fieldRef('customerId'),
+            targetPkField: '_id',
+            alias: 'customer',
+            joinType: JoinType.LEFT,
+          } as AggregationJoinNode,
+        ],
+        dimensions: [
+          { ref: 'status', field: fieldRef('status') } as AggregationDimensionNode,
+        ],
+        measures: [
+          { ref: 'count', field: fieldRef('*'), aggregate: AggregateFunction.COUNT } as AggregationMeasureNode,
+        ],
+      }));
+
+      const lookupStage = findStage(result.stages, '$lookup');
+      expect(lookupStage).toBeDefined();
+      const lookup = lookupStage!.$lookup as Record<string, unknown>;
+      expect(lookup.from).toBe('customers');
+      expect(lookup.localField).toBe('customerId');
+      expect(lookup.foreignField).toBe('_id');
+
+      const unwindStage = findStage(result.stages, '$unwind');
+      expect(unwindStage).toBeDefined();
+      const unwind = unwindStage!.$unwind as Record<string, unknown>;
+      expect(unwind.preserveNullAndEmptyArrays).toBe(true); // LEFT join
+    });
+
+    it('should use pipeline form of $lookup with auth filter in pipeline $match', () => {
+      const result = compiler.compile(baseExpression({
+        joins: [
+          {
+            targetCollection: 'customers',
+            targetResourceType: 'CUSTOMERS',
+            foreignKeyField: fieldRef('customerId'),
+            targetPkField: '_id',
+            alias: 'customer',
+            joinType: JoinType.LEFT,
+            authFilter: { organizationId: 'org-123' },
+          } as AggregationJoinNode,
+        ],
+        dimensions: [
+          { ref: 'status', field: fieldRef('status') } as AggregationDimensionNode,
+        ],
+        measures: [
+          { ref: 'count', field: fieldRef('*'), aggregate: AggregateFunction.COUNT } as AggregationMeasureNode,
+        ],
+      }));
+
+      const lookupStage = findStage(result.stages, '$lookup');
+      const lookup = lookupStage!.$lookup as Record<string, unknown>;
+
+      // Pipeline form should have `let` (passing FK value) and `pipeline` (matching + auth)
+      expect(lookup.let).toBeDefined();
+      expect(lookup.pipeline).toBeDefined();
+
+      const pipeline = lookup.pipeline as Record<string, unknown>[];
+      // Pipeline should contain a $match stage with BOTH the PK join condition AND the auth filter
+      const pipelineMatch = pipeline.find(s => '$match' in s);
+      expect(pipelineMatch).toBeDefined();
+      const matchBody = (pipelineMatch as Record<string, unknown>).$match as Record<string, unknown>;
+
+      // Auth filter should be inside the pipeline $match — the organizationId restriction
+      // is part of the $and or directly in the match body
+      const matchStr = JSON.stringify(matchBody);
+      expect(matchStr).toContain('org-123');
+    });
+
+    it('should NOT preserveNullAndEmptyArrays for INNER join', () => {
+      const result = compiler.compile(baseExpression({
+        joins: [
+          {
+            targetCollection: 'customers',
+            targetResourceType: 'CUSTOMERS',
+            foreignKeyField: fieldRef('customerId'),
+            targetPkField: '_id',
+            alias: 'customer',
+            joinType: JoinType.INNER,
+          } as AggregationJoinNode,
+        ],
+        dimensions: [
+          { ref: 'status', field: fieldRef('status') } as AggregationDimensionNode,
+        ],
+        measures: [
+          { ref: 'count', field: fieldRef('*'), aggregate: AggregateFunction.COUNT } as AggregationMeasureNode,
+        ],
+      }));
+
+      const unwindStage = findStage(result.stages, '$unwind');
+      const unwind = unwindStage!.$unwind as Record<string, unknown>;
+      expect(unwind.preserveNullAndEmptyArrays).toBe(false);
+    });
+  });
+
+  // ── HAVING ────────────────────────────────────────────────
+
+  describe('HAVING clause', () => {
+    it('should add $match after $project and before $limit', () => {
+      const result = compiler.compile(baseExpression({
+        dimensions: [
+          { ref: 'status', field: fieldRef('status') } as AggregationDimensionNode,
+        ],
+        measures: [
+          { ref: 'count', field: fieldRef('*'), aggregate: AggregateFunction.COUNT } as AggregationMeasureNode,
+        ],
+        having: [
+          { measureRef: 'count', operator: ComparisonOperator.GT, value: 10 },
+        ],
+        limit: 100,
+      }));
+
+      // Find stages order: $group → $sort → $project → $match(HAVING) → $limit
+      const stageKeys = result.stages.map(s => Object.keys(s)[0]);
+      const projectIdx = stageKeys.indexOf('$project');
+      const limitIdx = stageKeys.lastIndexOf('$limit');
+
+      // There should be a $match AFTER $project
+      const matchStages = findAllStages(result.stages, '$match');
+      expect(matchStages.length).toBeGreaterThanOrEqual(1);
+
+      // The HAVING $match should be between $project and $limit
+      const havingMatchIdx = stageKeys.indexOf('$match', projectIdx);
+      expect(havingMatchIdx).toBeGreaterThan(projectIdx);
+      expect(havingMatchIdx).toBeLessThan(limitIdx);
+    });
+
+    it('should produce correct comparison operators', () => {
+      const result = compiler.compile(baseExpression({
+        dimensions: [
+          { ref: 's', field: fieldRef('status') } as AggregationDimensionNode,
+        ],
+        measures: [
+          { ref: 'c', field: fieldRef('*'), aggregate: AggregateFunction.COUNT } as AggregationMeasureNode,
+        ],
+        having: [
+          { measureRef: 'c', operator: ComparisonOperator.GTE, value: 5 },
+        ],
+      }));
+
+      // Find HAVING $match (the second $match if filters exist)
+      const matchStages = findAllStages(result.stages, '$match');
+      const havingMatch = matchStages[matchStages.length - 1]!.$match as Record<string, unknown>;
+      expect(havingMatch.c).toEqual({ $gte: 5 });
+    });
+  });
+
+  // ── Sort Stage ────────────────────────────────────────────
+
+  describe('sort stage', () => {
+    it('should use explicit orderBy', () => {
+      const result = compiler.compile(baseExpression({
+        dimensions: [
+          { ref: 'status', field: fieldRef('status') } as AggregationDimensionNode,
+        ],
+        measures: [
+          { ref: 'count', field: fieldRef('*'), aggregate: AggregateFunction.COUNT } as AggregationMeasureNode,
+        ],
+        orderBy: [
+          { ref: 'count', direction: SortDirection.DESC },
+        ],
+      }));
+
+      const sortBody = (findStage(result.stages, '$sort')!.$sort as Record<string, number>);
+      expect(sortBody.count).toBe(-1);
+    });
+
+    it('should default sort to first dimension ascending', () => {
+      const result = compiler.compile(baseExpression({
+        dimensions: [
+          { ref: 'month', field: fieldRef('createdAt'), timeGranularity: TimeGranularity.MONTH } as AggregationDimensionNode,
+        ],
+        measures: [
+          { ref: 'count', field: fieldRef('*'), aggregate: AggregateFunction.COUNT } as AggregationMeasureNode,
+        ],
+      }));
+
+      const sortBody = (findStage(result.stages, '$sort')!.$sort as Record<string, number>);
+      expect(sortBody['_id.month']).toBe(1);
+    });
+  });
+
+  // ── $project Stage ────────────────────────────────────────
+
+  describe('$project stage', () => {
+    it('should flatten _id dimensions to top-level fields', () => {
+      const result = compiler.compile(baseExpression({
+        dimensions: [
+          { ref: 'status', field: fieldRef('status') } as AggregationDimensionNode,
+          { ref: 'month', field: fieldRef('createdAt'), timeGranularity: TimeGranularity.MONTH } as AggregationDimensionNode,
+        ],
+        measures: [
+          { ref: 'count', field: fieldRef('*'), aggregate: AggregateFunction.COUNT } as AggregationMeasureNode,
+        ],
+      }));
+
+      const projectBody = (findStage(result.stages, '$project')!.$project as Record<string, unknown>);
+      expect(projectBody._id).toBe(0);
+      expect(projectBody.status).toBe('$_id.status');
+      expect(projectBody.month).toBe('$_id.month');
+      expect(projectBody.count).toBe(1);
+    });
+  });
+
+  // ── $setWindowFields ──────────────────────────────────────
+
+  describe('$setWindowFields', () => {
+    it('should produce RUNNING_TOTAL with $sum and unbounded window frame', () => {
+      const result = compiler.compile(baseExpression({
+        dimensions: [
+          { ref: 'month', field: fieldRef('createdAt'), timeGranularity: TimeGranularity.MONTH } as AggregationDimensionNode,
+        ],
+        measures: [
+          { ref: 'count', field: fieldRef('*'), aggregate: AggregateFunction.COUNT } as AggregationMeasureNode,
+        ],
+        windowFunctions: [
+          { ref: 'cumulative', sourceRef: 'count', type: WindowFunctionType.RUNNING_TOTAL } as AggregationWindowNode,
+        ],
+      }));
+
+      const windowStage = findStage(result.stages, '$setWindowFields');
+      expect(windowStage).toBeDefined();
+
+      const body = windowStage!.$setWindowFields as Record<string, unknown>;
+      const output = body.output as Record<string, unknown>;
+      const cumDef = output.cumulative as Record<string, unknown>;
+
+      // Verify correct operator and window frame
+      expect(cumDef.$sum).toBe('$count');
+      expect(cumDef.window).toEqual({ documents: ['unbounded', 'current'] });
+
+      // sortBy should be at stage level (first dimension), not inside window
+      expect(body.sortBy).toEqual({ month: 1 });
+    });
+
+    it('should produce $rank without window frame (stage-level sortBy)', () => {
+      const result = compiler.compile(baseExpression({
+        dimensions: [
+          { ref: 'status', field: fieldRef('status') } as AggregationDimensionNode,
+        ],
+        measures: [
+          { ref: 'count', field: fieldRef('*'), aggregate: AggregateFunction.COUNT } as AggregationMeasureNode,
+        ],
+        windowFunctions: [
+          { ref: 'rank', sourceRef: 'count', type: WindowFunctionType.RANK } as AggregationWindowNode,
+        ],
+      }));
+
+      const windowStage = findStage(result.stages, '$setWindowFields');
+      const body = windowStage!.$setWindowFields as Record<string, unknown>;
+      const output = body.output as Record<string, unknown>;
+
+      // $rank has no window frame and no $sum — just { $rank: {} }
+      expect(output.rank).toEqual({ $rank: {} });
+    });
+
+    it('should produce $shift for LAG/LEAD with correct offset', () => {
+      const result = compiler.compile(baseExpression({
+        dimensions: [
+          { ref: 'month', field: fieldRef('createdAt'), timeGranularity: TimeGranularity.MONTH } as AggregationDimensionNode,
+        ],
+        measures: [
+          { ref: 'count', field: fieldRef('*'), aggregate: AggregateFunction.COUNT } as AggregationMeasureNode,
+        ],
+        windowFunctions: [
+          { ref: 'prev_count', sourceRef: 'count', type: WindowFunctionType.LAG } as AggregationWindowNode,
+          { ref: 'next_count', sourceRef: 'count', type: WindowFunctionType.LEAD } as AggregationWindowNode,
+        ],
+      }));
+
+      const windowStage = findStage(result.stages, '$setWindowFields');
+      const body = windowStage!.$setWindowFields as Record<string, unknown>;
+      const output = body.output as Record<string, unknown>;
+
+      const lagDef = output.prev_count as Record<string, unknown>;
+      expect(lagDef.$shift).toEqual({ output: '$count', by: -1, default: null });
+
+      const leadDef = output.next_count as Record<string, unknown>;
+      expect(leadDef.$shift).toEqual({ output: '$count', by: 1, default: null });
+    });
+
+    it('should create separate $setWindowFields stages for different partitionBy', () => {
+      const result = compiler.compile(baseExpression({
+        dimensions: [
+          { ref: 'month', field: fieldRef('createdAt'), timeGranularity: TimeGranularity.MONTH } as AggregationDimensionNode,
+        ],
+        measures: [
+          { ref: 'count', field: fieldRef('*'), aggregate: AggregateFunction.COUNT } as AggregationMeasureNode,
+        ],
+        windowFunctions: [
+          { ref: 'global_rank', sourceRef: 'count', type: WindowFunctionType.RANK } as AggregationWindowNode,
+          { ref: 'partitioned_total', sourceRef: 'count', type: WindowFunctionType.RUNNING_TOTAL, partitionBy: 'region' } as AggregationWindowNode,
+        ],
+      }));
+
+      const windowStages = findAllStages(result.stages, '$setWindowFields');
+      // Different (partitionBy, orderBy) combos → separate stages
+      expect(windowStages.length).toBe(2);
+    });
+  });
+
+  // ── Result Metadata ───────────────────────────────────────
+
+  describe('result metadata', () => {
+    it('should set collection and maxTimeMS', () => {
+      const result = compiler.compile(baseExpression({
+        dimensions: [
+          { ref: 'status', field: fieldRef('status') } as AggregationDimensionNode,
+        ],
+        measures: [
+          { ref: 'count', field: fieldRef('*'), aggregate: AggregateFunction.COUNT } as AggregationMeasureNode,
+        ],
+      }));
+
+      expect(result.collection).toBe('orders');
+      expect(result.maxTimeMS).toBe(30000);
+    });
+  });
+
+  // ── $limit ────────────────────────────────────────────────
+
+  describe('$limit', () => {
+    it('should include $limit when specified', () => {
+      const result = compiler.compile(baseExpression({
+        dimensions: [
+          { ref: 'status', field: fieldRef('status') } as AggregationDimensionNode,
+        ],
+        measures: [
+          { ref: 'count', field: fieldRef('*'), aggregate: AggregateFunction.COUNT } as AggregationMeasureNode,
+        ],
+        limit: 50,
+      }));
+
+      const limitStage = findStage(result.stages, '$limit');
+      expect(limitStage).toBeDefined();
+      expect(limitStage!.$limit).toBe(50);
+    });
+
+    it('should handle limit: 0', () => {
+      const result = compiler.compile(baseExpression({
+        dimensions: [
+          { ref: 'status', field: fieldRef('status') } as AggregationDimensionNode,
+        ],
+        measures: [
+          { ref: 'count', field: fieldRef('*'), aggregate: AggregateFunction.COUNT } as AggregationMeasureNode,
+        ],
+        limit: 0,
+      }));
+
+      const limitStage = findStage(result.stages, '$limit');
+      expect(limitStage).toBeDefined();
+      expect(limitStage!.$limit).toBe(0);
+    });
+
+    it('should NOT include $limit when not specified', () => {
+      const result = compiler.compile(baseExpression({
+        dimensions: [
+          { ref: 'status', field: fieldRef('status') } as AggregationDimensionNode,
+        ],
+        measures: [
+          { ref: 'count', field: fieldRef('*'), aggregate: AggregateFunction.COUNT } as AggregationMeasureNode,
+        ],
+      }));
+
+      const limitStage = findStage(result.stages, '$limit');
+      expect(limitStage).toBeUndefined();
+    });
+  });
+
+  // ── $match (static filters) ───────────────────────────────
+
+  describe('$match (static filters)', () => {
+    it('should include $match when filter is provided', () => {
+      const result = compiler.compile(baseExpression({
+        dimensions: [
+          { ref: 'status', field: fieldRef('status') } as AggregationDimensionNode,
+        ],
+        measures: [
+          { ref: 'count', field: fieldRef('*'), aggregate: AggregateFunction.COUNT } as AggregationMeasureNode,
+        ],
+        filter: { isActive: true, organizationId: 'org-123' },
+      }));
+
+      const matchStage = findStage(result.stages, '$match');
+      expect(matchStage).toBeDefined();
+      const match = matchStage!.$match as Record<string, unknown>;
+      expect(match.isActive).toBe(true);
+      expect(match.organizationId).toBe('org-123');
+    });
+  });
+
+  // ── Pipeline Stage Ordering ────────────────────────────────
+  // This is the most critical correctness test: stage order determines query semantics.
+
+  describe('pipeline stage ordering (semantic correctness)', () => {
+    it('should enforce: $lookup → $match → $group → $sort → $project → HAVING $match → $limit → $setWindowFields', () => {
+      const result = compiler.compile(baseExpression({
+        joins: [
+          {
+            targetCollection: 'customers',
+            targetResourceType: 'CUSTOMERS',
+            foreignKeyField: fieldRef('customerId'),
+            targetPkField: '_id',
+            alias: 'customer',
+            joinType: JoinType.LEFT,
+          } as AggregationJoinNode,
+        ],
+        filter: { organizationId: 'org-1' },
+        dimensions: [
+          { ref: 'status', field: fieldRef('status') } as AggregationDimensionNode,
+        ],
+        measures: [
+          { ref: 'count', field: fieldRef('*'), aggregate: AggregateFunction.COUNT } as AggregationMeasureNode,
+        ],
+        having: [
+          { measureRef: 'count', operator: ComparisonOperator.GT, value: 5 },
+        ],
+        limit: 50,
+        windowFunctions: [
+          { ref: 'cum', sourceRef: 'count', type: WindowFunctionType.RUNNING_TOTAL } as AggregationWindowNode,
+        ],
+      }));
+
+      const stageKeys = result.stages.map(s => Object.keys(s)[0]);
+
+      // Find key positions
+      const lookupIdx = stageKeys.indexOf('$lookup');
+      const filterMatchIdx = stageKeys.indexOf('$match'); // filter $match
+      const groupIdx = stageKeys.indexOf('$group');
+      const sortIdx = stageKeys.indexOf('$sort');
+      const projectIdx = stageKeys.indexOf('$project');
+      const limitIdx = stageKeys.indexOf('$limit');
+      const windowIdx = stageKeys.indexOf('$setWindowFields');
+
+      // $lookup BEFORE $match (joins must be available for filters)
+      expect(lookupIdx).toBeLessThan(filterMatchIdx);
+      // $match (filter) BEFORE $group
+      expect(filterMatchIdx).toBeLessThan(groupIdx);
+      // $group BEFORE $sort
+      expect(groupIdx).toBeLessThan(sortIdx);
+      // $sort BEFORE $project
+      expect(sortIdx).toBeLessThan(projectIdx);
+      // $project BEFORE $limit (HAVING $match is between them)
+      expect(projectIdx).toBeLessThan(limitIdx);
+      // $limit BEFORE $setWindowFields (window functions operate on final result)
+      expect(limitIdx).toBeLessThan(windowIdx);
+    });
+
+    it('should place HAVING $match after $project but before $limit (SQL parity: GROUP BY → HAVING → LIMIT)', () => {
+      const result = compiler.compile(baseExpression({
+        dimensions: [
+          { ref: 'status', field: fieldRef('status') } as AggregationDimensionNode,
+        ],
+        measures: [
+          { ref: 'count', field: fieldRef('*'), aggregate: AggregateFunction.COUNT } as AggregationMeasureNode,
+        ],
+        having: [
+          { measureRef: 'count', operator: ComparisonOperator.GT, value: 10 },
+        ],
+        limit: 100,
+      }));
+
+      const stageKeys = result.stages.map(s => Object.keys(s)[0]);
+      const projectIdx = stageKeys.indexOf('$project');
+      const limitIdx = stageKeys.indexOf('$limit');
+
+      // HAVING $match should be the $match that appears AFTER $project
+      const havingIdx = stageKeys.indexOf('$match', projectIdx);
+      expect(havingIdx).toBeGreaterThan(projectIdx);
+      expect(havingIdx).toBeLessThan(limitIdx);
+    });
+  });
+
+  // ── getInDbWindowTypes ────────────────────────────────────
+
+  describe('getInDbWindowTypes', () => {
+    it('should return the set of in-DB window types', () => {
+      const types = compiler.getInDbWindowTypes();
+      expect(types.has(WindowFunctionType.RUNNING_TOTAL)).toBe(true);
+      expect(types.has(WindowFunctionType.RANK)).toBe(true);
+      expect(types.has(WindowFunctionType.DENSE_RANK)).toBe(true);
+      expect(types.has(WindowFunctionType.LAG)).toBe(true);
+      expect(types.has(WindowFunctionType.LEAD)).toBe(true);
+      // In-memory-only types should NOT be in the set
+      expect(types.has(WindowFunctionType.PERCENT_OF_TOTAL)).toBe(false);
+      expect(types.has(WindowFunctionType.MOVING_AVG)).toBe(false);
+    });
+  });
+});