@simtlix/simfinity-js 3.12.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

@@ -22,6 +22,16 @@ Use a MongoDB replica set or sharded cluster for transactional mutations. The li
 
 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. For the same reason, they keep the read that generated mutations otherwise skip before a delete without `onDelete` and before an update that merges no embedded value. So do models with `findOneAndUpdate` or `findOneAndDelete` hooks (including the one Mongoose's `timestamps` option adds) or with their own `findById`, `findOne`, `findByIdAndUpdate`, `findOneAndUpdate`, `findByIdAndDelete` or `findOneAndDelete` statics, which run before Mongoose casts the ID: the read rejects a malformed ID first. Models with application `_id` setters also keep the read, because setters can branch on the query operation before casting; Mongoose's built-in automatic ObjectId setter remains eligible for the optimization. See the [relationship contract](https://simtlix.github.io/simfinity.js/guide/relationships.html).
 
+Declare `extensions: { concurrency: { mode: 'optimistic' } }` on an entity before its first `createSchema()` to enable optimistic concurrency. Simfinity adds a managed `version: RecordVersion!` field, starts new records at 1, and requires the version read by the client on updates, state actions and deletes. A successful update advances it once; a stale write fails with `VERSION_CONFLICT` (409), and an update at `MAX_RECORD_VERSION` (9007199254740991) fails with `VERSION_EXHAUSTED` (409). Missing or null versions in existing MongoDB documents count as 1 and advance to 2 on their first protected update. Other invalid stored versions produce `DATABASE_ERROR`.
+
+Generated models declare a plain `version: Number` path without an index. A supplied model must already declare `version: Number`, without `immutable`, `select: false`, getters, setters or a default other than the literal 1; an alias is allowed, but `schema.options.versionKey` cannot be `'version'`. Simfinity rejects incompatible models with `INVALID_MODEL` and does not add paths to compiled models. Protection cannot be enabled after a type's first schema was built, or after a failed `createSchema()` already built its inputs or generated model without the managed field. Native pre/post save middleware must preserve initialized version 1 and the returned managed version: core checks controller `onSaving` before native save middleware and adds no post-save guard.
+
+Protected updates use `findOneAndUpdate` with an atomic ID/version filter and set the next version explicitly; `findByIdAndUpdate` overrides no longer run. Protected deletes in default mode use `findOneAndDelete`, bypassing `findByIdAndDelete` overrides; transactional integrity still calls `findByIdAndDelete` after its conditional lock write. `findOneAndUpdate` and `findOneAndDelete` middleware and statics still run. Middleware must preserve the version condition and increment. The no-match existence read uses the raw collection and bypasses query middleware, so middleware-hidden records can still produce `VERSION_CONFLICT`; express record visibility in `get_by_id` scope instead of relying on middleware hiding. Core checks the returned versions as defensive diagnostics; those checks do not prove that arbitrary middleware or adapter wrappers preserved the atomic precondition. Wrappers must forward every argument, including `options.expectedVersion`. Update pipelines with `expectedVersion` retain their stages and append the managed next-version assignment; calls without that option preserve the existing write paths, including update pipelines.
+
+The protected pre-read is a plain transaction read, with no extra claim lock. MongoDB write conflicts can retry an owned mutation; validators and hooks may run again, so keep external side effects out of them. Adapter-detected version errors abort a supplied session in transactional integrity mode; in default mode the caller owns the abort. Core-detected errors retain caller ownership of supplied sessions. A type's `get_by_id` scope decides whether stale versions are reported before hooks; hidden callers reach the conditional write after their hooks authorize it.
+
+Native writers must follow the same protocol: match `{ _id, version: expected }` (use `version: { $in: [1, null] }` for expected 1), then set `{ $set: { ...changes, version: expected + 1 } }`, or delete with that filter. Check the matched result and never update at the maximum version. Use the model's `Model.base.trusted({ $in: [1, null] })` for this operator when calling Mongoose with `sanitizeFilter`. Do not use `$inc`: missing and null legacy values need an explicit next value. Native writes that skip this protocol are outside the guarantee; derived-value maintenance within the same transaction may use an ordinary `updateOne` without advancing the version.
+
 Generated models store enum internal values with their own type (numbers, booleans or strings; other combinations as given) and support embedded fields named `type`. Embedded types that contain each other are rejected with `INVALID_MODEL` (`Embedded cycle at …`) when a generated model reaches them, and always in transactional mode; in the default mode, a cycle that only supplied models reach is not checked. Range filters, sorts and aggregates on numeric and boolean enums follow that type; PostgreSQL uses their text form. Earlier versions stored numeric and boolean enum values as strings; convert existing documents once as described in the [schema guide](https://simtlix.github.io/simfinity.js/guide/schema.html#what-gets-generated).
 
 Virtual fields (`extensions: { virtual: true }`, with the field's own `resolve`) get no path, no `[]` default and no index in generated models, on entities and embedded types, and no entry in the transactional integrity registry, so they need no `relation` in either mode and documents look the same with or without them. Generated writes never set or unset them, and Mongoose's strict mode drops a value that a controller assigns to a generated document for one. An embedded type whose members are all virtual becomes a strict subdocument without paths rather than a Mixed path, so nothing is stored for it but the `_id` of list items. With a generated model, values stored before a field became virtual stay in the documents: Mongoose drops an `$unset` of a path the model does not declare, so remove them with a driver-level update, such as `getModel(Type).collection.updateMany({}, { $unset: { busyRanges: '' } })`, or with `updateMany(filter, update, { strict: false })`; a generated update that sets an embedded parent rewrites it, which drops the stored keys of its virtual members. A supplied model keeps the paths it declares: documents stored earlier keep their values for the field, which nothing reads or writes until `$unset` removes them, and an index on such a path stays until you drop it. `buildQuery()` rejects a path through a virtual field with `INVALID_FILTER_FIELD` (400).
@@ -32,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.12.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.12.0",
-    "@simtlix/simfinity-mcp": "3.12.0"
+    "@simtlix/simfinity-core": "3.14.0",
+    "@simtlix/simfinity-mcp": "3.14.0"
   },
   "files": [
     "src",

package/src/index.js

@@ -1,5 +1,7 @@
 import {
   InternalServerError,
+  MAX_RECORD_VERSION,
+  RecordVersion,
   SimfinityError,
   buildErrorFormatter,
   createRuntime,
@@ -36,6 +38,8 @@ export {
   createRuntime,
   createValidatedScalar,
   InternalServerError,
+  MAX_RECORD_VERSION,
+  RecordVersion,
   SimfinityError,
 };
 

package/src/mongo/adapter.js

@@ -1,20 +1,113 @@
 import mongoose from 'mongoose';
 import { SimfinityError } from '@simtlix/simfinity-core';
+import { MAX_RECORD_VERSION, isProtectedType, isVersionField, readStoredVersion, retainStoredVersion } from '@simtlix/simfinity-core/internal/record-version';
 import { getListShape, normalizeConnectionField } from '@simtlix/simfinity-core/internal/relation-storage';
 
 import { createMongoModel } from './models.js';
 import { MONGO_QUERY_OPERATORS, createMongoQueries } from './queries.js';
 import { withMongoTransaction } from './transactions.js';
-import { createMongoIntegrity } from './integrity.js';
+import { createMongoIntegrity, readVersionMiss, versionFilter, versionTypeName, versionedUpdate } from './integrity.js';
 import {
   castModelId, castObjectId, castPathValue, invalidId, isQueryKeyCastFailure, mapIdCastError,
 } from './ids.js';
 
 const withSession = (query, session) => (session ? query.session(session) : query);
 
+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;
+  const path = model.schema?.path('version');
+  if (path?.instance !== 'Number' || path.options.immutable || path.options.select === false
+    || path.getters.length || path.setters.length
+    || (path.defaultValue !== undefined && path.defaultValue !== 1) || model.schema.options.versionKey === 'version') {
+    throw new SimfinityError(
+      `${gqltype.name} declares optimistic concurrency, so its Mongoose model must declare version: Number without immutable, select: false, getters, setters or a default other than 1`,
+      'INVALID_MODEL', 400,
+    );
+  }
+};
+
+// Mongoose 8 casts Number paths before query middleware/transforms. Capture invalid raw versions
+// at its private completion seam, then carry them to final same-record results after exec. Stored
+// identity, never final array position, associates toObject/toJSON copies and reordered batches.
+// Replacements must retain _id or an equivalent id; fabricated same-ID records cannot be distinguished
+// from conversions. No document/schema mutation or extra read is needed, including for frozen results.
+// Recheck these query-local completion seams when upgrading the Mongoose peer.
+const preserveStoredVersion = (query, many) => {
+  const method = many ? '_completeMany' : '_completeOne';
+  const complete = query?.[method];
+  const exec = query?.exec;
+  if (typeof complete !== 'function' || typeof exec !== 'function') {
+    throw new SimfinityError('Protected MongoDB reads require a Mongoose query with hydration completion support', 'DATABASE_ERROR', 500);
+  }
+  const captured = new Map();
+  const originals = new Map();
+  const keyOf = (record) => {
+    const key = record?._id ?? record?.id;
+    return key == null ? null : String(key);
+  };
+  const capture = (document) => {
+    const value = document?.version;
+    try { readStoredVersion(value); return null; }
+    catch {
+      const key = keyOf(document);
+      if (key !== null) captured.set(key, value);
+      return { key, value };
+    }
+  };
+  const associate = (record) => {
+    if (record === null || typeof record !== 'object') return;
+    const key = keyOf(record);
+    if (captured.has(key)) retainStoredVersion(record, captured.get(key));
+    else if (key === null && originals.has(record)) retainStoredVersion(record, originals.get(record));
+    // Middleware can reuse a result object across queries. Its prior raw value is no longer
+    // evidence about this result when the current query has no matching invalid storage value.
+    else retainStoredVersion(record, undefined);
+  };
+  if (many) {
+    query[method] = async function completeVersions(documents, ...args) {
+      const invalid = documents.map(capture);
+      const results = await complete.call(this, documents, ...args);
+      // Mongoose 8 _completeMany uses Promise.all over the raw documents in order. This
+      // establishes provenance only for its original hydrated objects, before transforms;
+      // final replacements still require an identifying key and never match by array position.
+      results.forEach((record, index) => {
+        const stored = invalid[index];
+        if (stored && record != null && keyOf(record) === stored.key) originals.set(record, stored.value);
+      });
+      return results;
+    };
+  } else {
+    query[method] = function completeVersion(document, metadata, projection, callback) {
+      const invalid = capture(document);
+      return complete.call(this, document, metadata, projection, (error, result) => {
+        const record = this.options?.includeResultMetadata ? result?.value : result;
+        // This completion callback establishes the original record's provenance even if a
+        // projection omits its identity. A later replacement still needs an identifying key.
+        if (!error && invalid && record != null && keyOf(record) === invalid.key) {
+          originals.set(record, invalid.value);
+        }
+        callback(error, result);
+      });
+    };
+  }
+  query.exec = async function execPreservingVersions(...args) {
+    try {
+      const result = await exec.apply(this, args);
+      if (many && Array.isArray(result)) result.forEach(associate);
+      else associate(this.options?.includeResultMetadata ? result?.value : result);
+      return result;
+    } finally {
+      captured.clear();
+      originals.clear();
+    }
+  };
+  return query;
+};
 
 // A write that fails only on malformed ObjectId values reports NOT_VALID_ID, not a driver error.
 const mapIdCastErrors = async (write) => {
@@ -214,6 +307,10 @@ export const createMongoAdapter = (options) => {
     session, body, (Model || session) ? Model : sessionModel(), ...rest,
   );
 
+  const versionedRead = (Model, query, many = false) => getRegistrations().some(
+    (registration) => registration.model === Model && isVersionField(registration.gqltype.getFields().version),
+  ) ? preserveStoredVersion(query, many) : query;
+
   const addPrivateConnectionField = (typeName, fieldName) => {
     if (!privateConnectionFields.has(typeName)) privateConnectionFields.set(typeName, new Set());
     privateConnectionFields.get(typeName).add(fieldName);
@@ -221,6 +318,7 @@ export const createMongoAdapter = (options) => {
 
   const adapter = {
     queryFeatures: QUERY_FEATURES,
+    writeFeatures: WRITE_FEATURES,
     bind(binding) {
       integrity.bind(binding);
       getRegistrations = binding.getRegistrations;
@@ -229,6 +327,7 @@ export const createMongoAdapter = (options) => {
       adapter.buildFilterGroupMatch = queries.buildFilterGroupMatch;
     },
     prepare(registrations, preparationOptions) {
+      for (const registration of registrations) assertVersionModel(registration);
       integrity.prepare(registrations, preparationOptions);
       for (const registration of registrations) {
         for (const field of Object.values(registration.gqltype.getFields())) {
@@ -317,7 +416,7 @@ export const createMongoAdapter = (options) => {
       let query = withSession(requiredId == null ? Model.findById(id, projection)
         : Model.findOne({ $and: [{ _id: requiredId }, { _id: id }] }, projection), session);
       if (plain) query = query.lean();
-      return mapQueryIdCastErrors(query);
+      return mapQueryIdCastErrors(versionedRead(Model, query));
     },
     getByIds(Model, ids) {
       integrity.assertReady();
@@ -325,7 +424,7 @@ export const createMongoAdapter = (options) => {
       // 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 }) });
+      return versionedRead(Model, Model.find({ _id: mongoose.trusted({ $in: ids }) }), true);
     },
     // Without middleware or overrides of the by-ID statics (see readsByIdAreInert), a read by ID has
     // no side effects, and a malformed ID fails the update or delete before application code runs,
@@ -336,16 +435,43 @@ export const createMongoAdapter = (options) => {
     prepareUpdate(set, unset) {
       return Object.keys(unset).length > 0 ? { ...set, $unset: unset } : set;
     },
-    update(Model, id, update, session) {
-      if (integrity.enabled) return integrity.updateRecord(Model, id, update, session);
+    update(Model, id, update, session, writeOptions) {
+      if (integrity.enabled) return integrity.updateRecord(Model, id, update, session, writeOptions);
+      const expected = writeOptions?.expectedVersion;
+      if (expected !== undefined) {
+        return mapIdCastErrors(async () => {
+          const query = mapQueryIdCastErrors(withSession(Model.findOneAndUpdate(
+            { _id: id, ...versionFilter(Model, expected) }, versionedUpdate(update, expected), { new: true },
+          ), session), mapIdCastError);
+          if (expected >= MAX_RECORD_VERSION) {
+            try {
+              query.cast(Model);
+            } catch (error) {
+              // The skipped query has no exec/error flag; this cast only processes its filter.
+              throw error?.name === 'CastError' && error.path === '_id' ? invalidId() : error;
+            }
+            return readVersionMiss(Model, query.getFilter()._id, session, expected, true, versionTypeName(Model, getRegistrations()));
+          }
+          const updated = await query;
+          return updated ?? readVersionMiss(Model, query.getFilter()._id, session, expected, true, versionTypeName(Model, getRegistrations()));
+        });
+      }
       return mapQueryIdCastErrors(withSession(
         Model.findByIdAndUpdate(id, update, { new: true }), session,
       ), mapIdCastError);
     },
-    delete(Model, id, session) {
+    delete(Model, id, session, writeOptions) {
       if (integrity.enabled) {
         integrity.assertWrite(Model, session);
-        return integrity.deleteRecord(Model, id, session);
+        return integrity.deleteRecord(Model, id, session, writeOptions);
+      }
+      const expected = writeOptions?.expectedVersion;
+      if (expected !== undefined) {
+        const query = mapQueryIdCastErrors(withSession(Model.findOneAndDelete(
+          { _id: id, ...versionFilter(Model, expected) },
+        ), session));
+        return query.then((deleted) => deleted ?? readVersionMiss(Model, query.getFilter()._id, session, expected, false,
+          versionTypeName(Model, getRegistrations())));
       }
       return mapQueryIdCastErrors(withSession(Model.findByIdAndDelete(id), session));
     },
@@ -354,7 +480,7 @@ export const createMongoAdapter = (options) => {
       const pipeline = await queries.buildQuery(args, gqltype);
       // Mongoose does not cast aggregation stages, so cast the key type here, without setters.
       if (requiredId != null) pipeline.unshift({ $match: { _id: castModelId(Model, requiredId) } });
-      if (pipeline.length === 0) return withSession(Model.find({}), session);
+      if (pipeline.length === 0) return versionedRead(Model, withSession(Model.find({}), session), true);
       return withSession(Model.aggregate(pipeline), session);
     },
     async count(Model, gqltype, args, session) {

package/src/mongo/integrity.js

@@ -1,8 +1,38 @@
 import mongoose from 'mongoose';
 import { describeModels, SimfinityError } from '@simtlix/simfinity-core';
+import {
+  MAX_RECORD_VERSION, readStoredVersion, unadvancedVersionError, versionConflictError, versionExhaustedError,
+} from '@simtlix/simfinity-core/internal/record-version';
 import { withMongoTransaction } from './transactions.js';
 import { castModelId, mapIdCastError } from './ids.js';
 
+// Shared by default and integrity writes. Trust this library-owned operator using the model's own
+// Mongoose instance, so sanitizeFilter also works for models compiled by another copy.
+export const versionFilter = (Model, expected) => ({
+  version: expected === 1 ? Model.base.trusted({ $in: [1, null] }) : expected,
+});
+
+export const versionedUpdate = (update, expected) => Array.isArray(update)
+  ? [...update, { $set: { version: expected + 1 } }]
+  : { ...update, version: expected + 1 };
+
+// A supplied model need not share its GraphQL type's name. Do not choose arbitrarily when one
+// model serves several registrations, or when a direct adapter caller has no runtime binding.
+export const versionTypeName = (Model, registrations = []) => {
+  const matches = registrations.filter(({ model }) => model === Model);
+  return matches.length === 1 ? matches[0].gqltype.name : Model.modelName;
+};
+
+// Bypass query middleware and use the write's cast key, in its still-active transaction.
+export const readVersionMiss = async (Model, id, session, expected, updating = false, typeName = Model.modelName) => {
+  const stored = await Model.collection.findOne({ _id: id }, { session, projection: { version: 1 } });
+  if (!stored) return null;
+  const version = readStoredVersion(stored.version, { typeName, id });
+  if (version !== expected) throw versionConflictError(typeName, id);
+  if (updating && version === MAX_RECORD_VERSION) throw versionExhaustedError(typeName, id);
+  return null;
+};
+
 const LOCK_FIELD = '_simfinityReferenceLock';
 // Distinct target ids per startup-audit query and per lock write, and ids the audit remembers per target.
 const AUDIT_BATCH_SIZE = 1000;
@@ -99,9 +129,10 @@ export const createMongoIntegrity = (options = {}) => {
     return [...references.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([, value]) => value);
   };
 
-  const lock = async (Model, id, session) => {
+  const lock = async (Model, id, session, expectedVersion) => {
     const result = await Model.collection.updateOne(
-      { _id: id }, { $set: { [LOCK_FIELD]: new mongoose.Types.ObjectId() } }, { session },
+      { _id: id, ...(expectedVersion === undefined ? {} : versionFilter(Model, expectedVersion)) },
+      { $set: { [LOCK_FIELD]: new mongoose.Types.ObjectId() } }, { session },
     );
     return result.matchedCount > 0;
   };
@@ -297,26 +328,45 @@ export const createMongoIntegrity = (options = {}) => {
     },
     // Protected writes cast the key before querying, without setters, as 3.5.3 did: the lock, the
     // reference checks and the identity checks must all use the key requested before middleware runs.
-    async updateRecord(Model, id, update, session) {
+    async updateRecord(Model, id, update, session, { expectedVersion } = {}) {
       assertWrite(Model, session);
       return abortOnWriteError(session, async () => {
         const objectId = castModelId(Model, id);
-        const updated = await Model.findByIdAndUpdate(objectId, update, { new: true }).session(session);
+        const versioned = expectedVersion !== undefined;
+        const query = (versioned
+          ? Model.findOneAndUpdate({ _id: objectId, ...versionFilter(Model, expectedVersion) },
+            versionedUpdate(update, expectedVersion), { new: true })
+          : Model.findByIdAndUpdate(objectId, update, { new: true })).session(session);
+        // No write at the ceiling, but still cast the raw existence lookup's key once.
+        const exhausted = versioned && expectedVersion >= MAX_RECORD_VERSION;
+        if (exhausted) query.cast(Model);
+        const updated = exhausted ? null : await query;
         if (!updated) {
+          if (versioned) await readVersionMiss(Model, query.getFilter()._id, session, expectedVersion, true,
+            versionTypeName(Model, binding.getRegistrations()));
           // A middleware can hide a completed write with a null result. Abort
           // even on a genuine no-match; core still reports its normal NOT_VALID_ID.
           await session.abortTransaction();
           return null;
         }
         if (!updated._id?.equals(objectId)) throw violation();
+        if (versioned) {
+          const typeName = versionTypeName(Model, binding.getRegistrations());
+          if (readStoredVersion(updated.version, { typeName, id }) !== expectedVersion + 1) {
+            throw unadvancedVersionError(typeName, id);
+          }
+        }
         await validateRecord(Model, updated, session);
         return updated;
       });
     },
-    async deleteRecord(Model, id, session) {
+    async deleteRecord(Model, id, session, { expectedVersion } = {}) {
       return abortOnWriteError(session, async () => {
         const objectId = castModelId(Model, id);
-        if (!await lock(Model, objectId, session)) return null;
+        if (!await lock(Model, objectId, session, expectedVersion)) {
+          return expectedVersion === undefined ? null : readVersionMiss(Model, objectId, session, expectedVersion, false,
+            versionTypeName(Model, binding.getRegistrations()));
+        }
         // One query per referencing collection: the $or of its per-path queries, each branch served
         // by its own path index. A self-reference ignores the deleted document itself. The $ne stays
         // inside each branch: hoisted, the planner can pick a scan of the _id index instead.

package/src/mongo/models.js

@@ -11,6 +11,7 @@ import {
   GraphQLString,
 } from 'graphql';
 import mongoose from 'mongoose';
+import { isVersionField } from '@simtlix/simfinity-core/internal/record-version';
 import { SimfinityError } from '@simtlix/simfinity-core';
 import { getFieldStorageName, isVirtualField } from '@simtlix/simfinity-core/internal/relation-storage';
 
@@ -117,7 +118,9 @@ const generateSchemaDefinition = (gqlType, nested = false, ancestors = [], path
     if (isVirtualField(fieldEntry)) continue;
     const { type } = fieldEntry;
 
-    if (matchesScalar(type, GraphQLID)) {
+    if (isVersionField(fieldEntry)) {
+      schemaArg[fieldEntryName] = Number;
+    } else if (matchesScalar(type, GraphQLID)) {
       schemaArg[fieldEntryName] = mongoose.Schema.Types.ObjectId;
     } else if (matchesScalar(type, GraphQLString)) {
       schemaArg[fieldEntryName] = withUnique(fieldEntry, String);

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,
@@ -27,7 +28,9 @@ export {
   createRuntime,
   createValidatedScalar,
   InternalServerError,
+  MAX_RECORD_VERSION,
   plugins,
+  RecordVersion,
   scalars,
   SimfinityError,
   validators,
@@ -37,6 +40,7 @@ export type {
   AuthRule,
   AuthRuleFunction,
   AuthSchemaPlugin,
+  ConcurrencyDeclaration,
   CreateSchemaOptions,
   EnvelopSchemaPlugin,
   FieldValidations,
@@ -47,6 +51,12 @@ export type {
   MutationLimitsOptions,
   PermissionSchema,
   PolicyExpression,
+  QLFilterCondition,
+  QLFilterGroup,
+  QLQuantifiedGroup,
+  QLTypeFilterExpression,
+  QueryLimitsOptions,
+  QueryQuantifier,
   ScopeFunction,
   ScopeOperation,
   ScopeParams,
@@ -97,8 +107,10 @@ export interface MongoAdapterOptions {
  */
 export interface MongoAdapter extends DatabaseAdapter {
   readonly referentialIntegrity: 'off' | 'transactional';
+  /** 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
@@ -127,6 +139,15 @@ export interface MongoAdapter extends DatabaseAdapter {
   /** After connecting MongoDB and createSchema(), await the transaction capability and existing-reference audit. */
   initialize(): Promise<void>;
 }
+/**
+ * Supports extensions.concurrency: { mode: 'optimistic' }. Generated models store version as Number.
+ * Supplied models must declare version: Number without immutable, select: false, getters, setters
+ * or a default other than 1; versionKey must not be 'version'. Missing/null stored versions mean 1.
+ * Protected writes use findOneAndUpdate/findOneAndDelete statics (integrity deletes still call
+ * findByIdAndDelete). Query middleware must preserve the version condition and increment.
+ * Adapter-detected conflicts abort supplied transactions only in transactional integrity mode;
+ * in default mode, the caller owns the abort. Core-detected conflicts keep that caller ownership.
+ */
 export function createMongoAdapter(options?: MongoAdapterOptions): MongoAdapter;
 export function getRegistrations(): RuntimeRegistration[];
 
@@ -270,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;
 
@@ -338,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;
@@ -353,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
@@ -389,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>,