@simtlix/simfinity-js 3.4.1 → 3.5.0

package/AGGREGATION_CHANGES_SUMMARY.md

@@ -55,8 +55,9 @@ const QLAggregationOperation = new GraphQLEnumType({
 
 #### New Functions
 
-##### buildFieldPath(gqltype, fieldPath)
-- Resolves a field path string (e.g., "category" or "country.name") to MongoDB field paths
+##### buildFieldPath(gqltype, fieldPath) (historical, removed)
+- Removed: groupId and fact paths are now resolved by the same validated resolver as filters, must end in a scalar field, and relation lookups use reserved `__sf_lN` aliases.
+- Resolved a field path string (e.g., "category" or "country.name") to MongoDB field paths
 - Handles:
   - Direct scalar fields
   - Embedded object fields

package/README.md

@@ -3,9 +3,11 @@
 MongoDB/Mongoose adapter and compatibility facade for Simfinity. This package generates GraphQL queries, mutations, relationships and models from `GraphQLObjectType` definitions using the shared Simfinity runtime.
 
 ```sh
-npm install @simtlix/simfinity-js graphql@^16.11.0 mongoose@^8.16.2
+npm install @simtlix/simfinity-js graphql@^16.11.0 mongoose@^8.24.2
 ```
 
+`graphql` and `mongoose` are peer dependencies: the facade uses your application's copies, and npm reports an out-of-range version as a peer conflict instead of installing a second copy. The MCP transports (`createMCPServer`, `startStdioMCPServer`, `createHTTPMCPHandler`) need the optional peer `@modelcontextprotocol/sdk@^1.13.0`; install it only when you use them. `generateMCPTools` works without it. The package does not install `graphql-middleware`.
+
 ```javascript
 import mongoose from 'mongoose';
 import * as simfinity from '@simtlix/simfinity-js';
@@ -18,6 +20,10 @@ const schema = simfinity.createSchema();
 
 Use a MongoDB replica set or sharded cluster for transactional mutations. The library requires Node.js >=18.18.0 and GraphQL 16.
 
+Generated single-reference reads can be batched within a request. Models with any `find` or `findOne` pre/post query hook retain individual `findOne` reads, including hooks shared by both operations, to preserve access restrictions and other middleware behavior. See the [relationship contract](https://simtlix.github.io/simfinity.js/guide/relationships.html).
+
+Mongoose 8.24.2 or later within version 8 is required to exclude the update-casting prototype-pollution vulnerability. Existing applications should update Mongoose and their dependency lockfile, then run `npm audit`; upgrading Simfinity does not refresh every transitive dependency already locked by the application.
+
 ## Optional transactional reference integrity
 
 Choose the mode once when creating an adapter; the default remains `'off'`:
@@ -40,6 +46,8 @@ Owned transactions use snapshot reads and majority commits. Supplied sessions ne
 
 The source now lives in `packages/mongodb` in the monorepo. Its public npm name remains `@simtlix/simfinity-js`; existing imports, including paths under `@simtlix/simfinity-js/src/`, retain their layout. Shared helpers, error identities and MCP compatibility exports are preserved. Internal Simfinity dependencies use the same exact release version.
 
+For tooling that locates the package, use `require.resolve('@simtlix/simfinity-js/package.json')` or the package root without a trailing slash. Directory specifiers ending in `/` were not valid ESM imports and are not supported by the export map, including in `require.resolve`; use explicit filenames such as `src/auth/index.js`.
+
 - [MongoDB quick start](https://simtlix.github.io/simfinity.js/guide/getting-started.html)
 - [API reference](https://simtlix.github.io/simfinity.js/reference/api.html)
 - [Database comparison](https://simtlix.github.io/simfinity.js/guide/databases.html)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simtlix/simfinity-js",
-  "version": "3.4.1",
+  "version": "3.5.0",
   "description": "MongoDB/Mongoose adapter and compatibility facade for Simfinity GraphQL APIs",
   "main": "src/index.js",
   "types": "./types/index.d.ts",
@@ -16,21 +16,21 @@
     "directory": "packages/mongodb"
   },
   "peerDependencies": {
+    "@modelcontextprotocol/sdk": "^1.13.0",
     "graphql": "^16.11.0",
-    "mongoose": "^8.16.2"
+    "mongoose": "^8.24.2"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    }
   },
   "config": {
     "owner": "simtlix"
   },
-  "optionalDependencies": {
-    "@modelcontextprotocol/sdk": "^1.13.0",
-    "graphql": "^16.11.0",
-    "graphql-middleware": "^6.1.35",
-    "mongoose": "^8.16.2"
-  },
   "dependencies": {
-    "@simtlix/simfinity-core": "3.4.1",
-    "@simtlix/simfinity-mcp": "3.4.1"
+    "@simtlix/simfinity-core": "3.5.0",
+    "@simtlix/simfinity-mcp": "3.5.0"
   },
   "files": [
     "src",
@@ -39,5 +39,25 @@
     "LICENSE",
     "AGGREGATION_EXAMPLE.md",
     "AGGREGATION_CHANGES_SUMMARY.md"
-  ]
+  ],
+  "keywords": [
+    "simfinity",
+    "graphql",
+    "mongodb",
+    "mongoose",
+    "crud",
+    "nodejs"
+  ],
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./src": "./src/index.js",
+    "./src/auth": "./src/auth/index.js",
+    "./src/*.js": "./src/*.js",
+    "./src/*": "./src/*.js",
+    "./package": "./package.json",
+    "./*": "./*"
+  }
 }

package/src/mongo/adapter.js

@@ -10,6 +10,19 @@ mongoose.set('strictQuery', false);
 
 const withSession = (query, session) => (session ? query.session(session) : query);
 
+// Even a shared hook can branch on `this.op` or the filter shape. Preserve findOne semantics
+// whenever either query operation has hooks instead of inferring equivalence from function identity.
+const hasNoFindHooks = (hooks) => {
+  if (!(hooks?._pres instanceof Map) || !(hooks._posts instanceof Map)) return false;
+  return ['find', 'findOne'].every((operation) => !hooks._pres.get(operation)?.length
+    && !hooks._posts.get(operation)?.length);
+};
+
+// getById reads through `findOne` and getByIds through `find`. Mongoose copies the schema's query
+// hooks to the model when compiling it, so both registries must allow the batched read.
+const batchesFindOne = (Model) => hasNoFindHooks(Model.schema?.s?.hooks)
+  && (Model.Query?.prototype?._queryMiddleware == null || hasNoFindHooks(Model.Query.prototype._queryMiddleware));
+
 export const createMongoAdapter = (options) => {
   const integrity = createMongoIntegrity(options);
   let queries;
@@ -82,6 +95,14 @@ export const createMongoAdapter = (options) => {
       if (plain) query = query.lean();
       return query;
     },
+    getByIds(Model, ids) {
+      integrity.assertReady();
+      // When `find` middleware could return other records, fail before reading, so the runtime
+      // reads each ID once with getById.
+      if (!batchesFindOne(Model)) throw new Error(`${Model.modelName} query middleware requires reads by ID`);
+      // Trusted, so that the `sanitizeFilter` option does not wrap the operator in `$eq`.
+      return Model.find({ _id: mongoose.trusted({ $in: ids }) });
+    },
     prepareUpdate(set, unset) {
       return Object.keys(unset).length > 0 ? { ...set, $unset: unset } : set;
     },

package/src/mongo/integrity.js

@@ -3,6 +3,9 @@ import { describeModels, SimfinityError } from '@simtlix/simfinity-core';
 import { withMongoTransaction } from './transactions.js';
 
 const LOCK_FIELD = '_simfinityReferenceLock';
+// Startup audit bounds: distinct target ids checked per query and ids remembered per target.
+const AUDIT_BATCH_SIZE = 1000;
+const AUDIT_VERIFIED_LIMIT = 100000;
 const transactionOptions = { readConcern: { level: 'snapshot' }, writeConcern: { w: 'majority' } };
 const violation = () => new SimfinityError('Reference constraint violated', 'REFERENCE_CONSTRAINT_VIOLATION', 409);
 const invalid = (message) => new SimfinityError(message, 'INVALID_MONGO_INTEGRITY_CONFIGURATION', 400);
@@ -165,21 +168,40 @@ export const createMongoIntegrity = (options = {}) => {
       await Model.init();
     }
     const session = await connection.startSession();
+    // Distinct target ids awaiting one batched existence query, and ids already
+    // found in this snapshot, per target model.
+    const pending = new Map();
+    const verified = new Map();
+    const verify = async (target) => {
+      const ids = pending.get(target);
+      pending.delete(target);
+      const found = new Set((await models.get(target).collection.find(
+        { _id: { $in: [...ids.values()] } }, { session, projection: { _id: 1 }, batchSize: ids.size + 1 },
+      ).toArray()).map(({ _id }) => _id.toHexString()));
+      for (const key of ids.keys()) if (!found.has(key)) throw violation();
+      if ((verified.get(target)?.size || 0) + ids.size > AUDIT_VERIFIED_LIMIT) verified.delete(target);
+      if (!verified.has(target)) verified.set(target, new Set());
+      for (const key of ids.keys()) verified.get(target).add(key);
+    };
     try {
       session.startTransaction({ readConcern: { level: 'snapshot' }, writeConcern: { w: 'majority' } });
       for (const Model of models.values()) {
-        const cursor = Model.collection.find({}, { session });
+        const projection = { _id: 1, [LOCK_FIELD]: 1 };
+        for (const { path } of outgoing.get(Model)) projection[path.join('.')] = 1;
+        const cursor = Model.collection.find({}, { session, projection });
         try {
           for await (const record of cursor) {
             if (record[LOCK_FIELD] != null && record[LOCK_FIELD]?._bsontype !== 'ObjectId') {
               throw invalid(`Existing ${LOCK_FIELD} data is incompatible with reference integrity`);
             }
             for (const { target, id } of modelReferences(Model, record)) {
-              if (!await models.get(target).collection.findOne({ _id: id }, { session, projection: { _id: 1 } })) {
-                throw violation();
-              }
+              const key = id.toHexString();
+              if (verified.get(target)?.has(key)) continue;
+              if (!pending.has(target)) pending.set(target, new Map());
+              if (pending.get(target).set(key, id).size >= AUDIT_BATCH_SIZE) await verify(target);
             }
           }
+          for (const target of [...pending.keys()]) await verify(target);
         } finally { await cursor.close(); }
       }
       // Read-only startup audit. Mutation attempts use independently owned or supplied sessions.

package/src/mongo/models.js

@@ -24,32 +24,30 @@ const getListItemType = (type) => {
   return unwrapNonNull(listType.ofType);
 };
 
-const isCustomValidatedScalar = (type) => (
-  type instanceof GraphQLScalarType && type.baseScalarType
-);
-
-const matchesScalar = (fieldType, target) => {
-  if (fieldType === target) return true;
-  if (fieldType instanceof GraphQLNonNull && fieldType.ofType === target) return true;
-  if (isCustomValidatedScalar(fieldType) && fieldType.baseScalarType === target) return true;
-  return fieldType instanceof GraphQLNonNull
-    && isCustomValidatedScalar(fieldType.ofType)
-    && fieldType.ofType.baseScalarType === target;
+// Follow validated-scalar chains to their storage scalar; a cyclic chain stops where it repeats.
+export const resolveStorageScalar = (type) => {
+  let base = type;
+  const visited = new Set();
+  while (base instanceof GraphQLScalarType && base.baseScalarType && !visited.has(base)) {
+    visited.add(base);
+    base = base.baseScalarType;
+  }
+  return base;
 };
 
+const matchesScalar = (fieldType, target) => resolveStorageScalar(unwrapNonNull(fieldType)) === target;
+
 const getEffectiveTypeName = (type) => (
-  type instanceof GraphQLScalarType && type.baseScalarType ? type.baseScalarType.name : type.name
+  type instanceof GraphQLScalarType ? resolveStorageScalar(type).name : type.name
 );
 
 const isGraphQLisoDate = (typeName) => (
   typeName === 'DateTime' || typeName === 'Date' || typeName === 'Time'
 );
 
-const listItemMatchesScalar = (listType, target) => {
-  const ofType = getListItemType(listType);
-  return ofType === target
-    || (isCustomValidatedScalar(ofType) && ofType.baseScalarType === target);
-};
+const listItemMatchesScalar = (listType, target) => (
+  resolveStorageScalar(getListItemType(listType)) === target
+);
 
 const withUnique = (fieldEntry, mongoType) => (fieldEntry.extensions && fieldEntry.extensions.unique
   ? { type: mongoType, unique: true }
@@ -154,7 +152,10 @@ export const createMongoModel = (gqlType, onModelCreated, { createCollection = t
     onModelCreated(model);
   }
   if (createCollection) {
-    model.createCollection();
+    // Mongoose already ignores NamespaceExists; report other failures instead of crashing the process.
+    Promise.resolve(model.createCollection()).catch((error) => {
+      console.warn(`Simfinity could not create MongoDB collection ${model.collection.collectionName}: ${error?.message ?? error}`);
+    });
   }
   return model;
 };

package/src/mongo/queries.js

@@ -10,6 +10,8 @@ import mongoose from 'mongoose';
 
 import { SimfinityError, QLOperator, paginationStages } from '@simtlix/simfinity-core';
 
+import { resolveStorageScalar } from './models.js';
+
 const isNonNullOfType = (fieldEntryType, graphQLType) => (
   fieldEntryType instanceof GraphQLNonNull && fieldEntryType.ofType instanceof graphQLType
 );
@@ -47,14 +49,39 @@ const getConnectionStorageName = (childType, declaredFieldName) => {
 };
 
 const getEffectiveTypeName = (type) => (
-  type instanceof GraphQLScalarType && type.baseScalarType ? type.baseScalarType.name : type.name
+  type instanceof GraphQLScalarType ? resolveStorageScalar(type).name : type.name
 );
 
 const isGraphQLisoDate = (typeName) => (
   typeName === 'DateTime' || typeName === 'Date' || typeName === 'Time'
 );
 
+// GraphQL reserves `__` names, so these aliases never replace a stored field.
+const LOOKUP_ALIAS_PREFIX = '__sf_l';
+
 export const createMongoQueries = ({ getModel, getRegistrations }) => {
+// One alias per relation path for each query build, keyed by the build's `included` accumulator.
+const lookupAliases = new WeakMap();
+
+const allocateLookupAlias = (aggregationsIncluded, relationPath) => {
+  let aliases = lookupAliases.get(aggregationsIncluded);
+  if (!aliases) {
+    aliases = new Map();
+    lookupAliases.set(aggregationsIncluded, aliases);
+  }
+  if (!aliases.has(relationPath)) aliases.set(relationPath, `${LOOKUP_ALIAS_PREFIX}${aliases.size}`);
+  return aliases.get(relationPath);
+};
+
+const appendLookups = (aggregateClauses, aggregationsIncluded, lookups) => {
+  for (const [alias, { lookup, unwind }] of Object.entries(lookups)) {
+    if (!Object.hasOwn(aggregationsIncluded, alias)) {
+      aggregateClauses.push(lookup, unwind);
+      aggregationsIncluded[alias] = true;
+    }
+  }
+};
+
 const buildRelationLookup = ({
   collectionName, localField, foreignField, alias,
 }) => ({
@@ -127,7 +154,7 @@ const queryNamedType = (type) => {
 };
 
 // Resolve GraphQL paths and storage paths together; supplied models own ID casting.
-const resolveQueryPath = (gqltype, path) => {
+const resolveQueryPath = (gqltype, path, aggregationsIncluded) => {
   assertValidFilterPath(path);
   const parts = path.split('.');
   let currentType = gqltype;
@@ -153,7 +180,7 @@ const resolveQueryPath = (gqltype, path) => {
         const declaredField = relation.connectionField || part;
         const connField = isList ? getConnectionStorageName(fieldType, declaredField) : declaredField;
         const localLeaf = isList ? '_id' : connField;
-        const alias = mongoPath ? `${mongoPath.replaceAll('.', '_')}_${part}` : part;
+        const alias = allocateLookupAlias(aggregationsIncluded, parts.slice(0, index + 1).join('.'));
         aggregateClauses[alias] = buildRelationLookup({
           collectionName: relatedModel.collection.collectionName,
           localField: mongoPath ? `${mongoPath}.${localLeaf}` : localLeaf,
@@ -209,7 +236,7 @@ const castFilterValue = (value, resolved) => {
       const stored = resolved.storesStateName ? entry.name : entry.value;
       return schemaType ? schemaType.cast(stored) : stored;
     }
-    const parsed = (scalar.baseScalarType || scalar).parseValue(value);
+    const parsed = resolveStorageScalar(scalar).parseValue(value);
     return schemaType ? schemaType.cast(parsed) : parsed;
   } catch {
     throw filterError(`Invalid value for ${resolved.mongoPath}`);
@@ -239,7 +266,7 @@ const buildMatchesClause = (resolved, operator, value) => {
   return { [resolved.mongoPath]: OP_TO_MONGO[op](coerced) };
 };
 
-const buildQueryTerms = async (filterField, qlField, fieldName, gqltype) => {
+const buildQueryTerms = async (filterField, qlField, fieldName, gqltype, aggregationsIncluded) => {
   const aggregateClauses = {};
   const matchesClauses = [];
   if (!qlField) throw filterError(`Unknown filter field: ${fieldName}`, 'INVALID_FILTER_FIELD');
@@ -253,7 +280,7 @@ const buildQueryTerms = async (filterField, qlField, fieldName, gqltype) => {
   for (const term of terms) {
     if (!term || typeof term !== 'object' || Array.isArray(term)) throw filterError(`Invalid term for ${fieldName}`);
     if (isObject) assertValidFilterPath(term.path);
-    const resolved = resolveQueryPath(gqltype, isObject ? `${fieldName}.${term.path}` : fieldName);
+    const resolved = resolveQueryPath(gqltype, isObject ? `${fieldName}.${term.path}` : fieldName, aggregationsIncluded);
     Object.assign(aggregateClauses, resolved.aggregateClauses);
     matchesClauses.push(buildMatchesClause(resolved, term.operator, term.value));
   }
@@ -303,15 +330,10 @@ const buildFilterGroupMatch = async (filterGroup, gqltype, aggregateClauses, agg
         filterInput = { operator: condition.operator, value: condition.value };
       }
 
-      const result = await buildQueryTerms(filterInput, qlField, condition.field, gqltype);
+      const result = await buildQueryTerms(filterInput, qlField, condition.field, gqltype, aggregationsIncluded);
       if (!result) continue;
 
-      for (const [prop, aggregate] of Object.entries(result.aggregateClauses)) {
-        if (!aggregationsIncluded[prop]) {
-          aggregateClauses.push(aggregate.lookup, aggregate.unwind);
-          aggregationsIncluded[prop] = true;
-        }
-      }
+      appendLookups(aggregateClauses, aggregationsIncluded, result.aggregateClauses);
       for (const matchClause of Object.values(result.matchesClauses)) {
         for (const [matchKey, match] of Object.entries(matchClause)) {
           parts.push({ [matchKey]: match });
@@ -357,15 +379,10 @@ const collectFiltersAndLookups = async (input, gqltype, aggregateClauses, aggreg
   for (const [key, filterField] of Object.entries(input)) {
     if (RESERVED_QUERY_KEYS.has(key)) continue;
     const qlField = fields[key];
-    const result = await buildQueryTerms(filterField, qlField, key, gqltype);
+    const result = await buildQueryTerms(filterField, qlField, key, gqltype, aggregationsIncluded);
     if (!result) continue;
 
-    for (const [prop, aggregate] of Object.entries(result.aggregateClauses)) {
-      if (!aggregationsIncluded[prop]) {
-        aggregateClauses.push(aggregate.lookup, aggregate.unwind);
-        aggregationsIncluded[prop] = true;
-      }
-    }
+    appendLookups(aggregateClauses, aggregationsIncluded, result.aggregateClauses);
     for (const matchClause of Object.values(result.matchesClauses)) {
       for (const [matchKey, match] of Object.entries(matchClause)) {
         if (Object.hasOwn(flatMatchConditions, matchKey)) {
@@ -419,13 +436,8 @@ const validateSortTerms = (sort) => {
 const buildSortClause = (sortTerms, gqltype, aggregateClauses, aggregationsIncluded) => {
   const sortExpressions = {};
   for (const sort of sortTerms) {
-    const resolved = resolveQueryPath(gqltype, sort.field);
-    for (const [alias, aggregate] of Object.entries(resolved.aggregateClauses)) {
-      if (!aggregationsIncluded[alias]) {
-        aggregateClauses.push(aggregate.lookup, aggregate.unwind);
-        aggregationsIncluded[alias] = true;
-      }
-    }
+    const resolved = resolveQueryPath(gqltype, sort.field, aggregationsIncluded);
+    appendLookups(aggregateClauses, aggregationsIncluded, resolved.aggregateClauses);
     sortExpressions[resolved.mongoPath] = sort.order === 'ASC' ? 1 : -1;
   }
   return { $sort: sortExpressions };
@@ -450,67 +462,14 @@ const buildQuery = async (input, gqltype, isCount) => {
 
   aggregateClauses.push(...paging);
 
-  return aggregateClauses;
-};
-
-const buildFieldPath = (gqltype, fieldPath) => {
-  assertValidFilterPath(fieldPath);
-  const pathParts = fieldPath.split('.');
-  const lookupPairs = [];
-  let currentPath = '';
-  let currentGQLType = gqltype;
-
-  for (const part of pathParts) {
-    const field = currentGQLType.getFields()[part];
-    if (!field) {
-      throw new Error(`Field ${part} not found in type ${currentGQLType.name}`);
-    }
-
-    const fieldType = unwrapListAndNonNull(field.type);
-    const relation = field.extensions?.relation;
-
-    if (fieldType instanceof GraphQLObjectType && relation && !relation.embedded) {
-      const { collectionName } = getModel(fieldType).collection;
-      const lookupAlias = currentPath ? `${currentPath}_${part}` : part;
-      const inverseList = isListType(field.type);
-      const declaredField = relation.connectionField || part;
-      const connField = inverseList
-        ? getConnectionStorageName(fieldType, declaredField)
-        : declaredField;
-      const localField = inverseList
-        ? (currentPath ? `${currentPath}._id` : '_id')
-        : (currentPath ? `${currentPath}.${connField}` : connField);
-
-      lookupPairs.push(buildRelationLookup({
-        collectionName,
-        localField,
-        foreignField: inverseList ? connField : '_id',
-        alias: lookupAlias,
-      }));
-
-      currentPath = lookupAlias;
-      currentGQLType = fieldType;
-    } else if (fieldType instanceof GraphQLObjectType && relation?.embedded) {
-      currentPath = currentPath ? `${currentPath}.${part}` : part;
-      currentGQLType = fieldType;
-    } else {
-      const leaf = part === 'id' ? '_id' : part;
-      currentPath = currentPath ? `${currentPath}.${leaf}` : leaf;
-    }
-  }
+  // Joined documents only serve $match/$sort; returned rows keep their stored references.
+  const lookupAliasList = Object.keys(aggregationsIncluded);
+  if (lookupAliasList.length > 0) aggregateClauses.push({ $unset: lookupAliasList });
 
-  return { mongoPath: currentPath, lookupPairs };
+  return aggregateClauses;
 };
 
-const appendLookupPairs = (aggregateClauses, aggregationsIncluded, lookupPairs) => {
-  for (const { lookup, unwind } of lookupPairs) {
-    const alias = lookup.$lookup.as;
-    if (!aggregationsIncluded[alias]) {
-      aggregateClauses.push(lookup, unwind);
-      aggregationsIncluded[alias] = true;
-    }
-  }
-};
+const RESERVED_FACT_NAMES = new Set(['__proto__', 'constructor', 'prototype']);
 
 const buildAggregationQuery = async (input, gqltype, aggregationExpression) => {
   const aggregateClauses = [];
@@ -520,21 +479,25 @@ const buildAggregationQuery = async (input, gqltype, aggregationExpression) => {
   const matchStage = await collectFiltersAndLookups(input, gqltype, aggregateClauses, aggregationsIncluded);
   if (matchStage) aggregateClauses.push(matchStage);
 
-  const { groupId, facts } = aggregationExpression;
-  const groupIdPath = buildFieldPath(gqltype, groupId);
-  appendLookupPairs(aggregateClauses, aggregationsIncluded, groupIdPath.lookupPairs);
+  const { groupId, facts } = aggregationExpression ?? {};
+  if (!groupId || !Array.isArray(facts) || facts.length === 0) throw filterError('Aggregation requires a groupId and facts');
+  const groupIdPath = resolveQueryPath(gqltype, groupId, aggregationsIncluded);
+  appendLookups(aggregateClauses, aggregationsIncluded, groupIdPath.aggregateClauses);
 
   const groupStage = { $group: { _id: `$${groupIdPath.mongoPath}` } };
-
-  facts.forEach((fact) => {
-    const factPath = buildFieldPath(gqltype, fact.path);
-    appendLookupPairs(aggregateClauses, aggregationsIncluded, factPath.lookupPairs);
-
-    const builder = AGG_OP_TO_MONGO[fact.operation];
-    if (!builder) {
-      throw new Error(`Unknown aggregation operation: ${fact.operation}`);
+  const factNames = new Set();
+
+  // Positional accumulator names keep a fact named `_id` from replacing the group key.
+  facts.forEach((fact, index) => {
+    if (!Object.hasOwn(AGG_OP_TO_MONGO, fact?.operation)) throw filterError('Invalid aggregate operation');
+    if (typeof fact.factName !== 'string' || !PATH_SEGMENT_RE.test(fact.factName)
+      || RESERVED_FACT_NAMES.has(fact.factName) || factNames.has(fact.factName)) {
+      throw filterError('Invalid or duplicate aggregation fact name');
     }
-    groupStage.$group[fact.factName] = builder(factPath.mongoPath);
+    factNames.add(fact.factName);
+    const factPath = resolveQueryPath(gqltype, fact.path, aggregationsIncluded);
+    appendLookups(aggregateClauses, aggregationsIncluded, factPath.aggregateClauses);
+    groupStage.$group[`fact_${index}`] = AGG_OP_TO_MONGO[fact.operation](factPath.mongoPath);
   });
 
   aggregateClauses.push(groupStage);
@@ -543,17 +506,16 @@ const buildAggregationQuery = async (input, gqltype, aggregationExpression) => {
     $project: {
       _id: 0,
       groupId: '$_id',
-      facts: Object.fromEntries(facts.map((fact) => [fact.factName, `$${fact.factName}`])),
+      facts: Object.fromEntries(facts.map((fact, index) => [fact.factName, `$fact_${index}`])),
     },
   });
 
   const sortTerms = input.sort ? validateSortTerms(input.sort) : null;
   if (sortTerms) {
-    const factNames = facts.map((fact) => fact.factName);
     const sortObject = {};
     sortTerms.forEach((sortTerm) => {
       const field = sortTerm.field || 'groupId';
-      const sortFieldPath = factNames.includes(field) ? `facts.${field}` : 'groupId';
+      const sortFieldPath = factNames.has(field) ? `facts.${field}` : 'groupId';
       sortObject[sortFieldPath] = sortTerm.order === 'ASC' ? 1 : -1;
     });
     aggregateClauses.push({ $sort: sortObject });