@simtlix/simfinity-js 3.13.0 → 3.14.0

package/AGGREGATION_EXAMPLE.md

@@ -510,6 +510,8 @@ query {
 }
 ```
 
+In Example 9, `episodes` is in J because `totalRevenue` crosses it. Its join preserves one row per episode, including one null row when none exists, so `seriesCount` counts those rows rather than distinct series. A collection used only by a filter becomes an `ANY` frame and does not multiply facts; beyond a joined prefix it tests the joined alias through an anchor. Explicit `ANY`/`ALL`/`NONE` and relation-filter `quantifier` always stay frames. See [aggregate collection semantics](../../docs/guide/queries.md#aggregate-records).
+
 ## Field Path Resolution
 
 The `groupId` and `path` parameters support:
@@ -528,7 +530,7 @@ The `groupId` and `path` parameters support:
 The aggregation queries are translated to MongoDB aggregation pipelines:
 
 1. **$lookup**: Used for non-embedded related entities
-2. **$unwind**: Used to flatten joined collections
+2. **$unwind**: Expands collection prefixes used by `groupId` or facts (J), preserving their joined-row cardinality; filter-only collection frames use correlated `$lookup` existence probes without unwinding root rows
 3. **$match**: Applied for filtering (before grouping)
 4. **$group**: Groups by the specified field with aggregation operations
 5. **$project**: Formats the final output with groupId and facts fields

package/README.md

@@ -42,6 +42,10 @@ Text filters compile to escaped regular expressions, so a value never becomes re
 
 The adapter also declares `queryFeatures.referenceEmptiness`, so these operators cross single references and end at references and collections, such as `director IS_EMPTY`, `director.name IS_EMPTY` or `seasons IS_EMPTY`, and an embedded object with a reference or collection member follows the member rule. A crossing joins the target with `$lookup` and `$unwind`, and the target's `id` right after it is its record identity, which is empty exactly when the reference is. A reference or collection is a frame: one `$lookup` that keeps at most one record id, so it never repeats a document, matched with `"alias.0": { $exists: false }` and its `$nor`; a collection frame reads the child's connection field and also tests its local key for null, because `$lookup` matches a missing local key with every child whose connection field is null. The joins and frames run before the `$match`, so they also filter counts, aggregates and batched collection reads, and they probe the `_id` index or the index on the connection field, which generated models create and a supplied model needs to declare. A client's condition reads each target through its `find` scope, inside the `$lookup` pipeline, so a record the scope hides reads as missing, also on the way to a later hop. Conditions that middleware and scopes add, and `buildQuery()` called directly, read stored data, so a dangling reference, to a record that no longer exists, is empty. A related type without a model fails with `INVALID_FILTER_PATH` (400), as for the other operators, and supplied models on another database or connection and discriminator targets are not supported, as for every relation path. A collection inside an embedded type, which only a supplied model can declare, is read through the embedded object's `_id`, as relation paths read it. The [query scope guide](https://simtlix.github.io/simfinity.js/guide/query-scope.html) describes client and trusted conditions, and the [middleware guide](https://simtlix.github.io/simfinity.js/guide/middleware.html) how to edit client filters without detaching them.
 
+The adapter declares `queryFeatures.quantifiers: true`. Ordinary filter paths through collections compile as correlated `ANY` frames: `reviews.rating GTE 4` keeps each parent once, so pagination counts roots and filters no longer multiply aggregate rows. Conditions in the same group that share a collection prefix must match the same child; separate groups have independent frames. Explicit `ANY`, `ALL` and `NONE` groups and `quantifier` field filters accept paths relative to the target element, including nested frames and references. `ALL` holds when every visible element matches and is true for an empty set; `ALL` without conditions is always true, including inside `OR`. Client target `find` scopes run inside each frame before its conditions, and `ALL` negates only the conditions; trusted conditions from middleware, scopes and direct `buildQuery()` calls read stored data. A reference inside a client frame reads its target through the scoped join in that sub-pipeline.
+
+A quantified frame uses one `$lookup` with the child scope, inner joins and the condition, followed by `$limit: 1` and `$project: { _id: 1 }`, tested by the presence or absence of `"__sf_qN.0"`. Collection frames correlated through a reference or embedded `_id` start with a non-null check on the child's connection field; legacy aggregate collection joins whose local key is not the root `_id` (a collection reached through a reference or an embedded object) use the same guard, avoiding orphan matches through missing parents. Root-anchored aggregate collection joins keep their form. Reference frames need no guard. `groupId` and fact paths preserve their collection joins and row cardinality, while other aggregate filters use frames anchored on the relevant joined row. Sort paths through a collection reject with `INVALID_FILTER_PATH` (400), also for counted pages; sorts through references remain available. Existing own-field and reference predicates, embedded-list predicates and 2b emptiness forms retain their pipelines. Generated and batched collection reads use the same frame pipelines unchanged inside `$unionWith`. These concise lookups require MongoDB 5.0 or later; see the [queries guide](https://simtlix.github.io/simfinity.js/guide/queries.html) for correlation, scopes, depth and compatibility rules.
+
 The facade registers generated models on your application's default Mongoose instance and does not change global Mongoose options such as `strictQuery`. Supplied models may use another connection, such as one from `mongoose.createConnection()`: generated mutations and `saveObject()` use the model's connection, and, in the default `referentialIntegrity: 'off'` mode, custom mutations use the default connection unless it is unused, never opened and without compiled models, also on its `useDb()` descendants, and the registered models share one MongoDB client; with transactional reference integrity they use the first protected model's connection. Named views need no session: they run the generated list path. Custom queries registered with `registerCustomQuery()` receive no session; a callback that needs a transaction opens it with the `transaction()` of the Mongoose connection whose models it reads. `createMongoAdapter().castId` accepts only an ObjectId or its 24-character hexadecimal string and throws `NOT_VALID_ID` (400) otherwise; create new identifiers with `new mongoose.Types.ObjectId()`. Owned transactions retry transient failures after a short random delay, and a write conflict that outlasts the retries fails with `TRANSACTION_RETRY_EXCEEDED` (409).
 
 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simtlix/simfinity-js",
-  "version": "3.13.0",
+  "version": "3.14.0",
   "description": "MongoDB/Mongoose adapter and compatibility facade for Simfinity GraphQL APIs",
   "main": "src/index.js",
   "types": "./types/index.d.ts",
@@ -29,8 +29,8 @@
     "owner": "simtlix"
   },
   "dependencies": {
-    "@simtlix/simfinity-core": "3.13.0",
-    "@simtlix/simfinity-mcp": "3.13.0"
+    "@simtlix/simfinity-core": "3.14.0",
+    "@simtlix/simfinity-mcp": "3.14.0"
   },
   "files": [
     "src",

package/src/mongo/adapter.js

@@ -16,7 +16,7 @@ const withSession = (query, session) => (session ? query.session(session) : quer
 const WRITE_FEATURES = Object.freeze({ optimisticConcurrency: true });
 // Every filter operator the query compiler supports, and emptiness through references and collections (#108 part
 // 2b); the runtime rejects any other operator.
-const QUERY_FEATURES = Object.freeze({ operators: MONGO_QUERY_OPERATORS, referenceEmptiness: true });
+const QUERY_FEATURES = Object.freeze({ operators: MONGO_QUERY_OPERATORS, referenceEmptiness: true, quantifiers: true });
 
 const assertVersionModel = ({ gqltype, model }) => {
   if (!model || !isProtectedType(gqltype)) return;

package/src/mongo/queries.js

@@ -10,7 +10,8 @@ import mongoose from 'mongoose';
 
 import { SimfinityError, QLOperator, paginationStages } from '@simtlix/simfinity-core';
 import {
-  TEXT_QUERY_OPERATORS, describeEmptiness, effectiveScalarName, emptinessScopePaths, isEmptinessOperator,
+  TEXT_QUERY_OPERATORS, aggregateJoinPrefixes, crossingKeys, describeEmptiness, effectiveScalarName, emptinessScopePaths,
+  frameCollectionPaths, isEmptinessOperator, validateQuantifiedGroups,
   textQueryOperator, validateTextFilterValue,
 } from '@simtlix/simfinity-core/internal/query-operators';
 import {
@@ -43,6 +44,8 @@ export const MONGO_QUERY_OPERATORS = Object.freeze([
 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();
+// Only actual reference joins reached through embedded lists multiply a body's candidates.
+const multiplyingBuilds = new WeakSet();
 
 const allocateLookupAlias = (aggregationsIncluded, relationPath) => {
   let aliases = lookupAliases.get(aggregationsIncluded);
@@ -62,7 +65,7 @@ const relationBuild = (aggregationsIncluded) => {
   let build = relationBuilds.get(aggregationsIncluded);
   if (!build) {
     build = {
-      aliases: new Map(), counts: { join: 0, frame: 0 }, scopes: new WeakMap(), scopeCount: 0,
+      aliases: new Map(), counts: { join: 0, frame: 0, scope: 0, serial: 0 }, scopes: new WeakMap(), serials: new WeakMap(),
     };
     relationBuilds.set(aggregationsIncluded, build);
   }
@@ -92,6 +95,7 @@ const buildRelationLookup = ({
     {
       $lookup: {
         from: collectionName, foreignField, localField, as: alias,
+        ...(foreignField !== '_id' && localField !== '_id' ? { pipeline: [{ $match: { [foreignField]: { $ne: null } } }] } : {}),
       },
     },
     { $unwind: { path: `$${alias}`, preserveNullAndEmptyArrays: true } },
@@ -195,13 +199,14 @@ const identifierLeaf = (model, schemaPath, gqltype) => {
 };
 
 // Resolve GraphQL paths and storage paths together; supplied models own ID casting.
-const resolveQueryPath = (gqltype, path, aggregationsIncluded) => {
+const resolveQueryPath = (gqltype, path, aggregationsIncluded, origin) => {
   assertValidFilterPath(path);
   const parts = path.split('.');
   let currentType = gqltype;
-  let currentModel = getModel(gqltype);
-  let mongoPath = '';
-  let schemaPath = '';
+  let currentModel = origin?.model ?? getModel(gqltype);
+  let mongoPath = origin?.parent.key ?? '';
+  let schemaPath = origin?.parent.schemaPath ?? '';
+  let vector = false;
   const aggregateClauses = {};
 
   for (const [index, part] of parts.entries()) {
@@ -218,6 +223,7 @@ const resolveQueryPath = (gqltype, path, aggregationsIncluded) => {
     if (fieldType instanceof GraphQLObjectType) {
       if (index === parts.length - 1) throw filterError(`Query path must end in a scalar field: ${path}`, 'INVALID_FILTER_PATH');
       if (!relation || relation.embedded) {
+        vector ||= !!getListShape(field.type);
         mongoPath = mongoPath ? `${mongoPath}.${part}` : part;
         schemaPath = schemaPath ? `${schemaPath}.${part}` : part;
       } else {
@@ -229,6 +235,8 @@ const resolveQueryPath = (gqltype, path, aggregationsIncluded) => {
           ? normalizeConnectionField(fieldType, relation.connectionField || part).storageFieldName
           : getFieldStorageName(part, field);
         const localLeaf = isList ? '_id' : connField;
+        if (vector) multiplyingBuilds.add(aggregationsIncluded);
+        vector = false;
         const alias = allocateLookupAlias(aggregationsIncluded, parts.slice(0, index + 1).join('.'));
         aggregateClauses[alias] = buildRelationLookup({
           collectionName: relatedModel.collection.collectionName,
@@ -394,7 +402,7 @@ const compileTargetScope = async (build, scope, targetType) => {
   const stages = [];
   const match = await collectFiltersAndLookups(scope, targetType, stages, {}, 'find');
   if (match) stages.push(match);
-  const result = stages.length ? { token: `s${build.scopeCount++}`, stages } : null;
+  const result = stages.length ? { token: `s${build.counts.scope++}`, stages } : null;
   if (!build.scopes.has(scope)) build.scopes.set(scope, new Map());
   build.scopes.get(scope).set(targetType, result);
   return result;
@@ -491,6 +499,179 @@ const buildEmptinessClause = async (gqltype, path, operator, value, construct, l
   return form(ctx, shape, parent, type, segments.at(-1));
 };
 
+// A build keeps one rewrite context; aggregate J paths must survive every logical-group pass.
+const rewriteContext = (gqltype, operation = 'find', aggregation) => {
+  const ctx = { gqltype, operation, quantifiers: true, referenceEmptiness: true, operators: new Set(MONGO_QUERY_OPERATORS), base: '', inFrame: false };
+  // Ordinary root markers reject at the existing post-value guards, preserving native order.
+  ctx.deferOrdinaryRootMarkers = true;
+  ctx.J = operation === 'aggregate' ? aggregateJoinPrefixes(aggregation, ctx) : new Set();
+  return ctx;
+};
+
+// Cross references in the containing pipeline. Collection steps occur here only for an aggregate
+// anchor: all ordinary collection crossings have already become frames in the shared rewrite.
+const crossFramePath = async (gqltype, segments, scopes, build, lookups, included) => {
+  let type = gqltype;
+  let parent = { key: '', schemaPath: '', path: '' };
+  let model = getModel(type);
+  const chain = [];
+  let scoped = false;
+  let vector = false;
+  for (const name of segments) {
+    const field = type.getFields()[name];
+    const targetType = getNamedType(field.type);
+    const path = joinPath(parent.path, name);
+    const relation = field.extensions?.relation;
+    if (!relation || relation.embedded) {
+      vector ||= !!getListShape(field.type);
+      parent = { key: joinPath(parent.key, name), schemaPath: joinPath(parent.schemaPath, name), path };
+    } else {
+      const target = getModel(targetType);
+      if (!target) throw filterError(`Related model is not available for ${path}`, 'INVALID_FILTER_PATH');
+      const collection = !!getListShape(field.type);
+      const foreignField = collection ? normalizeConnectionField(targetType, relation.connectionField || name).storageFieldName : '_id';
+      const localField = joinPath(parent.key, collection ? '_id' : getFieldStorageName(name, field));
+      const scope = scopes && Object.hasOwn(scopes, path) ? await compileTargetScope(build, scopes[path], targetType) : null;
+      if (vector && scope) throw new SimfinityError('A reference inside an embedded list cannot apply a target scope', 'FORBIDDEN_FILTER_PATH', 403);
+      chain.push(scope ? scope.token : '-');
+      scoped ||= !!scope;
+      let alias;
+      if (!scoped) {
+        alias = allocateLookupAlias(included, path);
+        lookups[alias] = buildRelationLookup({ collectionName: target.collection.collectionName, localField, foreignField, alias });
+      } else {
+        alias = allocateRelationAlias(build, 'join', `${path} ${chain.join(',')}`);
+        // A vector with a null target scope keeps every target. The chain alias isolates it
+        // from a trusted join while its local key preserves the earlier restricted reference.
+        lookups[alias] = vector ? buildRelationLookup({ collectionName: target.collection.collectionName, localField, foreignField, alias }) : { stages: [
+          { $lookup: { from: target.collection.collectionName, localField, foreignField, pipeline: [...(scope?.stages ?? []), { $limit: 1 }], as: alias } },
+          { $unwind: { path: `$${alias}`, preserveNullAndEmptyArrays: true } },
+        ] };
+      }
+      if (vector) multiplyingBuilds.add(included);
+      vector = false;
+      parent = { key: alias, schemaPath: '', path };
+      model = target;
+    }
+    type = targetType;
+  }
+  return { type, parent, model, chain };
+};
+
+// A non-emptiness marker is legal only inside a frame, on a condition crossing references. Its
+// keys are relative to the element, just like 2b emptiness keys in the same sub-build.
+const resolveConditionPath = async (gqltype, path, construct, included, ctx) => {
+  if (!hasScopeMarker(construct)) return resolveQueryPath(gqltype, path, included);
+  // buildQueryTerms rejects the marker immediately after buildMatchesClause; group conditions
+  // also retain their raw-condition guard. No accepted path parses or casts a value twice.
+  if (!ctx?.inFrame && ctx?.deferOrdinaryRootMarkers === true) return resolveQueryPath(gqltype, path, included);
+  if (!ctx?.inFrame) throw detachedFilter(`${construct.operator ?? 'EQ'} on ${joinPath(ctx?.base, path)} carries a client scope marker, but is not an emptiness condition`);
+  const paths = crossingKeys(path.split('.'), { gqltype });
+  const scopes = clientScopes(construct, `${construct.operator ?? 'EQ'} on ${joinPath(ctx.base, path)}`, paths);
+  const aggregateClauses = {};
+  const crossed = await crossFramePath(gqltype, path.split('.').slice(0, -1), scopes, relationBuild(included), aggregateClauses, included);
+  const resolved = resolveQueryPath(crossed.type, path.split('.').at(-1), included, crossed);
+  return { ...resolved, aggregateClauses: { ...aggregateClauses, ...resolved.aggregateClauses } };
+};
+
+const compileFrame = async (ctx, quantifier, group) => {
+  const build = relationBuild(ctx.included);
+  const anchor = group.__implicit === true ? group.__anchor ?? [] : [];
+  const segments = [...anchor, ...group.path.split('.')];
+  const paths = [];
+  let type = ctx.gqltype;
+  let vector = false;
+  let multiplyingPrefix = false;
+  for (const [index, name] of segments.entries()) {
+    const field = type.getFields()[name];
+    if (field.extensions?.relation && !field.extensions.relation.embedded) {
+      if (index < segments.length - 1 && vector) multiplyingPrefix = true;
+      vector = false;
+      if (!getModel(getNamedType(field.type))) throw filterError(`Related model is not available for ${joinPath(ctx.base, segments.join('.'))}`, 'INVALID_FILTER_PATH');
+      if (!anchor.length || index >= anchor.length || getListShape(field.type)) paths.push(segments.slice(0, index + 1).join('.'));
+    } else {
+      vector ||= !!getListShape(field.type);
+    }
+    type = getNamedType(field.type);
+  }
+  const scopes = clientScopes(group, `${quantifier} on ${joinPath(ctx.base, segments.join('.'))}`, paths);
+  if (anchor.length && scopes) {
+    for (const path of paths.filter((key) => anchor.join('.').startsWith(key))) {
+      if (scopes[path] !== null) throw detachedFilter('Aggregate anchors require null J scopes and legacy reference joins');
+    }
+  }
+  const emptyAll = quantifier === 'ALL' && !['conditions', 'ANY', 'ALL', 'NONE', 'AND', 'OR'].some((key) => group[key]?.length);
+  // A vector prefix belongs to this predicate, not to the containing result set. A
+  // self-correlated witness keeps its joins local without discarding any target. Aggregate
+  // anchors retain their intentional expansion. NONE tests the positive ANY witness; ALL
+  // looks for a prefix whose complete ALL test fails, including vacuous empty prefixes.
+  if (multiplyingPrefix && !anchor.length && !ctx.prefixIsolated && !emptyAll) {
+    const model = getModel(ctx.gqltype);
+    if (!model) throw filterError(`Related model is not available for ${ctx.gqltype.name}`, 'INVALID_FILTER_PATH');
+    if (!build.serials.has(group)) build.serials.set(group, build.counts.serial++);
+    const alias = allocateRelationAlias(build, 'frame', `prefix:${build.serials.get(group)}`);
+    const stages = [];
+    const included = {};
+    relationBuilds.set(included, { ...relationBuild(included), counts: build.counts, scopes: build.scopes });
+    const positive = await compileFrame({ ...ctx, stages, included, prefixIsolated: true }, quantifier === 'NONE' ? 'ANY' : quantifier, group);
+    if (quantifier === 'ALL' && !Object.keys(positive).length) return {};
+    ctx.stages.push({ $lookup: {
+      from: model.collection.collectionName, localField: '_id', foreignField: '_id',
+      pipeline: [...stages, { $match: quantifier === 'ALL' ? { $nor: [positive] } : positive }, { $limit: 1 }, { $project: { _id: 1 } }],
+      as: alias,
+    } });
+    ctx.included[alias] = true;
+    return { [`${alias}.0`]: { $exists: quantifier === 'ANY' } };
+  }
+  const lookups = {};
+  const crossed = await crossFramePath(ctx.gqltype, segments.slice(0, -1), anchor.length ? null : scopes, build, lookups, ctx.included);
+  const name = segments.at(-1);
+  const field = crossed.type.getFields()[name];
+  const targetType = getNamedType(field.type);
+  const path = segments.join('.');
+  const scope = scopes ? await compileTargetScope(build, scopes[path], targetType) : null;
+  if (emptyAll) return {};
+  // Allocate before compiling the body: descendants follow their parent's serial even though
+  // their lookups live inside its pipeline. No quantified frame shares a 2b emptiness frame.
+  if (!build.serials.has(group)) build.serials.set(group, build.counts.serial++);
+  const alias = allocateRelationAlias(build, 'frame', `group:${build.serials.get(group)} ${path} ${[...crossed.chain, scope ? scope.token : '-'].join(',')}`);
+  const stages = [];
+  const included = {};
+  relationBuilds.set(included, { ...relationBuild(included), counts: build.counts, scopes: build.scopes });
+  const childCtx = { ...rewriteContext(targetType), base: joinPath(ctx.base, path), inFrame: true };
+  const body = await buildFilterGroupMatch(group, targetType, stages, included, 0, childCtx);
+  if (quantifier === 'ALL' && body === null) return {};
+  // ALL negates one truth value for the actual child. With vector joins, negating
+  // individual expanded rows would incorrectly turn a bad sibling target into a failing
+  // child. Keep the complete positive body together, with its scope admission outside.
+  let bodyStages = stages;
+  let bodyMatch = quantifier === 'ALL' ? { $nor: [body] } : body;
+  if (quantifier === 'ALL' && multiplyingBuilds.has(included)) {
+    const witness = allocateRelationAlias(build, 'frame', `body:${build.serials.get(group)}`);
+    bodyStages = [{ $lookup: {
+      from: getModel(targetType).collection.collectionName, localField: '_id', foreignField: '_id',
+      pipeline: [...stages, { $match: body }, { $limit: 1 }, { $project: { _id: 1 } }],
+      as: witness,
+    } }];
+    bodyMatch = { [`${witness}.0`]: { $exists: false } };
+  }
+  const collection = !!getListShape(field.type);
+  const localField = joinPath(crossed.parent.key, collection ? '_id' : getFieldStorageName(name, field));
+  const foreignField = collection ? normalizeConnectionField(targetType, field.extensions.relation.connectionField || name).storageFieldName : '_id';
+  lookups[alias] = { stages: [{ $lookup: {
+    from: getModel(targetType).collection.collectionName, localField, foreignField,
+    pipeline: [
+      ...(collection && localField !== '_id' ? [{ $match: { [foreignField]: { $ne: null } } }] : []),
+      ...(scope?.stages ?? []), ...bodyStages,
+      ...(body === null ? [] : [{ $match: bodyMatch }]),
+      { $limit: 1 }, { $project: { _id: 1 } },
+    ],
+    as: alias,
+  } }] };
+  appendLookups(ctx.stages, ctx.included, lookups);
+  return { [`${alias}.0`]: { $exists: quantifier === 'ANY' } };
+};
+
 const castFilterValue = (value, resolved) => {
   if (value === null) return null;
   if (value === undefined || Array.isArray(value)
@@ -556,7 +737,7 @@ const buildMatchesClause = (resolved, operator, value, path) => {
   return { [resolved.mongoPath]: OP_TO_MONGO[op](coerced, path) };
 };
 
-const buildQueryTerms = async (filterField, qlField, fieldName, gqltype, aggregationsIncluded) => {
+const buildQueryTerms = async (filterField, qlField, fieldName, gqltype, aggregationsIncluded, ctx) => {
   const aggregateClauses = {};
   const matchesClauses = [];
   if (!qlField) throw filterError(`Unknown filter field: ${fieldName}`, 'INVALID_FILTER_FIELD');
@@ -606,10 +787,10 @@ const buildQueryTerms = async (filterField, qlField, fieldName, gqltype, aggrega
     }
     if (isObject) assertValidFilterPath(term.path);
     const path = isObject ? `${fieldName}.${term.path}` : fieldName;
-    const resolved = resolveQueryPath(gqltype, path, aggregationsIncluded);
+    const resolved = await resolveConditionPath(gqltype, path, isObject ? term : null, aggregationsIncluded, ctx);
     Object.assign(aggregateClauses, resolved.aggregateClauses);
     matchesClauses.push(buildMatchesClause(resolved, term.operator, term.value, path));
-    if (isObject && hasScopeMarker(term)) {
+    if (isObject && hasScopeMarker(term) && !ctx?.inFrame) {
       throw detachedFilter(`${term.operator ?? 'EQ'} on ${path} carries a client scope marker, but is not an emptiness condition`);
     }
   }
@@ -625,7 +806,15 @@ const validateLogicalLists = (group, keys = ['AND', 'OR', 'conditions']) => {
   }
 };
 
-const buildFilterGroupMatch = async (filterGroup, gqltype, aggregateClauses, aggregationsIncluded, depth = 0) => {
+const buildFilterGroupMatch = async (rawFilterGroup, gqltype, aggregateClauses, aggregationsIncluded, depth = 0, rewriteCtx) => {
+  let filterGroup = rawFilterGroup;
+  let ctx = rewriteCtx;
+  if (!ctx) {
+    ctx = rewriteContext(gqltype);
+    const input = { AND: [filterGroup] };
+    validateQuantifiedGroups(input, ctx);
+    filterGroup = frameCollectionPaths(input, ctx).AND[0];
+  }
   if (depth > MAX_FILTER_GROUP_DEPTH) {
     throw new SimfinityError('Filter nesting too deep', 'FILTER_DEPTH_EXCEEDED', 400);
   }
@@ -661,15 +850,15 @@ const buildFilterGroupMatch = async (filterGroup, gqltype, aggregateClauses, agg
           throw new SimfinityError(`Filter on object field "${condition.field}" requires a path`, 'MISSING_FILTER_PATH', 400);
         }
         filterInput = {
-          terms: [{ path: condition.path, operator: condition.operator, value: condition.value }],
+          terms: [{ ...rawCondition, field: undefined, path: condition.path, operator: condition.operator, value: condition.value }],
         };
       } else {
         if (condition.path != null && condition.path !== '') throw filterError(`Cannot traverse scalar field ${condition.field}`, 'INVALID_FILTER_PATH');
         filterInput = { operator: condition.operator, value: condition.value };
       }
 
-      const result = await buildQueryTerms(filterInput, qlField, condition.field, gqltype, aggregationsIncluded);
-      if (hasScopeMarker(rawCondition)) {
+      const result = await buildQueryTerms(filterInput, qlField, condition.field, gqltype, aggregationsIncluded, ctx);
+      if (hasScopeMarker(rawCondition) && !ctx.inFrame) {
         throw detachedFilter(`${condition.operator ?? 'EQ'} on ${path} carries a client scope marker, but is not an emptiness condition`);
       }
       appendLookups(aggregateClauses, aggregationsIncluded, result.aggregateClauses);
@@ -681,9 +870,13 @@ const buildFilterGroupMatch = async (filterGroup, gqltype, aggregateClauses, agg
     }
   }
 
+  for (const quantifier of ['ANY', 'ALL', 'NONE']) {
+    for (const group of filterGroup[quantifier] ?? []) parts.push(await compileFrame({ ...ctx, stages: aggregateClauses, included: aggregationsIncluded }, quantifier, group));
+  }
+
   if (filterGroup.AND?.length > 0) {
     for (const subGroup of filterGroup.AND) {
-      const subMatch = await buildFilterGroupMatch(subGroup, gqltype, aggregateClauses, aggregationsIncluded, depth + 1);
+      const subMatch = await buildFilterGroupMatch(subGroup, gqltype, aggregateClauses, aggregationsIncluded, depth + (subGroup.__implicit === true ? 0 : 1), ctx);
       if (subMatch) parts.push(subMatch);
     }
   }
@@ -691,7 +884,7 @@ const buildFilterGroupMatch = async (filterGroup, gqltype, aggregateClauses, agg
   if (filterGroup.OR?.length > 0) {
     const orParts = [];
     for (const subGroup of filterGroup.OR) {
-      const subMatch = await buildFilterGroupMatch(subGroup, gqltype, aggregateClauses, aggregationsIncluded, depth + 1);
+      const subMatch = await buildFilterGroupMatch(subGroup, gqltype, aggregateClauses, aggregationsIncluded, depth + (subGroup.__implicit === true ? 0 : 1), ctx);
       if (subMatch) orParts.push(subMatch);
     }
     if (orParts.length === 1) {
@@ -710,7 +903,10 @@ const FIND_CONTROL_KEYS = new Set(['pagination', 'sort', 'AND', 'OR']);
 // `aggregation` is the expression argument only on aggregate queries; elsewhere it names a field.
 const AGGREGATE_CONTROL_KEYS = new Set([...FIND_CONTROL_KEYS, 'aggregation']);
 
-const collectFiltersAndLookups = async (input, gqltype, aggregateClauses, aggregationsIncluded, operation = 'find') => {
+const collectFiltersAndLookups = async (rawInput, gqltype, aggregateClauses, aggregationsIncluded, operation = 'find', aggregation) => {
+  const ctx = rewriteContext(gqltype, operation, aggregation);
+  validateQuantifiedGroups(rawInput, ctx);
+  const input = frameCollectionPaths(rawInput, ctx);
   // Top-level arguments are field filters plus AND/OR groups; `conditions` is a key only inside groups.
   validateLogicalLists(input, ['AND', 'OR']);
   const controlKeys = operation === 'aggregate' ? AGGREGATE_CONTROL_KEYS : FIND_CONTROL_KEYS;
@@ -722,7 +918,7 @@ const collectFiltersAndLookups = async (input, gqltype, aggregateClauses, aggreg
   for (const [key, filterField] of Object.entries(input)) {
     if (controlKeys.has(key)) continue;
     const qlField = fields[key];
-    const result = await buildQueryTerms(filterField, qlField, key, gqltype, aggregationsIncluded);
+    const result = await buildQueryTerms(filterField, qlField, key, gqltype, aggregationsIncluded, ctx);
     appendLookups(aggregateClauses, aggregationsIncluded, result.aggregateClauses);
     for (const matchClause of Object.values(result.matchesClauses)) {
       for (const [matchKey, match] of Object.entries(matchClause)) {
@@ -742,7 +938,7 @@ const collectFiltersAndLookups = async (input, gqltype, aggregateClauses, aggreg
 
   if (input.AND?.length > 0) {
     for (const group of input.AND) {
-      const groupMatch = await buildFilterGroupMatch(group, gqltype, aggregateClauses, aggregationsIncluded);
+      const groupMatch = await buildFilterGroupMatch(group, gqltype, aggregateClauses, aggregationsIncluded, 0, ctx);
       if (groupMatch) topLevelAndParts.push(groupMatch);
     }
   }
@@ -750,7 +946,7 @@ const collectFiltersAndLookups = async (input, gqltype, aggregateClauses, aggreg
   if (input.OR?.length > 0) {
     const orParts = [];
     for (const group of input.OR) {
-      const groupMatch = await buildFilterGroupMatch(group, gqltype, aggregateClauses, aggregationsIncluded);
+      const groupMatch = await buildFilterGroupMatch(group, gqltype, aggregateClauses, aggregationsIncluded, 0, ctx);
       if (groupMatch) orParts.push(groupMatch);
     }
     if (orParts.length === 1) {
@@ -777,6 +973,15 @@ const validateSortTerms = (sort) => {
 const buildSortClause = (sortTerms, gqltype, aggregateClauses, aggregationsIncluded) => {
   const sortExpressions = {};
   for (const sort of sortTerms) {
+    let type = gqltype;
+    for (const name of sort.field.split('.')) {
+      const field = type.getFields?.()[name];
+      if (!field) break;
+      if (field.extensions?.relation && !field.extensions.relation.embedded && getListShape(field.type)) {
+        throw filterError(`Sort path ${sort.field} crosses the collection ${type.name}.${name}; a record has no single value there`, 'INVALID_FILTER_PATH');
+      }
+      type = getNamedType(field.type);
+    }
     const resolved = resolveQueryPath(gqltype, sort.field, aggregationsIncluded);
     appendLookups(aggregateClauses, aggregationsIncluded, resolved.aggregateClauses);
     sortExpressions[resolved.mongoPath] = sort.order === 'ASC' ? 1 : -1;
@@ -817,7 +1022,7 @@ const buildAggregationQuery = async (input, gqltype, aggregationExpression) => {
   const aggregationsIncluded = {};
   const paging = paginationStages(input.pagination, false);
 
-  const matchStage = await collectFiltersAndLookups(input, gqltype, aggregateClauses, aggregationsIncluded, 'aggregate');
+  const matchStage = await collectFiltersAndLookups(input, gqltype, aggregateClauses, aggregationsIncluded, 'aggregate', aggregationExpression);
   if (matchStage) aggregateClauses.push(matchStage);
 
   const { groupId, facts } = aggregationExpression ?? {};

package/types/index.d.ts

@@ -17,6 +17,7 @@ import type {
   DatabaseAdapter,
   MutationLimitsOptions,
   QueryFeatures,
+  QueryLimitsOptions,
   RuntimeRegistration,
   SimfinityError,
   ViewOptions,
@@ -50,6 +51,12 @@ export type {
   MutationLimitsOptions,
   PermissionSchema,
   PolicyExpression,
+  QLFilterCondition,
+  QLFilterGroup,
+  QLQuantifiedGroup,
+  QLTypeFilterExpression,
+  QueryLimitsOptions,
+  QueryQuantifier,
   ScopeFunction,
   ScopeOperation,
   ScopeParams,
@@ -103,7 +110,7 @@ export interface MongoAdapter extends DatabaseAdapter {
   /** Frozen declaration of atomic expectedVersion writes; wrappers must forward every argument. */
   readonly writeFeatures: Readonly<{ optimisticConcurrency: true }>;
   /**
-   * Frozen; lists every `QLOperator` value and declares `referenceEmptiness: true`. The literal text
+   * Frozen; lists every `QLOperator` value and declares `referenceEmptiness: true` and `quantifiers: true`. The literal text
    * operators compile to escaped regular expressions: `ILIKE` unanchored, `STARTS_WITH` and
    * `ISTARTS_WITH` anchored with `^`, `ENDS_WITH` and `IENDS_WITH` with `\z`, and `IEQ` with both, with
    * the `i` option for the case-insensitive ones. `IS_EMPTY` and `IS_NOT_EMPTY` compile to plain query
@@ -284,21 +291,10 @@ export function use(
 /** Globally prevent Mongoose collection creation for generated models. */
 export function preventCreatingCollection(prevent: boolean): void;
 
-/** Process-wide limits for generated list and paginated aggregate queries. */
-export interface QueryLimitsOptions {
-  /** Positive safe integer; defaults to 1000. Unpaged lists use min(100, maxPageSize). */
-  maxPageSize?: number;
-  /**
-   * Positive safe integer; defaults to 10. The most distinct scoped joins and frames that the
-   * client's reference and collection emptiness may need in one list, aggregate or collection-field
-   * call; more fail with `FILTER_DEPTH_EXCEEDED` (400).
-   */
-  maxReferenceFrames?: number;
-}
-
 /**
- * Configure at startup. Invalid configuration throws INVALID_QUERY_LIMITS (400) and keeps both
- * limits; an omitted option takes its default again.
+ * Process-wide limits for generated list and paginated aggregate queries. Configure at startup.
+ * Invalid configuration throws INVALID_QUERY_LIMITS (400) and keeps all limits; an omitted option
+ * takes its default again.
  */
 export function configureQueryLimits(options?: QueryLimitsOptions): void;
 
@@ -352,10 +348,13 @@ export function getType(
  * Query building (src/index.js)
  * ========================================================================== */
 
-/** A QLFilterGroup input value (recursive AND/OR groups plus flat conditions). */
+/** A QLFilterGroup input value: conditions, logical groups and element-relative quantified groups. */
 export interface FilterGroupInput {
   AND?: FilterGroupInput[];
   OR?: FilterGroupInput[];
+  ANY?: QuantifiedGroupInput[];
+  ALL?: QuantifiedGroupInput[];
+  NONE?: QuantifiedGroupInput[];
   conditions?: Array<{
     field: string;
     operator?: string;
@@ -367,6 +366,11 @@ export interface FilterGroupInput {
   [key: string]: any;
 }
 
+/** A reference or collection frame; its body uses paths relative to the target element. */
+export interface QuantifiedGroupInput extends FilterGroupInput {
+  path: string;
+}
+
 /**
  * Translate list-query arguments (filters, AND/OR, sort, pagination) into a MongoDB aggregation
  * pipeline. `input.aggregation` filters a field named `aggregation`; the aggregate stage is never
@@ -403,16 +407,25 @@ export interface FilterGroupInput {
  * that a scope hides reads as missing. A crossing or frame after a scoped crossing stays in that chain,
  * also when its own scope is null. The aliases are unset at the end of find pipelines. A target type
  * without a model fails with `INVALID_FILTER_PATH` (400), and a marker that is not filled for every
- * path the construct reads, or that sits on a construct that reads none or on another operator, with
+ * path the construct reads, or that sits on a construct that reads no relation or on an ordinary
+ * condition outside a quantified frame, with
  * `DETACHED_CLIENT_FILTER` (500), after the 400 checks. Supplied models on another database or
  * connection and discriminator targets are not supported here, as for the other relation paths.
  *
+ * Ordinary paths through collections compile as correlated `ANY` frames. Conditions in one group
+ * sharing a collection must hold on the same child, and each parent appears once. Explicit `ANY`,
+ * `ALL` and `NONE` groups and `quantifier` field filters accept element-relative conditions; `ALL`
+ * alone is true, including an OR branch. Target find scopes precede frame conditions; trusted
+ * constructs read stored data. References inside a client frame use its element-relative scope
+ * keys. Off-root collection correlation keys get an inner non-null connection guard. Aggregate
+ * groupId/fact collection prefixes keep legacy joins, and other filters can anchor frames on them.
+ * Collection sorts reject with `INVALID_FILTER_PATH`, including count mode.
+ *
  * The checks, and their codes, are those of `createQueryPlan` in the same order: `MISSING_FILTER_PATH`
  * for an emptiness operator on an object filter without terms or beside terms, `INVALID_FILTER_PATH`
  * for a value inside an embedded list or a collection and for an interface or union field or member,
  * `INVALID_FILTER_OPERATOR` for an embedded type that reaches itself through single embedded members,
- * and `INVALID_FILTER_VALUE` for a value that is not omitted or null. Other operators keep their
- * pipelines.
+ * and `INVALID_FILTER_VALUE` for a value that is not omitted or null.
  */
 export function buildQuery(
   input: Record<string, any>,