@simtlix/simfinity-js 3.5.2 → 3.5.5

package/README.md

@@ -24,6 +24,8 @@ Generated single-reference reads can be batched within a request. Models with an
 
 Generated models store enum internal values with their own type (numbers, booleans or strings; other combinations as given) and support embedded fields named `type`. 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).
 
+The facade registers generated models on your application's default Mongoose instance and does not change global Mongoose options such as `strictQuery`. `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.
 
 ## Optional transactional reference integrity

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simtlix/simfinity-js",
-  "version": "3.5.2",
+  "version": "3.5.5",
   "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.5.2",
-    "@simtlix/simfinity-mcp": "3.5.2"
+    "@simtlix/simfinity-core": "3.5.5",
+    "@simtlix/simfinity-mcp": "3.5.5"
   },
   "files": [
     "src",

package/src/index.js

@@ -12,6 +12,7 @@ const mongoAdapter = createMongoAdapter();
 const runtime = createRuntime(mongoAdapter);
 
 export const configureQueryLimits = runtime.configureQueryLimits;
+export const configureMutationLimits = runtime.configureMutationLimits;
 export const connect = runtime.connect;
 export const addNoEndpointType = runtime.addNoEndpointType;
 export const createSchema = runtime.createSchema;

package/src/mongo/adapter.js

@@ -1,15 +1,41 @@
 import mongoose from 'mongoose';
-import { getNamedType, isListType, isNonNullType } from 'graphql';
+import { getListShape, normalizeConnectionField } from '@simtlix/simfinity-core/internal/relation-storage';
 
 import { createMongoModel } from './models.js';
 import { createMongoQueries } from './queries.js';
 import { withMongoTransaction } from './transactions.js';
 import { createMongoIntegrity } from './integrity.js';
-
-mongoose.set('strictQuery', false);
+import {
+  castModelId, castObjectId, castPathValue, invalidId, isQueryKeyCastFailure, mapIdCastError,
+} from './ids.js';
 
 const withSession = (query, session) => (session ? query.session(session) : query);
 
+// A write that fails only on malformed ObjectId values reports NOT_VALID_ID, not a driver error.
+const mapIdCastErrors = async (write) => {
+  try {
+    return await write();
+  } catch (error) {
+    throw mapIdCastError(error);
+  }
+};
+
+// By-ID queries take the raw ID, so the model's setters and key cast run once, in Mongoose's own
+// query lifecycle. Keep the chainable Query and map a failed key cast only when it runs; with
+// `mapError`, also map other failures, such as malformed ObjectId values in an update.
+const mapQueryIdCastErrors = (query, mapError = (error) => error) => {
+  const { exec } = query;
+  if (typeof exec !== 'function') return query;
+  query.exec = async function execMappingIdCasts(...args) {
+    try {
+      return await exec.apply(this, args);
+    } catch (error) {
+      throw isQueryKeyCastFailure(this, error) ? invalidId() : mapError(error);
+    }
+  };
+  return query;
+};
+
 // Even a shared hook can branch on `this.op` or the filter shape. Preserve findOne semantics
 // whenever either query operation has hooks instead of inferring equivalence from function identity.
 const hasNoFindHooks = (hooks) => {
@@ -45,20 +71,15 @@ export const createMongoAdapter = (options) => {
       for (const registration of registrations) {
         for (const field of Object.values(registration.gqltype.getFields())) {
           const relation = field.extensions?.relation;
-          const listType = isNonNullType(field.type) ? field.type.ofType : field.type;
-          if (!relation?.connectionField || relation.embedded || !isListType(listType)) continue;
-          const childType = getNamedType(field.type);
-          const childFields = childType.getFields();
-          const connectionExists = childFields[relation.connectionField]
-            || Object.entries(childFields).some(([fieldName, childField]) => {
-              const childRelation = childField.extensions?.relation;
-              return childRelation && !childRelation.embedded
-                && (childRelation.connectionField || fieldName) === relation.connectionField;
-            });
-          if (!connectionExists) addPrivateConnectionField(
-            childType.name,
-            relation.connectionField,
-          );
+          const listShape = getListShape(field.type);
+          if (!relation?.connectionField || relation.embedded || !listShape) continue;
+          // Same rule as core: only a direct or aliased singular reference on the child stores the
+          // link. Otherwise, including a child collection that reuses the name (chained or
+          // self-referencing collections), the child gets a private ObjectId field.
+          const connection = normalizeConnectionField(listShape.itemType, relation.connectionField);
+          if (!connection.graphqlFieldName) {
+            addPrivateConnectionField(listShape.itemType.name, connection.storageFieldName);
+          }
         }
       }
     },
@@ -71,9 +92,8 @@ export const createMongoAdapter = (options) => {
         if (onModelCreated) onModelCreated(model);
       }, integrity.enabled ? { ...modelOptions, createCollection: false } : modelOptions);
     },
