@simtlix/simfinity-js 3.11.0 → 3.13.0

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,7 +42,7 @@ 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 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. 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).
+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.11.0",
+  "version": "3.13.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.11.0",
-    "@simtlix/simfinity-mcp": "3.11.0"
+    "@simtlix/simfinity-core": "3.13.0",
+    "@simtlix/simfinity-mcp": "3.13.0"
   },
   "files": [
     "src",

package/src/index.js

@@ -1,5 +1,7 @@
 import {
   InternalServerError,
+  MAX_RECORD_VERSION,
+  RecordVersion,
   SimfinityError,
   buildErrorFormatter,
   createRuntime,
@@ -23,6 +25,7 @@ export const getRegistrations = runtime.getRegistrations;
 export const use = runtime.use;
 export const registerMutation = runtime.registerMutation;
 export const registerCustomQuery = runtime.registerCustomQuery;
+export const registerView = runtime.registerView;
 export const saveObject = runtime.saveObject;
 export const preventCreatingCollection = runtime.preventCreatingCollection;
 
@@ -35,6 +38,8 @@ export {
   createRuntime,
   createValidatedScalar,
   InternalServerError,
+  MAX_RECORD_VERSION,
+  RecordVersion,
   SimfinityError,
 };
 

package/src/mongo/adapter.js

@@ -1,21 +1,114 @@
 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 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) => {
   try {
@@ -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/types/index.d.ts

@@ -19,6 +19,7 @@ import type {
   QueryFeatures,
   RuntimeRegistration,
   SimfinityError,
+  ViewOptions,
 } from '@simtlix/simfinity-core';
 export {
   auth,
@@ -26,7 +27,9 @@ export {
   createRuntime,
   createValidatedScalar,
   InternalServerError,
+  MAX_RECORD_VERSION,
   plugins,
+  RecordVersion,
   scalars,
   SimfinityError,
   validators,
@@ -36,10 +39,13 @@ export type {
   AuthRule,
   AuthRuleFunction,
   AuthSchemaPlugin,
+  ConcurrencyDeclaration,
   CreateSchemaOptions,
   EnvelopSchemaPlugin,
   FieldValidations,
   FieldValidator,
+  FilterCondition,
+  FilterGroup,
   ItemValidators,
   MutationLimitsOptions,
   PermissionSchema,
@@ -49,6 +55,9 @@ export type {
   ScopeParams,
   TypePermissions,
   TypeScopes,
+  ViewOptions,
+  ViewParam,
+  ViewParamType,
   VirtualFieldDeclaration,
   VirtualFieldOptions,
 } from '@simtlix/simfinity-core';
@@ -91,6 +100,8 @@ 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
    * operators compile to escaped regular expressions: `ILIKE` unanchored, `STARTS_WITH` and
@@ -121,6 +132,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[];
 
@@ -227,6 +247,14 @@ export function registerCustomQuery(
   callback: (input: any, context: any) => any,
 ): void;
 
+/**
+ * Register a named view: a root query field that returns the type's list with the generated list
+ * arguments plus the view's params, and appends the groups of `where` after middleware. Throws
+ * `INVALID_VIEW` (500) for an invalid declaration and `QUERY_NAME_CONFLICT` (500) for a name already
+ * registered as a view (see the core `Runtime.registerView`).
+ */
+export function registerView(name: string, options: ViewOptions): void;
+
 /** Operation context for root operations, generated non-embedded relation reads, and nested collection writes. */
 export interface SimfinityMiddlewareContext {
   args: any;