@wildo-ai/saas-backend-lib 1.0.1

package/src/databases/services/mongo-aggregation.backend.service.ts

@@ -0,0 +1,762 @@
+/** ──────────────────────────────────────────────────────────────
+ * MongoAggregationCompilerBackendService
+ *
+ * Compiles an AggregationExpression AST into a MongoDB aggregation pipeline.
+ *
+ * Milestone A: $match, $group (basic aggregates), $sort, $limit, $project
+ * Milestone C: Measure filters ($cond), advanced aggregates, $setWindowFields
+ * Milestone D: $lookup joins, HAVING ($match after $group), numeric binning
+ * ────────────────────────────────────────────────────────────── */
+
+import { injectable, inject } from 'inversify';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import type { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import { AggregateFunction, ComparisonOperator, DimensionSortBy, JoinType, SortDirection, WindowFunctionType } from '@wildo-ai/saas-models';
+import type {
+  AggregationExpression,
+  AggregationMeasureNode,
+  AggregationDimensionNode,
+  AggregationJoinNode,
+  AggregationHavingNode,
+  AggregationWindowNode,
+  MongoAggregationPipeline,
+} from '~wildo-backend-lib/databases/models/aggregation.backend.schemas';
+
+/** Window function types that can be executed in-DB via $setWindowFields (MongoDB 5.0+) */
+const IN_DB_WINDOW_FUNCTIONS = new Set<WindowFunctionType>([
+  WindowFunctionType.RUNNING_TOTAL,
+  WindowFunctionType.RUNNING_AVG,
+  WindowFunctionType.RANK,
+  WindowFunctionType.DENSE_RANK,
+  WindowFunctionType.LAG,
+  WindowFunctionType.LEAD,
+]);
+
+@injectable()
+export class MongoAggregationCompilerBackendService {
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,
+  ) {}
+
+  /**
+   * Compile an AggregationExpression into a MongoDB aggregation pipeline.
+   */
+  compile(expression: AggregationExpression): MongoAggregationPipeline {
+    const stages: Record<string, unknown>[] = [];
+
+    // 1. $lookup + $unwind — cross-resource joins (before $match so joined fields are available for filters)
+    for (const join of expression.joins) {
+      const lookupStages = this.buildLookupStages(join);
+      stages.push(...lookupStages);
+    }
+
+    // 2. $match — combined filters (static + auth + context)
+    if (expression.filter && Object.keys(expression.filter).length > 0) {
+      stages.push({ $match: expression.filter });
+    }
+
+    // 3. $group — dimensions (with binning support) + measures
+    const groupId = this.buildGroupId(expression.dimensions, expression.timezone);
+    const groupAccumulators = this.buildGroupAccumulators(expression.measures);
+    stages.push({
+      $group: {
+        _id: groupId,
+        ...groupAccumulators,
+      },
+    });
+
+    // 4. $sort
+    const sortStage = this.buildSortStage(expression);
+    if (sortStage) {
+      stages.push({ $sort: sortStage });
+    }
+
+    // 5. $project — flatten _id fields into top-level refs
+    const projectStage = this.buildProjectStage(expression.dimensions, expression.measures);
+    stages.push({ $project: projectStage });
+
+    // 6. HAVING — $match AFTER $project so measure refs are resolved
+    //    (Advanced aggregates like COUNT_DISTINCT use intermediate field names
+    //    in $group that differ from the final ref; $project normalizes them.)
+    //    HAVING must run BEFORE $limit so that limit applies to the filtered result,
+    //    matching SQL semantics (GROUP BY → HAVING → ORDER BY → LIMIT).
+    if (expression.having.length > 0) {
+      const havingMatch = this.buildHavingStage(expression.having);
+      stages.push({ $match: havingMatch });
+    }
+
+    // 7. $limit — after HAVING to match SQL semantics
+    if (expression.limit != null) {
+      stages.push({ $limit: expression.limit });
+    }
+
+    // 8. $setWindowFields — in-DB window functions (MongoDB 5.0+)
+    const inDbWindows = (expression.windowFunctions || []).filter(
+      wf => IN_DB_WINDOW_FUNCTIONS.has(wf.type),
+    );
+    if (inDbWindows.length > 0) {
+      const windowStages = this.buildSetWindowFieldsStages(inDbWindows, expression.dimensions);
+      stages.push(...windowStages);
+    }
+
+    this.logger.debug(`MongoAggregationCompiler: compiled ${stages.length} stages for ${expression.collection}`);
+
+    return {
+      stages,
+      collection: expression.collection,
+      maxTimeMS: expression.timeoutMs,
+    };
+  }
+
+  /**
+   * Determine which window function types can be executed in-DB.
+   * The rest will be handled by the in-memory WindowFunctionProcessor.
+   */
+  getInDbWindowTypes(): Set<WindowFunctionType> {
+    return IN_DB_WINDOW_FUNCTIONS;
+  }
+
+  // ── $lookup (Cross-Resource Join) Builder ───────────────────
+
+  /**
+   * Build $lookup + $unwind stages for a cross-resource join.
+   *
+   * For LEFT joins, $unwind uses `preserveNullAndEmptyArrays: true`
+   * so documents without a match are retained with null joined fields.
+   * For INNER joins, unmatched documents are removed.
+   *
+   * Joined fields are projected under the alias prefix (e.g., "customer.name").
+   * If the join has an authFilter, it's added as a pipeline match within $lookup.
+   */
+  private buildLookupStages(join: AggregationJoinNode): Record<string, unknown>[] {
+    const stages: Record<string, unknown>[] = [];
+    const asField = `_joined_${join.alias}`;
+
+    // Build the lookup pipeline conditionally
+    // If there's an authFilter or selectFields, use the pipeline form of $lookup
+    const hasAuthFilter = join.authFilter && Object.keys(join.authFilter).length > 0;
+    const hasSelectFields = join.selectFields && join.selectFields.length > 0;
+
+    if (hasAuthFilter || hasSelectFields) {
+      // Pipeline form of $lookup — supports filtering and projection on the joined collection
+      const lookupPipeline: Record<string, unknown>[] = [];
+
+      // Match the FK → PK relationship + auth filter
+      const matchExpr: Record<string, unknown> = {
+        $expr: { $eq: [`$${join.targetPkField}`, '$$_fkValue'] },
+      };
+      if (hasAuthFilter) {
+        lookupPipeline.push({ $match: { $and: [matchExpr, join.authFilter] } });
+      } else {
+        lookupPipeline.push({ $match: matchExpr });
+      }
+
+      // Select only specific fields from joined resource
+      if (hasSelectFields) {
+        const projection: Record<string, 1> = {};
+        for (const field of join.selectFields!) {
+          projection[field] = 1;
+        }
+        lookupPipeline.push({ $project: projection });
+      }
+
+      stages.push({
+        $lookup: {
+          from: join.targetCollection,
+          let: { _fkValue: `$${join.foreignKeyField.physicalPath}` },
+          pipeline: lookupPipeline,
+          as: asField,
+        },
+      });
+    } else {
+      // Simple form of $lookup
+      stages.push({
+        $lookup: {
+          from: join.targetCollection,
+          localField: join.foreignKeyField.physicalPath,
+          foreignField: join.targetPkField,
+          as: asField,
+        },
+      });
+    }
+
+    // $unwind the joined array — for 1:1 or N:1 joins, this unwraps to a single doc
+    stages.push({
+      $unwind: {
+        path: `$${asField}`,
+        preserveNullAndEmptyArrays: join.joinType === JoinType.LEFT,
+      },
+    });
+
+    // Alias projection: rename `_joined_customer.name` → `customer.name`
+    // This is done so dimensions/measures can reference "customer.name" directly.
+    // We use $addFields to project the alias to a top-level nested object.
+    stages.push({
+      $addFields: {
+        [join.alias]: `$${asField}`,
+      },
+    });
+
+    return stages;
+  }
+
+  // ── HAVING Builder ──────────────────────────────────────────
+
+  /**
+   * Build a $match stage for HAVING conditions.
+   * These filter on aggregated measure values after $group.
+   */
+  private buildHavingStage(havingClauses: AggregationHavingNode[]): Record<string, unknown> {
+    const conditions: Record<string, unknown>[] = [];
+
+    for (const clause of havingClauses) {
+      const field = clause.measureRef;
+      let condition: Record<string, unknown>;
+
+      switch (clause.operator) {
+        case ComparisonOperator.EQ:
+          condition = { [field]: { $eq: clause.value } };
+          break;
+        case ComparisonOperator.NE:
+          condition = { [field]: { $ne: clause.value } };
+          break;
+        case ComparisonOperator.GT:
+          condition = { [field]: { $gt: clause.value } };
+          break;
+        case ComparisonOperator.GTE:
+          condition = { [field]: { $gte: clause.value } };
+          break;
+        case ComparisonOperator.LT:
+          condition = { [field]: { $lt: clause.value } };
+          break;
+        case ComparisonOperator.LTE:
+          condition = { [field]: { $lte: clause.value } };
+          break;
+        default:
+          this.logger.warn(`MongoAggregationCompiler: unsupported HAVING operator: ${clause.operator}`);
+          continue;
+      }
+
+      conditions.push(condition);
+    }
+
+    // All HAVING conditions are ANDed together
+    if (conditions.length === 1) {
+      return conditions[0]!;
+    }
+    return { $and: conditions };
+  }
+
+  // ── Numeric Binning Builder ─────────────────────────────────
+
+  /**
+   * Build a binning expression for a numeric dimension in $group._id.
+   *
+   * Two modes:
+   * - Step-based: bin = { step: 10 } → floor(value / 10) * 10  →  e.g., 0, 10, 20, ...
+   * - Boundary-based: bin = { boundaries: [0, 10, 50, 100] } → $switch with ranges
+   */
+  private buildBinExpression(
+    fieldPath: string,
+    bin: { step: number } | { boundaries: number[] },
+  ): Record<string, unknown> {
+    if ('step' in bin) {
+      // Step-based binning: floor(value / step) * step
+      return {
+        $multiply: [
+          { $floor: { $divide: [fieldPath, bin.step] } },
+          bin.step,
+        ],
+      };
+    }
+
+    // Boundary-based binning: $switch with ordered boundaries
+    const boundaries = bin.boundaries;
+
+    if (boundaries.length < 2) {
+      this.logger.warn('MongoAggregationCompiler: boundary binning requires at least 2 boundaries, falling back to direct field');
+      return { $toString: fieldPath };
+    }
+
+    const branches: { case: Record<string, unknown>; then: string }[] = [];
+
+    // First branch: value < first boundary → "< first"
+    branches.push({
+      case: { $lt: [fieldPath, boundaries[0]] },
+      then: `< ${boundaries[0]}`,
+    });
+
+    // Middle branches: each boundary range
+    for (let i = 0; i < boundaries.length - 1; i++) {
+      branches.push({
+        case: {
+          $and: [
+            { $gte: [fieldPath, boundaries[i]] },
+            { $lt: [fieldPath, boundaries[i + 1]] },
+          ],
+        },
+        then: `${boundaries[i]} - ${boundaries[i + 1]}`,
+      });
+    }
+
+    // Last value is the catch-all → ">= last"
+    return {
+      $switch: {
+        branches,
+        default: `>= ${boundaries[boundaries.length - 1]}`,
+      },
+    };
+  }
+
+  // ── Group _id Builder ──────────────────────────────────────
+
+  private buildGroupId(
+    dimensions: AggregationDimensionNode[],
+    timezone: string,
+  ): Record<string, unknown> {
+    const groupId: Record<string, unknown> = {};
+
+    for (const dim of dimensions) {
+      const fieldPath = `$${dim.field.physicalPath}`;
+
+      if (dim.timeGranularity) {
+        // Time dimension: use $dateTrunc for bucketing
+        groupId[dim.ref] = {
+          $dateTrunc: {
+            date: fieldPath,
+            unit: dim.timeGranularity,
+            timezone,
+          },
+        };
+      } else if (dim.bin) {
+        // Numeric binning
+        groupId[dim.ref] = this.buildBinExpression(fieldPath, dim.bin);
+      } else {
+        // Categorical dimension: direct field reference
+        groupId[dim.ref] = fieldPath;
+      }
+    }
+
+    return groupId;
+  }
+
+  // ── Group Accumulators Builder ─────────────────────────────
+
+  private buildGroupAccumulators(measures: AggregationMeasureNode[]): Record<string, unknown> {
+    const accumulators: Record<string, unknown> = {};
+
+    for (const measure of measures) {
+      const fieldPath = measure.field.logicalName === '*' ? 1 : `$${measure.field.physicalPath}`;
+
+      // If measure has a filter, wrap the field with $cond
+      const effectiveField = measure.filter
+        ? this.buildConditionalField(fieldPath, measure.filter)
+        : fieldPath;
+
+      switch (measure.aggregate) {
+        // ── Basic ──
+        case AggregateFunction.COUNT:
+          if (measure.filter) {
+            // Conditional COUNT: sum 1 where filter matches, 0 otherwise
+            accumulators[measure.ref] = {
+              $sum: { $cond: [this.buildFilterExpression(measure.filter), 1, 0] },
+            };
+          } else {
+            accumulators[measure.ref] = { $sum: 1 };
+          }
+          break;
+
+        case AggregateFunction.COUNT_DISTINCT:
+          // COUNT_DISTINCT requires $addToSet + post-$group $project with $size
+          if (measure.filter) {
+            // Use raw fieldPath (not effectiveField which is already $cond-wrapped)
+            accumulators[`_distinct_${measure.ref}`] = {
+              $addToSet: {
+                $cond: [this.buildFilterExpression(measure.filter), fieldPath, '$$REMOVE'],
+              },
+            };
+          } else {
+            accumulators[`_distinct_${measure.ref}`] = { $addToSet: fieldPath };
+          }
+          break;
+
+        case AggregateFunction.SUM:
+          accumulators[measure.ref] = { $sum: effectiveField };
+          break;
+
+        case AggregateFunction.AVG:
+          accumulators[measure.ref] = { $avg: effectiveField };
+          break;
+
+        case AggregateFunction.MIN:
+          accumulators[measure.ref] = { $min: effectiveField };
+          break;
+
+        case AggregateFunction.MAX:
+          accumulators[measure.ref] = { $max: effectiveField };
+          break;
+
+        // ── Statistical ──
+        case AggregateFunction.MEDIAN:
+          // MongoDB 7.0+: $percentile with p: [0.5]
+          // Falls back gracefully — older MongoDB versions will error on this operator
+          accumulators[`_percentile_${measure.ref}`] = {
+            $percentile: {
+              input: effectiveField,
+              p: [0.5],
+              method: 'approximate',
+            },
+          };
+          break;
+
+        case AggregateFunction.PERCENTILE:
+          // MongoDB 7.0+: $percentile
+          accumulators[`_percentile_${measure.ref}`] = {
+            $percentile: {
+              input: effectiveField,
+              p: [(measure.percentileValue ?? 50) / 100],
+              method: 'approximate',
+            },
+          };
+          break;
+
+        case AggregateFunction.STDDEV:
+          accumulators[measure.ref] = { $stdDevPop: effectiveField };
+          break;
+
+        case AggregateFunction.VARIANCE:
+          // MongoDB doesn't have native $variance — compute stddev and square it in $project
+          accumulators[`_stddev_${measure.ref}`] = { $stdDevPop: effectiveField };
+          break;
+
+        // ── Boolean / existence ──
+        case AggregateFunction.ANY_VALUE:
+          accumulators[measure.ref] = { $first: effectiveField };
+          break;
+
+        case AggregateFunction.BOOL_AND:
+          // Collect all boolean values, then check in $project
+          accumulators[`_boolvals_${measure.ref}`] = { $push: effectiveField };
+          break;
+
+        case AggregateFunction.BOOL_OR:
+          // Collect all boolean values, then check in $project
+          accumulators[`_boolvals_${measure.ref}`] = { $push: effectiveField };
+          break;
+
+        // ── Array ──
+        case AggregateFunction.ARRAY_AGG:
+          accumulators[`_array_${measure.ref}`] = { $push: effectiveField };
+          break;
+
+        case AggregateFunction.STRING_AGG:
+          accumulators[`_array_${measure.ref}`] = { $push: effectiveField };
+          break;
+
+        default:
+          this.logger.warn(`MongoAggregationCompiler: unknown aggregate '${measure.aggregate}', defaulting to $sum`);
+          accumulators[measure.ref] = { $sum: effectiveField };
+          break;
+      }
+    }
+
+    return accumulators;
+  }
+
+  // ── Measure-level Filter Helpers ──────────────────────────
+
+  /**
+   * Wrap a field reference with $cond to apply a measure-level filter.
+   * Returns the field value when filter matches, null otherwise.
+   * Used for non-COUNT aggregates (SUM, AVG, etc.) where nulls are ignored.
+   */
+  private buildConditionalField(
+    fieldPath: string | number,
+    filter: Record<string, unknown>,
+  ): Record<string, unknown> {
+    return {
+      $cond: [this.buildFilterExpression(filter), fieldPath, null],
+    };
+  }
+
+  /**
+   * Convert a filter object (MongoDB-style) to a $cond-compatible expression.
+   * Supports simple equality and single-level operator filters.
+   *
+   * Examples:
+   *   { status: 'completed' } → { $eq: ['$status', 'completed'] }
+   *   { amount: { $gte: 100 } } → { $gte: ['$amount', 100] }
+   */
+  private buildFilterExpression(filter: Record<string, unknown>): Record<string, unknown> {
+    const conditions: Record<string, unknown>[] = [];
+
+    for (const [field, value] of Object.entries(filter)) {
+      if (value && typeof value === 'object' && !Array.isArray(value)) {
+        // Operator filter: { $gte: 100, $lt: 200 }
+        for (const [op, opVal] of Object.entries(value as Record<string, unknown>)) {
+          conditions.push({ [op]: [`$${field}`, opVal] });
+        }
+      } else {
+        // Simple equality
+        conditions.push({ $eq: [`$${field}`, value] });
+      }
+    }
+
+    if (conditions.length === 1) return conditions[0];
+    return { $and: conditions };
+  }
+
+  // ── Sort Stage Builder ─────────────────────────────────────
+
+  private buildSortStage(expression: AggregationExpression): Record<string, 1 | -1> | null {
+    // Use explicit orderBy if provided
+    if (expression.orderBy.length > 0) {
+      const sort: Record<string, 1 | -1> = {};
+      for (const ob of expression.orderBy) {
+        // Check if it's a dimension (lives in _id) or measure (top-level)
+        const isDimension = expression.dimensions.some(d => d.ref === ob.ref);
+        const key = isDimension ? `_id.${ob.ref}` : ob.ref;
+        sort[key] = ob.direction === SortDirection.ASC ? 1 : -1;
+      }
+      return sort;
+    }
+
+    // Check per-dimension sort
+    for (const dim of expression.dimensions) {
+      if (dim.sort) {
+        const sort: Record<string, 1 | -1> = {};
+        if (dim.sort.by === DimensionSortBy.MEASURE && dim.sort.measureRef) {
+          sort[dim.sort.measureRef] = dim.sort.direction === SortDirection.ASC ? 1 : -1;
+        } else {
+          sort[`_id.${dim.ref}`] = dim.sort.direction === SortDirection.ASC ? 1 : -1;
+        }
+        return sort;
+      }
+    }
+
+    // Default: sort by first dimension ascending (natural order for time series)
+    if (expression.dimensions.length > 0) {
+      return { [`_id.${expression.dimensions[0].ref}`]: 1 };
+    }
+
+    return null;
+  }
+
+  // ── Project Stage Builder ──────────────────────────────────
+
+  private buildProjectStage(
+    dimensions: AggregationDimensionNode[],
+    measures: AggregationMeasureNode[],
+  ): Record<string, unknown> {
+    const project: Record<string, unknown> = {
+      _id: 0, // Suppress MongoDB _id
+    };
+
+    // Flatten dimensions from _id
+    for (const dim of dimensions) {
+      project[dim.ref] = `$_id.${dim.ref}`;
+    }
+
+    // Measures — handle advanced aggregates that need post-processing in $project
+    for (const measure of measures) {
+      switch (measure.aggregate) {
+        case AggregateFunction.COUNT_DISTINCT:
+          // COUNT_DISTINCT: compute $size of the $addToSet array
+          project[measure.ref] = { $size: `$_distinct_${measure.ref}` };
+          break;
+
+        case AggregateFunction.MEDIAN:
+          // $percentile returns an array, extract first element
+          project[measure.ref] = { $arrayElemAt: [`$_percentile_${measure.ref}`, 0] };
+          break;
+
+        case AggregateFunction.PERCENTILE:
+          project[measure.ref] = { $arrayElemAt: [`$_percentile_${measure.ref}`, 0] };
+          break;
+
+        case AggregateFunction.VARIANCE:
+          // Variance = stddev^2
+          project[measure.ref] = {
+            $pow: [`$_stddev_${measure.ref}`, 2],
+          };
+          break;
+
+        case AggregateFunction.BOOL_AND:
+          // All elements must be truthy — $allElementsTrue expects array arg per MongoDB spec
+          project[measure.ref] = { $allElementsTrue: [`$_boolvals_${measure.ref}`] };
+          break;
+
+        case AggregateFunction.BOOL_OR:
+          // At least one element must be truthy — $anyElementTrue expects array arg per MongoDB spec
+          project[measure.ref] = { $anyElementTrue: [`$_boolvals_${measure.ref}`] };
+          break;
+
+        case AggregateFunction.ARRAY_AGG:
+          if (measure.arrayLimit) {
+            project[measure.ref] = { $slice: [`$_array_${measure.ref}`, measure.arrayLimit] };
+          } else {
+            project[measure.ref] = `$_array_${measure.ref}`;
+          }
+          break;
+
+        case AggregateFunction.STRING_AGG: {
+          // Reduce array of strings into joined string with separator
+          const sep = measure.separator ?? ', ';
+          project[measure.ref] = {
+            $reduce: {
+              input: `$_array_${measure.ref}`,
+              initialValue: '',
+              in: {
+                $cond: [
+                  { $eq: ['$$value', ''] },
+                  { $toString: '$$this' },
+                  { $concat: ['$$value', sep, { $toString: '$$this' }] },
+                ],
+              },
+            },
+          };
+          break;
+        }
+
+        default:
+          // Basic aggregates: already at top level from $group
+          project[measure.ref] = 1;
+          break;
+      }
+    }
+
+    return project;
+  }
+
+  // ── $setWindowFields Builder ────────────────────────────────
+
+  /**
+   * Build one or more $setWindowFields stages for in-DB window functions.
+   *
+   * MongoDB $setWindowFields spec (5.0+):
+   *   { $setWindowFields: { partitionBy, sortBy, output: { field: { operator, window? } } } }
+   *
+   * Key rules:
+   *   - `sortBy` is at the STAGE level (sibling of `output`), not inside `window`
+   *   - `window.documents` defines the frame (e.g., ['unbounded', 'current'])
+   *   - Different (partitionBy, orderBy) combos need SEPARATE stages
+   *   - $rank/$denseRank don't need a `window` frame — they use stage-level sortBy
+   *   - $shift (LAG/LEAD) doesn't need a `window` frame either
+   */
+  private buildSetWindowFieldsStages(
+    windowFunctions: AggregationWindowNode[],
+    dimensions: AggregationDimensionNode[],
+  ): Record<string, unknown>[] {
+    if (windowFunctions.length === 0) return [];
+
+    // Default sort field: first time dimension or first dimension
+    const defaultSortRef = dimensions[0]?.ref;
+
+    // Group window functions by (partitionBy, orderBy) so each group gets its own stage
+    const groups = new Map<string, {
+      partitionBy: string | undefined;
+      sortByRef: string | undefined;
+      functions: AggregationWindowNode[];
+    }>();
+
+    for (const wf of windowFunctions) {
+      const partKey = wf.partitionBy ?? '__none__';
+      const sortKey = wf.orderBy || defaultSortRef || '__none__';
+      const groupKey = `${partKey}|${sortKey}`;
+
+      let group = groups.get(groupKey);
+      if (!group) {
+        group = {
+          partitionBy: wf.partitionBy,
+          sortByRef: wf.orderBy || defaultSortRef,
+          functions: [],
+        };
+        groups.set(groupKey, group);
+      }
+      group.functions.push(wf);
+    }
+
+    // Build one $setWindowFields stage per group
+    const stages: Record<string, unknown>[] = [];
+
+    for (const group of groups.values()) {
+      const output: Record<string, unknown> = {};
+
+      for (const wf of group.functions) {
+        const outputField = this.buildWindowOutputField(wf);
+        if (outputField) {
+          output[wf.ref] = outputField;
+        }
+      }
+
+      if (Object.keys(output).length === 0) continue;
+
+      // Build the stage with sortBy at stage level (not inside window)
+      const stageBody: Record<string, unknown> = { output };
+
+      if (group.partitionBy) {
+        stageBody.partitionBy = `$${group.partitionBy}`;
+      }
+
+      if (group.sortByRef) {
+        stageBody.sortBy = { [group.sortByRef]: 1 };
+      }
+
+      stages.push({ $setWindowFields: stageBody });
+    }
+
+    return stages;
+  }
+
+  /**
+   * Build the output field definition for a single window function.
+   * Returns the value to assign to `output[wf.ref]`.
+   *
+   * Note: `sortBy` is NOT placed here — it's at the stage level.
+   * Only `window.documents` defines the frame for accumulator-based functions.
+   */
+  private buildWindowOutputField(wf: AggregationWindowNode): Record<string, unknown> | null {
+    switch (wf.type) {
+      case WindowFunctionType.RUNNING_TOTAL:
+        return {
+          $sum: `$${wf.sourceRef}`,
+          window: { documents: ['unbounded', 'current'] },
+        };
+
+      case WindowFunctionType.RUNNING_AVG:
+        return {
+          $avg: `$${wf.sourceRef}`,
+          window: { documents: ['unbounded', 'current'] },
+        };
+
+      case WindowFunctionType.RANK:
+        // $rank uses stage-level sortBy, no window frame needed
+        return { $rank: {} };
+
+      case WindowFunctionType.DENSE_RANK:
+        return { $denseRank: {} };
+
+      case WindowFunctionType.LAG:
+        return {
+          $shift: {
+            output: `$${wf.sourceRef}`,
+            by: -1,
+            default: null,
+          },
+        };
+
+      case WindowFunctionType.LEAD:
+        return {
+          $shift: {
+            output: `$${wf.sourceRef}`,
+            by: 1,
+            default: null,
+          },
+        };
+
+      default:
+        this.logger.warn(`MongoAggregationCompiler: window function '${wf.type}' not supported in-DB`);
+        return null;
+    }
+  }
+}