-    castId(value) {
-      return new mongoose.Types.ObjectId(value);
-    },
+    // Relation inputs and batch keys: only an ObjectId or its hex form, never a newly minted one.
+    castId: castObjectId,
     initialize: integrity.initialize,
     withTransaction: integrity.enabled ? integrity.withTransaction : withMongoTransaction,
     newRecord(Model, data, session) {
@@ -83,17 +103,27 @@ export const createMongoAdapter = (options) => {
     },
     saveRecord(Model, record, session) {
       if (integrity.enabled) return integrity.saveRecord(Model, record, session === undefined ? record.$session() : session);
-      return record.save();
+      return mapIdCastErrors(() => record.save());
     },
     toObject(record) {
       return typeof record?.toObject === 'function' ? record.toObject() : record;
     },
+    // A hydrated document renders a singular embedded path as an object even when the stored value
+    // is an explicit null. Only that stored null reads as null; an absent value keeps Mongoose's
+    // materialized object, as legacy documents rely on.
+    readEmbeddedValue(value) {
+      // The nested accessor's toJSON is called without a receiver on purpose. It reads the schema's
+      // toJSON virtuals option from `this` (guarded by `this &&`), and with that option set a stored
+      // null renders as `{}`. Without a receiver it reads the raw path value of its own document.
+      return value?.$__isNested === true && typeof value.toJSON === 'function' && value.toJSON.call(null) === null
+        ? null : value;
+    },
     getById(Model, id, session, { projection, plain, requiredId } = {}) {
       integrity.assertReady();
       let query = withSession(requiredId == null ? Model.findById(id, projection)
         : Model.findOne({ $and: [{ _id: requiredId }, { _id: id }] }, projection), session);
       if (plain) query = query.lean();
-      return query;
+      return mapQueryIdCastErrors(query);
     },
     getByIds(Model, ids) {
       integrity.assertReady();
@@ -108,19 +138,22 @@ export const createMongoAdapter = (options) => {
     },
     update(Model, id, update, session) {
       if (integrity.enabled) return integrity.updateRecord(Model, id, update, session);
-      return withSession(Model.findByIdAndUpdate(id, update, { new: true }), session);
+      return mapQueryIdCastErrors(withSession(
+        Model.findByIdAndUpdate(id, update, { new: true }), session,
+      ), mapIdCastError);
     },
     delete(Model, id, session) {
       if (integrity.enabled) {
         integrity.assertWrite(Model, session);
         return integrity.deleteRecord(Model, id, session);
       }
-      return withSession(Model.findByIdAndDelete(id), session);
+      return mapQueryIdCastErrors(withSession(Model.findByIdAndDelete(id), session));
     },
     async find(Model, gqltype, args, session, { requiredId } = {}) {
       integrity.assertReady();
       const pipeline = await queries.buildQuery(args, gqltype);
-      if (requiredId != null) pipeline.unshift({ $match: { _id: Model.schema.path('_id').cast(requiredId) } });
+      // 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);
       return withSession(Model.aggregate(pipeline), session);
     },
@@ -138,8 +171,15 @@ export const createMongoAdapter = (options) => {
     async findChildren(Model, gqltype, connectionField, parentId, args, session) {
       integrity.assertReady();
       const pipeline = await queries.buildQuery(args, gqltype);
-      const path = Model.schema.path(connectionField);
-      pipeline.unshift({ $match: { [connectionField]: path ? path.cast(parentId) : parentId } });
+      let parentKey;
+      try {
+        parentKey = castPathValue(Model.schema.path(connectionField), parentId);
+      } catch (error) {
+        // A stored parent key that the connection path cannot cast has no children.
+        if (error?.extensions?.code === 'NOT_VALID_ID') return [];
+        throw error;
+      }
+      pipeline.unshift({ $match: { [connectionField]: parentKey } });
       return withSession(Model.aggregate(pipeline), session);
     },
   };

package/src/mongo/ids.js

@@ -0,0 +1,60 @@
+import mongoose from 'mongoose';
+import { SimfinityError } from '@simtlix/simfinity-core';
+
+// Identifier casts shared by the adapter, the query builder and the integrity layer. A malformed
+// identifier is the client's error, so it becomes NOT_VALID_ID (400) instead of a driver error, and
+// the message never echoes the value.
+
+export const invalidId = () => new SimfinityError('Invalid identifier', 'NOT_VALID_ID', 400);
+
+// Names also match a CastError or BSONError from another mongoose or bson copy used by a supplied model.
+const isCastFailure = (error) => error?.name === 'CastError' || error?.name === 'BSONError';
+
+// Accepts only an ObjectId or its 24-character hex form, so a missing or numeric value never mints a
+// new identifier.
+export const castObjectId = (value) => {
+  try {
+    if (mongoose.isObjectIdOrHexString(value)) return new mongoose.Types.ObjectId(value);
+  } catch {
+    // Fall through: an ObjectId-like value that does not convert is malformed.
+  }
+  throw invalidId();
+};
+
+// Casts with the model's own path type, as Mongoose would at query time, so supplied models with a
+// String or Number key keep working. Mongoose matches nothing for null or undefined.
+export const castPathValue = (schemaType, value) => {
+  if (value == null || !schemaType) return value;
+  try {
+    return schemaType.cast(value);
+  } catch (error) {
+    if (isCastFailure(error)) throw invalidId();
+    throw error;
+  }
+};
+
+export const castModelId = (Model, value) => castPathValue(Model.schema.path('_id'), value);
+
+// A Mongoose query casts its filter, with the model's setters, when it runs, and keeps a failure as
+// its error flag. A failed cast of the record key there is a malformed identifier, whatever the key
+// type; a key cast failure in an update document, or an error that error middleware substitutes, is not.
+export const isQueryKeyCastFailure = (query, error) => error?.name === 'CastError' && error.path === '_id'
+  && typeof query?.error === 'function' && query.error() === error;
+
+// A write that fails only because ObjectId values do not cast: an ObjectId CastError, an embedded or
+// array cast wrapping one, or a ValidationError made only of such casts. Any other failure keeps its
+// own error.
+const isObjectIdCastFailure = (error) => {
+  if (error?.name === 'CastError') {
+    if (error.kind === 'ObjectId') return true;
+    const wraps = error.kind === 'embedded' || error.kind === 'Array' || /^\[.*\]$/.test(error.kind ?? '');
+    return wraps && isObjectIdCastFailure(error.reason);
+  }
+  if (error?.name === 'ValidationError') {
+    const nested = Object.values(error.errors ?? {});
+    return nested.length > 0 && nested.every(isObjectIdCastFailure);
+  }
+  return false;
+};
+
+export const mapIdCastError = (error) => (isObjectIdCastFailure(error) ? invalidId() : error);

package/src/mongo/integrity.js

@@ -1,6 +1,7 @@
 import mongoose from 'mongoose';
 import { describeModels, SimfinityError } from '@simtlix/simfinity-core';
 import { withMongoTransaction } from './transactions.js';
+import { castModelId, mapIdCastError } from './ids.js';
 
 const LOCK_FIELD = '_simfinityReferenceLock';
 // Startup audit bounds: distinct target ids checked per query and ids remembered per target.
@@ -108,7 +109,8 @@ export const createMongoIntegrity = (options = {}) => {
         // A caller must not catch that error and commit a borrowed transaction.
         try { await session.abortTransaction(); } catch { /* Preserve the write error and retry labels. */ }
       }
-      throw error;
+      // A malformed identifier is reported as NOT_VALID_ID; the transaction is still aborted.
+      throw mapIdCastError(error);
     }
   };
 
@@ -254,10 +256,12 @@ export const createMongoIntegrity = (options = {}) => {
         return saved;
       });
     },
+    // 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) {
       assertWrite(Model, session);
       return abortOnWriteError(session, async () => {
-        const objectId = Model.schema.path('_id').cast(id);
+        const objectId = castModelId(Model, id);
         const updated = await Model.findByIdAndUpdate(objectId, update, { new: true }).session(session);
         if (!updated) {
           // A middleware can hide a completed write with a null result. Abort
@@ -272,7 +276,7 @@ export const createMongoIntegrity = (options = {}) => {
     },
     async deleteRecord(Model, id, session) {
       return abortOnWriteError(session, async () => {
-        const objectId = Model.schema.path('_id').cast(id);
+        const objectId = castModelId(Model, id);
         if (!await lock(Model, objectId, session)) return null;
         for (const reference of incoming.get(Model) || []) {
           const query = reference.Model === Model

package/src/mongo/models.js

@@ -11,6 +11,7 @@ import {
   GraphQLString,
 } from 'graphql';
 import mongoose from 'mongoose';
+import { getFieldStorageName } from '@simtlix/simfinity-core/internal/relation-storage';
 
 const isNonNullOfType = (fieldEntryType, graphQLType) => (
   fieldEntryType instanceof GraphQLNonNull && fieldEntryType.ofType instanceof graphQLType
@@ -90,8 +91,7 @@ const generateSchemaDefinition = (gqlType, nested = false) => {
     } else if (type instanceof GraphQLObjectType || isNonNullOfType(type, GraphQLObjectType)) {
       if (fieldEntry.extensions && fieldEntry.extensions.relation) {
         if (!fieldEntry.extensions.relation.embedded) {
-          const key = fieldEntry.extensions.relation.connectionField || fieldEntry.name;
-          schemaArg[key] = mongoose.Schema.Types.ObjectId;
+          schemaArg[getFieldStorageName(fieldEntryName, fieldEntry)] = mongoose.Schema.Types.ObjectId;
         } else {
           const entryType = unwrapNonNull(type);
           if (entryType === gqlType) {

package/src/mongo/queries.js

@@ -9,15 +9,17 @@ import {
 import mongoose from 'mongoose';
 
 import { SimfinityError, QLOperator, paginationStages } from '@simtlix/simfinity-core';
+import {
+  getFieldStorageName, getListShape, hasStoredIdentity, normalizeConnectionField,
+} from '@simtlix/simfinity-core/internal/relation-storage';
 
+import { castObjectId } from './ids.js';
 import { resolveStorageScalar } from './models.js';
 
 const isNonNullOfType = (fieldEntryType, graphQLType) => (
   fieldEntryType instanceof GraphQLNonNull && fieldEntryType.ofType instanceof graphQLType
 );
 
-const unwrapNonNull = (type) => (type instanceof GraphQLNonNull ? type.ofType : type);
-
 const unwrapListAndNonNull = (type) => {
   let unwrapped = type;
   while (unwrapped instanceof GraphQLList || unwrapped instanceof GraphQLNonNull) {
@@ -26,28 +28,6 @@ const unwrapListAndNonNull = (type) => {
   return unwrapped;
 };
 
-const isListType = (type) => unwrapNonNull(type) instanceof GraphQLList;
-
-const getFieldStorageName = (fieldName, field) => {
-  const relation = field.extensions?.relation;
-  return relation && !relation.embedded && !isListType(field.type)
-    ? relation.connectionField || fieldName
-    : fieldName;
-};
-
-const getConnectionStorageName = (childType, declaredFieldName) => {
-  const childFields = childType.getFields();
-  if (childFields[declaredFieldName]) {
-    return getFieldStorageName(declaredFieldName, childFields[declaredFieldName]);
-  }
-  const aliasedField = Object.entries(childFields).find(([fieldName, field]) => (
-    getFieldStorageName(fieldName, field) === declaredFieldName
-  ));
-  return aliasedField
-    ? getFieldStorageName(aliasedField[0], aliasedField[1])
-    : declaredFieldName;
-};
-
 const getEffectiveTypeName = (type) => (
   type instanceof GraphQLScalarType ? resolveStorageScalar(type).name : type.name
 );
@@ -153,6 +133,19 @@ const queryNamedType = (type) => {
   return result;
 };
 
+// `id` is the record key `_id` at an entity boundary: the root or a joined document. Inside an
+// embedded object it follows what reads return. Entity types read the stored subdocument `_id`
+// through the generated id resolver; that resolver lives on the type object, so any runtime that
+// marked the type an entity decides it, not only this one. Every other embedded object stores and
+// returns its declared `id` member. A supplied subdocument schema without an `id` path keeps `_id`,
+// which only hydrated reads expose, through Mongoose's `id` virtual; list reads return null for it.
+const identifierLeaf = (model, schemaPath, gqltype) => {
+  if (!schemaPath) return '_id';
+  const schema = model?.schema;
+  if (!schema?.path(`${schemaPath}._id`)) return 'id';
+  return hasStoredIdentity(gqltype) || !schema.path(`${schemaPath}.id`) ? '_id' : 'id';
+};
+
 // Resolve GraphQL paths and storage paths together; supplied models own ID casting.
 const resolveQueryPath = (gqltype, path, aggregationsIncluded) => {
   assertValidFilterPath(path);
@@ -176,9 +169,11 @@ const resolveQueryPath = (gqltype, path, aggregationsIncluded) => {
       } else {
         const relatedModel = getModel(fieldType);
         if (!relatedModel) throw filterError(`Related model is not available for ${path}`, 'INVALID_FILTER_PATH');
-        const isList = unwrapNonNull(field.type) instanceof GraphQLList;
-        const declaredField = relation.connectionField || part;
-        const connField = isList ? getConnectionStorageName(fieldType, declaredField) : declaredField;
+        const isList = !!getListShape(field.type);
+        // A collection without connectionField keeps reading through its field name, as before.
+        const connField = isList
+          ? normalizeConnectionField(fieldType, relation.connectionField || part).storageFieldName
+          : getFieldStorageName(part, field);
         const localLeaf = isList ? '_id' : connField;
         const alias = allocateLookupAlias(aggregationsIncluded, parts.slice(0, index + 1).join('.'));
         aggregateClauses[alias] = buildRelationLookup({
@@ -194,7 +189,7 @@ const resolveQueryPath = (gqltype, path, aggregationsIncluded) => {
       currentType = fieldType;
     } else {
       if (index !== parts.length - 1) throw filterError(`Cannot traverse scalar field in ${path}`, 'INVALID_FILTER_PATH');
-      const leaf = part === 'id' ? '_id' : part;
+      const leaf = part === 'id' ? identifierLeaf(currentModel, schemaPath, currentType) : part;
       const storagePath = schemaPath ? `${schemaPath}.${leaf}` : leaf;
       return {
         mongoPath: mongoPath ? `${mongoPath}.${leaf}` : leaf,
@@ -228,7 +223,7 @@ const castFilterValue = (value, resolved) => {
       if (Number.isNaN(date.getTime())) throw new Error('Invalid date');
       return date;
     }
-    if (scalar === GraphQLID && !schemaType) return new mongoose.Types.ObjectId(value);
+    if (scalar === GraphQLID && !schemaType) return castObjectId(value);
     if (scalar instanceof GraphQLEnumType) {
       const entry = scalar.getValues().find((item) => item.name === value)
         || scalar.getValues().find((item) => item.value === value);
@@ -289,9 +284,9 @@ const buildQueryTerms = async (filterField, qlField, fieldName, gqltype, aggrega
 
 const MAX_FILTER_GROUP_DEPTH = 5;
 
-const validateLogicalLists = (group) => {
+const validateLogicalLists = (group, keys = ['AND', 'OR', 'conditions']) => {
   if (!group || typeof group !== 'object' || Array.isArray(group)) throw filterError('Expected a filter group object');
-  for (const key of ['AND', 'OR', 'conditions']) {
+  for (const key of keys) {
     if (group[key] != null && !Array.isArray(group[key])) throw filterError(`${key} requires an array`);
   }
 };
@@ -367,17 +362,21 @@ const buildFilterGroupMatch = async (filterGroup, gqltype, aggregateClauses, agg
   return { $and: parts };
 };
 
-const RESERVED_QUERY_KEYS = new Set(['pagination', 'sort', 'AND', 'OR', 'aggregation']);
+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) => {
-  validateLogicalLists(input);
+const collectFiltersAndLookups = async (input, gqltype, aggregateClauses, aggregationsIncluded, operation = 'find') => {
+  // 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;
   const flatMatchConditions = {};
   const repeatedConditions = [];
   let hasFlat = false;
   const fields = gqltype.getFields();
 
   for (const [key, filterField] of Object.entries(input)) {
-    if (RESERVED_QUERY_KEYS.has(key)) continue;
+    if (controlKeys.has(key)) continue;
     const qlField = fields[key];
     const result = await buildQueryTerms(filterField, qlField, key, gqltype, aggregationsIncluded);
     if (!result) continue;
@@ -448,7 +447,7 @@ const buildQuery = async (input, gqltype, isCount) => {
   const aggregationsIncluded = {};
   const paging = paginationStages(input.pagination, true);
 
-  const matchStage = await collectFiltersAndLookups(input, gqltype, aggregateClauses, aggregationsIncluded);
+  const matchStage = await collectFiltersAndLookups(input, gqltype, aggregateClauses, aggregationsIncluded, 'find');
   if (matchStage) aggregateClauses.push(matchStage);
 
   if (isCount) {
@@ -476,7 +475,7 @@ const buildAggregationQuery = async (input, gqltype, aggregationExpression) => {
   const aggregationsIncluded = {};
   const paging = paginationStages(input.pagination, false);
 
-  const matchStage = await collectFiltersAndLookups(input, gqltype, aggregateClauses, aggregationsIncluded);
+  const matchStage = await collectFiltersAndLookups(input, gqltype, aggregateClauses, aggregationsIncluded, 'aggregate');
   if (matchStage) aggregateClauses.push(matchStage);
 
   const { groupId, facts } = aggregationExpression ?? {};

package/src/mongo/transactions.js

@@ -3,6 +3,23 @@ import { SimfinityError } from '@simtlix/simfinity-core';
 
 const MAX_TRANSIENT_RETRIES = 5;
 const MAX_COMMIT_RETRIES = 5;
+// Full-jitter exponential backoff before each complete-transaction retry: a uniform wait below
+// 10, 20, 40, 80 and 160 ms, so conflicting transactions do not retry in lock-step.
+const RETRY_BASE_DELAY_MS = 10;
+const WRITE_CONFLICT = 112;
+
+const retryDelay = (attempt) => Math.random() * RETRY_BASE_DELAY_MS * 2 ** attempt;
+const sleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); });
+const isWriteConflict = (error) => error?.code === WRITE_CONFLICT || error?.codeName === 'WriteConflict';
+
+// Same code and status as PostgreSQL's exhausted serialization and deadlock retries. The driver
+// error stays available to logging, as on InternalServerError.
+const retryExceeded = (error) => {
+  const exceeded = new SimfinityError('Concurrent write could not be completed', 'TRANSACTION_RETRY_EXCEEDED', 409);
+  exceeded.cause = error;
+  exceeded.getCause = () => exceeded.cause;
+  return exceeded;
+};
 
 const commitWithRetry = async (session) => {
   for (let attempt = 0; ; attempt++) {
@@ -45,7 +62,7 @@ export const withMongoTransaction = async (session, body, model, transactionOpti
     ? await mongoose.startSession() : await connection.startSession();
   let failed = false;
   try {
-    for (let attempt = 0; attempt <= MAX_TRANSIENT_RETRIES; attempt++) {
+    for (let attempt = 0; ; attempt++) {
       if (transactionOptions) await mySession.startTransaction(transactionOptions);
       else await mySession.startTransaction();
       try {
@@ -65,14 +82,16 @@ export const withMongoTransaction = async (session, body, model, transactionOpti
             throw error;
           }
         }
-        const isTransient = error?.errorLabels?.includes('TransientTransactionError');
-        if (isTransient && attempt < MAX_TRANSIENT_RETRIES) {
+        if (!error?.errorLabels?.includes('TransientTransactionError')) throw error;
+        if (attempt < MAX_TRANSIENT_RETRIES) {
+          // Wait only once the failed attempt is aborted, so its locks are not held meanwhile.
+          await sleep(retryDelay(attempt));
           continue;
         }
-        throw error;
+        // Other exhausted transient failures (network, NoSuchTransaction) are not concurrency.
+        throw isWriteConflict(error) ? retryExceeded(error) : error;
       }
     }
-    throw new SimfinityError('Transaction exceeded retry limit', 'TRANSACTION_RETRY_EXCEEDED', 500);
   } catch (error) {
     failed = true;
     throw error;

package/types/index.d.ts

@@ -14,6 +14,7 @@ import type {
 } from 'graphql';
 import type {
   DatabaseAdapter,
+  MutationLimitsOptions,
   RuntimeRegistration,
   SimfinityError,
 } from '@simtlix/simfinity-core';
@@ -35,9 +36,14 @@ export type {
   EnvelopSchemaPlugin,
   FieldValidations,
   FieldValidator,
+  MutationLimitsOptions,
   PermissionSchema,
   PolicyExpression,
+  ScopeFunction,
+  ScopeOperation,
+  ScopeParams,
   TypePermissions,
+  TypeScopes,
 } from '@simtlix/simfinity-core';
 export * from '@simtlix/simfinity-mcp';
 export { default as mcp } from '@simtlix/simfinity-mcp';
@@ -47,6 +53,14 @@ export interface MongoAdapterOptions {
 }
 export interface MongoAdapter extends DatabaseAdapter {
   readonly referentialIntegrity: 'off' | 'transactional';
+  /**
+   * Accepts only an ObjectId or a 24-character hexadecimal string, normalized to lowercase, and
+   * throws `NOT_VALID_ID` (400) for anything else, including undefined, null and numbers. It never
+   * creates an identifier; use `new mongoose.Types.ObjectId()` for that.
+   */
+  castId(value: any): any;
+  /** Returns null for a hydrated nested path whose stored value is an explicit null; otherwise the value. */
+  readEmbeddedValue(value: any): any;
   /** After connecting MongoDB and createSchema(), await the transaction capability and existing-reference audit. */
   initialize(): Promise<void>;
 }
@@ -74,7 +88,12 @@ export interface StateMachine {
   [key: string]: any;
 }
 
-/** Register a Mongoose model + GraphQL type pair, exposing single and list endpoints. */
+/**
+ * Register a Mongoose model + GraphQL type pair, exposing single and list endpoints.
+ * Throws INVALID_SCOPE (500) for an invalid `extensions.scope`, and TYPE_BOUND_TO_OTHER_RUNTIME
+ * (409) when another runtime bound the type by generating its relation resolvers, or reserved it
+ * because its schema reached the type with an unresolved relation field.
+ */
 export function connect(
   model: any,
   gqltype: GraphQLObjectType,
@@ -85,13 +104,21 @@ export function connect(
   stateMachine?: StateMachine | null,
 ): void;
 
-/** Register a GraphQL type without exposing root endpoints (e.g. embedded/related types). */
+/** Register a GraphQL type without exposing root endpoints (e.g. embedded/related types). Throws like connect(). */
 export function addNoEndpointType(gqltype: GraphQLObjectType): void;
 
 /**
  * Build the executable GraphQLSchema from every connected type. The first two
  * allowlists are matched against the GraphQLObjectType INSTANCES passed to
- * connect(); only custom mutations are matched by name.
+ * connect(); only custom mutations are matched by name. Scopes are validated
+ * (INVALID_SCOPE), and reachable types bound or reserved by another runtime, or
+ * holding a field copied with toConfig() after another runtime generated its
+ * relation resolver, keeping the generated resolver or its extensions, are rejected (TYPE_BOUND_TO_OTHER_RUNTIME), before models
+ * are created; a list or embedded relation to an unregistered type throws
+ * UNREGISTERED_RELATION_TARGET. A writable non-embedded list relation without a child
+ * connectionField, whose resolver Simfinity would generate, throws INVALID_MODEL (400). In default
+ * mode, one with its own resolver or readOnly only logs a warning and rejects nested writes
+ * (INVALID_MODEL, 500); referentialIntegrity 'transactional' rejects every such collection.
  */
 export function createSchema(
   includedQueryTypes?: GraphQLObjectType[] | null,
@@ -122,6 +149,10 @@ export interface SimfinityMiddlewareContext {
  * Register middleware before generated operations, including related-type reads and nested child writes.
  * Nested operations keep root argument shapes and the GraphQL request context.
  * Await next() to advance the middleware chain; throw to reject before the operation executes.
+ * A non-function throws INVALID_MIDDLEWARE (500). The rest of the chain runs at most once and is
+ * awaited even when next() is not; its errors cancel the operation, even if a middleware catches them.
+ * Call next() before the middleware returns or its promise settles: a later call, such as
+ * setTimeout(next), does nothing, so the remaining middleware is skipped.
  */
 export function use(
   middleware: (
@@ -142,6 +173,15 @@ export interface QueryLimitsOptions {
 /** Configure at startup. Invalid configuration throws INVALID_QUERY_LIMITS (400). */
 export function configureQueryLimits(options?: QueryLimitsOptions): void;
 
+/**
+ * Process-wide limit on nested added/updated/deleted entries per generated add, update or
+ * state-action mutation; unlimited by default, restored by calling it without options.
+ * Invalid configuration, including an unknown or misspelled option key, throws
+ * INVALID_MUTATION_LIMITS (400) and keeps the current limit; a mutation over the limit
+ * fails with NESTED_OPERATIONS_EXCEEDED (400) before its transaction starts.
+ */
+export function configureMutationLimits(options?: MutationLimitsOptions): void;
+
 /**
  * Get the generated create input type, preserving field and list-item non-null
  * wrappers. Update inputs remove only the outer wrapper (except entity id).
@@ -157,7 +197,10 @@ export function getInputType(type: GraphQLObjectType | { name: string }): GraphQ
  * The caller then owns retries, commit, abort, and cleanup; inactive sessions are rejected.
  * Exception: transactional reference integrity aborts on a violation, guarded-write error or ambiguous update result.
  * That mode requires snapshot read concern and majority write concern on supplied transactions.
- * Owned transactions retry transient failures and uncertain commits separately, up to five times each.
+ * Owned transactions retry transient failures after a short randomized backoff, and uncertain commits
+ * immediately, up to five times each. An exhausted write conflict throws TRANSACTION_RETRY_EXCEEDED
+ * (409) with the driver error as `cause`; a supplied session receives the raw driver error.
+ * Relation inputs need `{ id }`; a missing or malformed ID throws NOT_VALID_ID (400).
  */
 
 export function saveObject(
@@ -192,7 +235,12 @@ export interface FilterGroupInput {
   [key: string]: any;
 }
 
-/** Translate list-query arguments (filters, AND/OR, sort, pagination) into a MongoDB aggregation pipeline. */
+/**
+ * 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
+ * built here. An embedded `.id` path uses the declared `id` member, except for entity types embedded
+ * as lists and supplied subdocument schemas without an `id` path, which use the subdocument `_id`.
+ */
 export function buildQuery(
   input: Record<string, any>,
   gqltype: GraphQLObjectType,