@simtlix/simfinity-js 3.5.8 → 3.6.0

package/README.md

@@ -20,11 +20,11 @@ const schema = simfinity.createSchema();
 
 Use a MongoDB replica set or sharded cluster for transactional mutations. The library requires Node.js >=18.18.0 and GraphQL 16.
 
-Generated single-reference reads can be batched within a request. Models with any `find` or `findOne` pre/post query hook retain individual `findOne` reads, including hooks shared by both operations, to preserve access restrictions and other middleware behavior. See the [relationship contract](https://simtlix.github.io/simfinity.js/guide/relationships.html).
+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).
 
-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).
+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).
 
-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).
+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. `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.
 
@@ -50,7 +50,7 @@ Owned transactions use snapshot reads and majority commits. Supplied sessions ne
 
 The source now lives in `packages/mongodb` in the monorepo. Its public npm name remains `@simtlix/simfinity-js`; existing imports, including paths under `@simtlix/simfinity-js/src/`, retain their layout. Shared helpers, error identities and MCP compatibility exports are preserved. Internal Simfinity dependencies use the same exact release version.
 
-The legacy `src/` deep imports have no TypeScript declarations. In TypeScript, import `auth`, `plugins`, `scalars` and `validators` from the package root. Importing the typed `@simtlix/simfinity-core` subpaths, such as `@simtlix/simfinity-core/auth`, instead needs `@simtlix/simfinity-core` as a direct dependency pinned to this package's exact version.
+Its legacy `src/` modules that re-export public API (`src/index.js`, `src/auth/index.js`, `src/auth/errors.js`, `src/auth/expressions.js`, `src/auth/rules.js`, `src/plugins.js`, `src/scalars.js`, `src/validators.js`, `src/mcp.js`, `src/const/*.js`, `src/errors/*.js`, and their extensionless aliases) ship TypeScript declarations with the types of the package root and the matching `@simtlix/simfinity-core` subpaths; `src/mongo/*` is internal and undeclared. New code should still import `auth`, `plugins`, `scalars` and `validators` from the package root. Importing the typed `@simtlix/simfinity-core` subpaths, such as `@simtlix/simfinity-core/auth`, instead needs `@simtlix/simfinity-core` as a direct dependency pinned to this package's exact version.
 
 For tooling that locates the package, use `require.resolve('@simtlix/simfinity-js/package.json')` or the package root without a trailing slash. Directory specifiers ending in `/` were not valid ESM imports and are not supported by the export map, including in `require.resolve`; use explicit filenames such as `src/auth/index.js`.
 

package/package.json

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

package/src/auth/errors.d.ts

@@ -0,0 +1,2 @@
+export * from '@simtlix/simfinity-core/auth/errors';
+export { default } from '@simtlix/simfinity-core/auth/errors';

package/src/auth/expressions.d.ts

@@ -0,0 +1,2 @@
+export * from '@simtlix/simfinity-core/auth/expressions';
+export { default } from '@simtlix/simfinity-core/auth/expressions';

package/src/auth/index.d.ts

@@ -0,0 +1,2 @@
+export * from '@simtlix/simfinity-core/auth';
+export { default } from '@simtlix/simfinity-core/auth';

package/src/auth/rules.d.ts

@@ -0,0 +1,2 @@
+export * from '@simtlix/simfinity-core/auth/rules';
+export { default } from '@simtlix/simfinity-core/auth/rules';

package/src/const/QLOperator.d.ts

@@ -0,0 +1,2 @@
+/** Declarations for the legacy `@simtlix/simfinity-js/src/const/QLOperator.js` deep import: core's `QLOperator`. */
+export { QLOperator as default } from '@simtlix/simfinity-core';

package/src/const/QLSort.d.ts

@@ -0,0 +1,2 @@
+/** Declarations for the legacy `@simtlix/simfinity-js/src/const/QLSort.js` deep import: core's `QLSort`. */
+export { QLSort as default } from '@simtlix/simfinity-core';

package/src/const/QLValue.d.ts

@@ -0,0 +1,2 @@
+/** Declarations for the legacy `@simtlix/simfinity-js/src/const/QLValue.js` deep import: core's `QLValue`. */
+export { QLValue as default } from '@simtlix/simfinity-core';

package/src/errors/internal-server.error.d.ts

@@ -0,0 +1,2 @@
+/** Declarations for the legacy `@simtlix/simfinity-js/src/errors/internal-server.error.js` deep import: core's `InternalServerError`. */
+export { InternalServerError as default } from '@simtlix/simfinity-core';

package/src/errors/simfinity.error.d.ts

@@ -0,0 +1,2 @@
+/** Declarations for the legacy `@simtlix/simfinity-js/src/errors/simfinity.error.js` deep import: core's `SimfinityError`. */
+export { SimfinityError as default } from '@simtlix/simfinity-core';

package/src/index.d.ts

@@ -0,0 +1,2 @@
+/** Declarations for the legacy `@simtlix/simfinity-js/src/index.js` (and `src`) deep import: the package root. */
+export * from '../types/index.js';

package/src/mcp.d.ts

@@ -0,0 +1,3 @@
+/** Declarations for the legacy `@simtlix/simfinity-js/src/mcp.js` deep import, which re-exports `@simtlix/simfinity-mcp`. */
+export * from '@simtlix/simfinity-mcp';
+export { default } from '@simtlix/simfinity-mcp';

package/src/mongo/adapter.js

@@ -39,22 +39,145 @@ const mapQueryIdCastErrors = (query, mapError = (error) => error) => {
 
 // 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) => {
+const hasNoHooks = (hooks, operations) => {
   if (!(hooks?._pres instanceof Map) || !(hooks._posts instanceof Map)) return false;
-  return ['find', 'findOne'].every((operation) => !hooks._pres.get(operation)?.length
+  return operations.every((operation) => !hooks._pres.get(operation)?.length
     && !hooks._posts.get(operation)?.length);
 };
 
-// getById reads through `findOne` and getByIds through `find`. Mongoose copies the schema's query
-// hooks to the model when compiling it, so both registries must allow the batched read.
-const batchesFindOne = (Model) => hasNoFindHooks(Model.schema?.s?.hooks)
-  && (Model.Query?.prototype?._queryMiddleware == null || hasNoFindHooks(Model.Query.prototype._queryMiddleware));
+// Mongoose copies the schema's query hooks to the model when compiling it, so both registries must
+// be free of hooks for the operations.
+const hasNoQueryHooks = (Model, operations) => hasNoHooks(Model.schema?.s?.hooks, operations)
+  && (Model.Query?.prototype?._queryMiddleware == null || hasNoHooks(Model.Query.prototype._queryMiddleware, operations));
+
+// getById reads through `findOne` and getByIds through `find`.
+const batchesFindOne = (Model) => hasNoQueryHooks(Model, ['find', 'findOne']);
+
+// The statics that getById, update and delete call, directly or through each other.
+const BY_ID_STATICS = ['findById', 'findOne', 'findByIdAndUpdate', 'findOneAndUpdate', 'findByIdAndDelete', 'findOneAndDelete'];
+// Mongoose's automatic ObjectId setter only changes document assignments, never query filters.
+const autoIdSetter = new mongoose.Schema.Types.ObjectId('_id').auto(true).setters.at(-1);
+
+// update and delete write through findByIdAndUpdate and findByIdAndDelete, whose findOneAndUpdate and
+// findOneAndDelete middleware runs before Mongoose casts the ID. Such middleware, or an application
+// override of one of these statics (schema.static, loadClass), could guard the read or act on a
+// malformed ID that the read by ID rejects first, so the runtime keeps that read. ID setters also
+// run before casting and can branch on the query operation. A model from another Mongoose copy
+// has other statics and keeps the read too.
+const readsByIdAreInert = (Model) => BY_ID_STATICS.every((name) => Model[name] === mongoose.Model[name])
+  && Model.schema?.path('_id')?.setters?.every((setter) => setter === autoIdSetter)
+  && hasNoQueryHooks(Model, ['find', 'findOne', 'findOneAndUpdate', 'findOneAndDelete']);
+
+// `useDb()` connections share their parent's MongoClient, and a session belongs to a client.
+const clientOf = (connection) => connection.getClient?.() || connection;
+
+// Whether a schema lets Mongoose render a member inside an embedded object from something other
+// than its stored value: a getter on a path, a virtual, an alias or, on a subdocument, a method
+// (GraphQL's default resolver calls one named like a member), at any depth (nested paths,
+// subdocuments, document arrays, map values). Core cannot tell such an object's data without
+// running them, so rawEmbeddedValue leaves it unconverted and core keeps it. Read from schema
+// metadata only. The `id` virtual that Mongoose adds to a schema with an `_id` renders that `_id`,
+// which core reads itself, so it does not count; one the application declares does: it has another
+// getter, or the schema disables the automatic one.
+const isAutomaticIdVirtual = (schema, name, virtual) => name === 'id' && virtual?.getters?.length === 1
+  && schema.options?.id !== false && schema.paths._id !== undefined && schema.paths.id === undefined;
+const schemaTypeComputes = (schemaType, seen) => {
+  if (!(schemaType instanceof mongoose.SchemaType) || seen.has(schemaType)) return false;
+  seen.add(schemaType);
+  if (schemaType.getters?.length > 0) return true;
+  // schemaComputes is defined below: schemas and their paths contain each other.
+  if (schemaType.schema && schemaComputes(schemaType.schema, '', seen)) return true;
+  // Map values, array items and document array elements.
+  return [schemaType.$__schemaType, schemaType.$embeddedSchemaType, schemaType.caster]
+    .some((inner) => schemaTypeComputes(inner, seen));
+};
+// `prefix` is a nested path of the schema; '' is the whole schema, as a subdocument's own.
+const schemaComputes = (schema, prefix, seen) => {
+  if (prefix === '') {
+    if (seen.has(schema)) return false;
+    seen.add(schema);
+    // Nested paths get no schema methods; a subdocument's own schema can.
+    if (Object.keys(schema.methods ?? {}).length > 0) return true;
+  }
+  const inside = (path) => prefix === '' || path.startsWith(`${prefix}.`);
+  return Object.entries(schema.paths ?? {}).some(([path, schemaType]) => inside(path) && schemaTypeComputes(schemaType, seen))
+    || Object.entries(schema.virtuals ?? {}).some(([name, virtual]) => inside(name)
+      && !(prefix === '' && isAutomaticIdVirtual(schema, name, virtual)))
+    // An alias stores its value under another path, and may be declared outside a nested path.
+    || Object.entries(schema.aliases ?? {}).some(([alias, path]) => inside(alias) || inside(path));
+};
+// Schemas do not change once their models are compiled, so each answer is computed once.
+const computesCache = new WeakMap();
+const cachedComputes = (key, prefix, compute) => {
+  let byPrefix = computesCache.get(key);
+  if (!byPrefix) {
+    byPrefix = new Map();
+    computesCache.set(key, byPrefix);
+  }
+  if (!byPrefix.has(prefix)) byPrefix.set(prefix, compute());
+  return byPrefix.get(prefix);
+};
+const declaresComputedMembers = (schema, prefix) => cachedComputes(schema, prefix, () => schemaComputes(schema, prefix, new Set()));
+const declaresComputedValues = (schemaType) => cachedComputes(schemaType, '', () => schemaTypeComputes(schemaType, new Set()));
+// A hydrated nested path is cached by its full path in its document's internal getters cache, which
+// it shares; '' (the whole schema) if it is not found there.
+const nestedPathOf = (nested) => {
+  const cache = nested.$__?.getters;
+  return (cache && Object.keys(cache).find((path) => cache[path] === nested)) ?? '';
+};
 
 export const createMongoAdapter = (options) => {
   const integrity = createMongoIntegrity(options);
   let queries;
+  let getRegistrations = () => [];
   const privateConnectionFields = new Map();
 
+  // A registered custom mutation passes no model, so its owned session stays on the default
+  // mongoose.connection, as before. While that connection has never been opened (no client), a
+  // session there can only wait and time out. Use the one MongoDB client of the registered models
+  // instead, but only when nothing can need the default connection:
+  // - any model compiled on it, generated or the application's, registered or not, means the
+  //   application opens it, maybe after the request arrived, and the callback may write that
+  //   model with the session, which must then come from the default connection's client. The
+  //   same holds for a model compiled on any useDb() descendant of it, such as
+  //   mongoose.connection.useDb('tenant').useDb('audit'), which shares its client. A connection's
+  //   otherDbs lists its direct useDb() children, not theirs, so the walk follows otherDbs at any
+  //   depth.
+  //   useDb(name, { noListener: true }) leaves a connection out of its parent's otherDbs, so neither
+  //   it nor its descendants are seen, and native collection writes
+  //   (mongoose.connection.collection()) compile no model;
+  // - registered models on several clients have no single client to choose.
+  // Once the default connection has a client, nothing changes.
+  const hasModels = (connection) => Object.keys(connection.models).length > 0;
+  // A child's otherDbs also lists its parent, so the walk visits each connection once, cycles
+  // included: a Set iteration also visits the entries added while it runs.
+  const defaultClientHasModels = () => {
+    const seen = new Set([mongoose.connection]);
+    for (const connection of seen) {
+      if (hasModels(connection)) return true;
+      for (const other of connection.otherDbs) seen.add(other);
+    }
+    return false;
+  };
+  const sessionModel = () => {
+    if (mongoose.connection.getClient() || defaultClientHasModels()) return undefined;
+    let found;
+    for (const { model } of getRegistrations()) {
+      const connection = model?.db;
+      if (!connection) continue;
+      if (connection === mongoose.connection) return undefined;
+      if (!found) found = model;
+      else if (clientOf(found.db) !== clientOf(connection)) return undefined;
+    }
+    return found;
+  };
+
+  // A supplied session or model is used as is; only an owned session without a model looks up
+  // the registrations.
+  const withOwnedTransaction = (session, body, Model, ...rest) => withMongoTransaction(
+    session, body, (Model || session) ? Model : sessionModel(), ...rest,
+  );
+
   const addPrivateConnectionField = (typeName, fieldName) => {
     if (!privateConnectionFields.has(typeName)) privateConnectionFields.set(typeName, new Set());
     privateConnectionFields.get(typeName).add(fieldName);
@@ -63,6 +186,7 @@ export const createMongoAdapter = (options) => {
   const adapter = {
     bind(binding) {
       integrity.bind(binding);
+      getRegistrations = binding.getRegistrations;
       queries = createMongoQueries(binding);
       adapter.buildQuery = queries.buildQuery;
       adapter.buildFilterGroupMatch = queries.buildFilterGroupMatch;
@@ -103,7 +227,7 @@ export const createMongoAdapter = (options) => {
     // 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,
+    withTransaction: integrity.enabled ? integrity.withTransaction : withOwnedTransaction,
     newRecord(Model, data, session) {
       const record = new Model(data);
       record.$session(session);
@@ -118,7 +242,8 @@ export const createMongoAdapter = (options) => {
     },
     // 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.
+    // materialized object; core then reads it as null when its stored members (rawEmbeddedValue)
+    // hold no data and miss a required member (runtime.js readEmbeddedObject).
     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
@@ -126,6 +251,30 @@ export const createMongoAdapter = (options) => {
       return value?.$__isNested === true && typeof value.toJSON === 'function' && value.toJSON.call(null) === null
         ? null : value;
     },
+    // The stored data of a hydrated embedded value, which core reads to tell whether it holds data
+    // without running schema getters or virtuals: a nested path's raw value (its toJSON without a
+    // receiver, as above), a subdocument's _doc or a Mongoose map's entries. The first two hold an
+    // absent nested path as {}, as Mongoose renders it, and keep subdocuments and maps hydrated,
+    // which core passes back here. A subdocument's automatic `id` virtual is not in _doc; core reads
+    // `_id` for `id`. A value whose schema declares a getter, a virtual, an alias or a subdocument
+    // method on a member at any depth inside it (declaresComputedMembers) is returned unchanged, so core counts it as data
+    // and keeps it, as 3.5.8 rendered it; no getter runs. Generated models declare none. Any other
+    // value is returned unchanged too.
+    rawEmbeddedValue(value) {
+      if (value?.$__isNested === true) {
+        // A schema from another Mongoose copy cannot be inspected; keep the value as 3.5.8 did.
+        if (typeof value.toJSON !== 'function' || !(value.$__schema instanceof mongoose.Schema)
+          || declaresComputedMembers(value.$__schema, nestedPathOf(value))) return value;
+        return value.toJSON.call(null);
+      }
+      // Iterating a map reads its stored values; its get() would run the value getters.
+      if (value instanceof mongoose.Types.Map) {
+        return declaresComputedValues(value.$__schemaType) ? value : Object.fromEntries(value);
+      }
+      if (!(value instanceof mongoose.Document) || !value._doc) return value;
+      const schema = value.$__schema ?? value.schema;
+      return !schema || declaresComputedMembers(schema, '') ? value : value._doc;
+    },
     getById(Model, id, session, { projection, plain, requiredId } = {}) {
       integrity.assertReady();
       let query = withSession(requiredId == null ? Model.findById(id, projection)
@@ -141,6 +290,12 @@ export const createMongoAdapter = (options) => {
       // Trusted, so that the `sanitizeFilter` option does not wrap the operator in `$eq`.
       return Model.find({ _id: mongoose.trusted({ $in: ids }) });
     },
+    // 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,
+    // as it fails the read.
+    readByIdIsInert(Model) {
+      return readsByIdAreInert(Model);
+    },
     prepareUpdate(set, unset) {
       return Object.keys(unset).length > 0 ? { ...set, $unset: unset } : set;
     },

package/src/mongo/integrity.js

@@ -4,7 +4,7 @@ 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.
+// Distinct target ids per startup-audit query and per lock write, and ids the audit remembers per target.
 const AUDIT_BATCH_SIZE = 1000;
 const AUDIT_VERIFIED_LIMIT = 100000;
 const transactionOptions = { readConcern: { level: 'snapshot' }, writeConcern: { w: 'majority' } };
@@ -44,7 +44,10 @@ export const createMongoIntegrity = (options = {}) => {
   let ready = false;
   const models = new Map();
   const outgoing = new Map();
+  // Per target model: each referencing model once, with its paths to the target in declaration order.
   const incoming = new Map();
+  // Per model: _id and its reference paths, the fields modelReferences reads.
+  const projections = new Map();
 
   const assertRegistry = () => {
     const current = binding.getRegistrations();
@@ -100,6 +103,37 @@ export const createMongoIntegrity = (options = {}) => {
     return result.matchedCount > 0;
   };
 
+  // Lock the distinct targets of one record with one write per target collection (up to
+  // AUDIT_BATCH_SIZE ids each). A batch of several ids is read first in the transaction snapshot,
+  // so a missing target is a violation before the batch's write, whatever its position, and never
+  // a retried conflict with a concurrently locked target of the same batch. A single id keeps its
+  // single updateOne.
+  const lockTargets = async (references, session) => {
+    const byTarget = new Map();
+    for (const { target, id } of references) {
+      if (!byTarget.has(target)) byTarget.set(target, []);
+      byTarget.get(target).push(id);
+    }
+    for (const [target, ids] of byTarget) {
+      const Target = models.get(target);
+      for (let start = 0; start < ids.length; start += AUDIT_BATCH_SIZE) {
+        const batch = ids.slice(start, start + AUDIT_BATCH_SIZE);
+        if (batch.length === 1) {
+          if (!await lock(Target, batch[0], session)) throw violation();
+          continue;
+        }
+        const found = await Target.collection.find(
+          { _id: { $in: batch } }, { session, projection: { _id: 1 }, batchSize: batch.length + 1 },
+        ).toArray();
+        if (found.length !== batch.length) throw violation();
+        const result = await Target.collection.updateMany(
+          { _id: { $in: batch } }, { $set: { [LOCK_FIELD]: new mongoose.Types.ObjectId() } }, { session },
+        );
+        if (result.matchedCount !== batch.length) throw violation();
+      }
+    }
+  };
+
   const abortOnWriteError = async (session, body) => {
     try {
       return await body();
@@ -115,13 +149,12 @@ export const createMongoIntegrity = (options = {}) => {
   };
 
   const validateRecord = async (Model, record, session) => abortOnWriteError(session, async () => {
-    // Read the stored post-image, including setters/defaults and save middleware changes.
+    // Read the stored post-image, including setters/defaults and save middleware changes:
+    // only _id and the reference paths.
     if (!record?._id) throw violation();
-    const stored = await Model.collection.findOne({ _id: record._id }, { session });
+    const stored = await Model.collection.findOne({ _id: record._id }, { session, projection: projections.get(Model) });
     if (!stored) throw violation();
-    for (const { target, id } of modelReferences(Model, stored)) {
-      if (!await lock(models.get(target), id, session)) throw violation();
-    }
+    await lockTargets(modelReferences(Model, stored), session);
   });
 
   const initialize = async () => {
@@ -154,11 +187,16 @@ export const createMongoIntegrity = (options = {}) => {
     }
     if (!connection || connection.readyState !== 1) throw invalid('Connect MongoDB before initializing reference integrity');
     for (const [Model, paths] of outgoing) {
+      const projection = { _id: 1 };
       for (const reference of paths) {
+        const path = reference.path.join('.');
+        projection[path] = 1;
         const target = models.get(reference.target);
-        if (!incoming.has(target)) incoming.set(target, []);
-        incoming.get(target).push({ Model, path: reference.path.join('.') });
+        if (!incoming.has(target)) incoming.set(target, new Map());
+        if (!incoming.get(target).has(Model)) incoming.get(target).set(Model, []);
+        if (!incoming.get(target).get(Model).includes(path)) incoming.get(target).get(Model).push(path);
       }
+      projections.set(Model, projection);
     }
     for (const Model of models.values()) {
       if (createCollection) await Model.createCollection();
@@ -188,9 +226,7 @@ export const createMongoIntegrity = (options = {}) => {
     try {
       session.startTransaction({ readConcern: { level: 'snapshot' }, writeConcern: { w: 'majority' } });
       for (const Model of models.values()) {
-        const projection = { _id: 1, [LOCK_FIELD]: 1 };
-        for (const { path } of outgoing.get(Model)) projection[path.join('.')] = 1;
-        const cursor = Model.collection.find({}, { session, projection });
+        const cursor = Model.collection.find({}, { session, projection: { ...projections.get(Model), [LOCK_FIELD]: 1 } });
         try {
           for await (const record of cursor) {
             if (record[LOCK_FIELD] != null && record[LOCK_FIELD]?._bsontype !== 'ObjectId') {
@@ -278,11 +314,15 @@ export const createMongoIntegrity = (options = {}) => {
       return abortOnWriteError(session, async () => {
         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
-            ? { $and: [{ [reference.path]: objectId }, { _id: { $ne: objectId } }] }
-            : { [reference.path]: objectId };
-          if (await reference.Model.collection.findOne(query, { session, projection: { _id: 1 } })) throw violation();
+        // 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.
+        for (const [Source, paths] of incoming.get(Model) || []) {
+          const matches = paths.map((path) => (Source === Model
+            ? { $and: [{ [path]: objectId }, { _id: { $ne: objectId } }] }
+            : { [path]: objectId }));
+          const query = matches.length === 1 ? matches[0] : { $or: matches };
+          if (await Source.collection.findOne(query, { session, projection: { _id: 1 } })) throw violation();
         }
         const deleted = await Model.findByIdAndDelete(objectId).session(session);
         if (!deleted?._id?.equals(objectId)

package/src/mongo/models.js

@@ -87,7 +87,17 @@ const assertEmbeddedFieldName = (gqlType, fieldEntryName) => {
   }
 };
 
-const generateSchemaDefinition = (gqlType, nested = false) => {
+// An embedded field whose type is the type being generated, or a type that embeds it on this path,
+// would nest without end. The path starts at the type whose model is generated. Sibling and nested
+// fields may still embed the same type.
+const assertNoEmbeddedCycle = (gqlType, entryType, ancestors, fieldPath) => {
+  if (entryType === gqlType) {
+    throw new SimfinityError('A type cannot have a field of its same type and embedded', 'INVALID_MODEL', 400);
+  }
+  if (ancestors.includes(entryType)) throw new SimfinityError(`Embedded cycle at ${fieldPath}`, 'INVALID_MODEL', 400);
+};
+
+const generateSchemaDefinition = (gqlType, nested = false, ancestors = [], path = gqlType.name) => {
   const argTypes = gqlType.getFields();
   const schemaArg = {};
 
@@ -111,10 +121,9 @@ const generateSchemaDefinition = (gqlType, nested = false) => {
         } else {
           assertEmbeddedFieldName(gqlType, fieldEntryName);
           const entryType = unwrapNonNull(type);
-          if (entryType === gqlType) {
-            throw new Error('A type cannot have a field of its same type and embedded');
-          }
-          const definition = generateSchemaDefinition(entryType, true);
+          const fieldPath = `${path}.${fieldEntryName}`;
+          assertNoEmbeddedCycle(gqlType, entryType, ancestors, fieldPath);
+          const definition = generateSchemaDefinition(entryType, true, [...ancestors, gqlType], fieldPath);
           // A nested object under a `type` key can only be a subdocument; like other embedded objects, it has no _id.
           schemaArg[fieldEntryName] = nested && fieldEntryName === 'type'
             ? new mongoose.Schema(definition, { _id: false })
@@ -126,10 +135,9 @@ const generateSchemaDefinition = (gqlType, nested = false) => {
       if (fieldEntry.extensions && fieldEntry.extensions.relation) {
         if (fieldEntry.extensions.relation.embedded) {
           assertEmbeddedFieldName(gqlType, fieldEntryName);
-          if (itemType === gqlType) {
-            throw new Error('A type cannot have a field of its same type and embedded');
-          }
-          schemaArg[fieldEntryName] = [generateSchemaDefinition(itemType, true)];
+          const fieldPath = `${path}.${fieldEntryName}`;
+          assertNoEmbeddedCycle(gqlType, itemType, ancestors, fieldPath);
+          schemaArg[fieldEntryName] = [generateSchemaDefinition(itemType, true, [...ancestors, gqlType], fieldPath)];
         }
       } else if (listItemMatchesScalar(type, GraphQLID)) {
         schemaArg[fieldEntryName] = [mongoose.Schema.Types.ObjectId];

package/src/mongo/queries.js

@@ -1,10 +1,9 @@
 import {
   GraphQLEnumType,
   GraphQLID,
-  GraphQLList,
-  GraphQLNonNull,
   GraphQLObjectType,
   GraphQLScalarType,
+  getNamedType,
 } from 'graphql';
 import mongoose from 'mongoose';
 
@@ -16,18 +15,6 @@ import {
 import { castObjectId } from './ids.js';
 import { resolveStorageScalar } from './models.js';
 
-const isNonNullOfType = (fieldEntryType, graphQLType) => (
-  fieldEntryType instanceof GraphQLNonNull && fieldEntryType.ofType instanceof graphQLType
-);
-
-const unwrapListAndNonNull = (type) => {
-  let unwrapped = type;
-  while (unwrapped instanceof GraphQLList || unwrapped instanceof GraphQLNonNull) {
-    unwrapped = unwrapped.ofType;
-  }
-  return unwrapped;
-};
-
 const getEffectiveTypeName = (type) => (
   type instanceof GraphQLScalarType ? resolveStorageScalar(type).name : type.name
 );
@@ -127,12 +114,6 @@ const AGG_OP_TO_MONGO = {
 
 const filterError = (message, code = 'INVALID_FILTER_VALUE') => new SimfinityError(message, code, 400);
 
-const queryNamedType = (type) => {
-  let result = type;
-  while (result instanceof GraphQLList || result instanceof GraphQLNonNull) result = result.ofType;
-  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
@@ -159,7 +140,7 @@ const resolveQueryPath = (gqltype, path, aggregationsIncluded) => {
   for (const [index, part] of parts.entries()) {
     const field = Object.hasOwn(currentType.getFields(), part) ? currentType.getFields()[part] : null;
     if (!field) throw filterError(`Unknown query field: ${path}`, 'INVALID_FILTER_FIELD');
-    const fieldType = queryNamedType(field.type);
+    const fieldType = getNamedType(field.type);
     const relation = field.extensions?.relation;
     if (fieldType instanceof GraphQLObjectType) {
       if (index === parts.length - 1) throw filterError(`Query path must end in a scalar field: ${path}`, 'INVALID_FILTER_PATH');
@@ -267,7 +248,7 @@ const buildQueryTerms = async (filterField, qlField, fieldName, gqltype, aggrega
   if (!qlField) throw filterError(`Unknown filter field: ${fieldName}`, 'INVALID_FILTER_FIELD');
   if (filterField == null) return { aggregateClauses, matchesClauses };
   if (typeof filterField !== 'object' || Array.isArray(filterField)) throw filterError(`Invalid filter for ${fieldName}`);
-  const isObject = queryNamedType(qlField.type) instanceof GraphQLObjectType;
+  const isObject = getNamedType(qlField.type) instanceof GraphQLObjectType;
   if (isObject && (!Array.isArray(filterField.terms) || filterField.terms.length === 0)) {
     throw filterError(`Filter on ${fieldName} requires non-empty terms`, 'MISSING_FILTER_PATH');
   }
@@ -309,8 +290,7 @@ const buildFilterGroupMatch = async (filterGroup, gqltype, aggregateClauses, agg
         throw new SimfinityError(`Unknown filter field: ${condition.field}`, 'INVALID_FILTER_FIELD', 400);
       }
 
-      const fieldType = unwrapListAndNonNull(qlField.type);
-      const isObject = fieldType instanceof GraphQLObjectType || isNonNullOfType(fieldType, GraphQLObjectType);
+      const isObject = getNamedType(qlField.type) instanceof GraphQLObjectType;
 
       let filterInput;
       if (isObject) {
@@ -326,8 +306,6 @@ const buildFilterGroupMatch = async (filterGroup, gqltype, aggregateClauses, agg
       }
 
       const result = await buildQueryTerms(filterInput, qlField, condition.field, gqltype, aggregationsIncluded);
-      if (!result) continue;
-
       appendLookups(aggregateClauses, aggregationsIncluded, result.aggregateClauses);
       for (const matchClause of Object.values(result.matchesClauses)) {
         for (const [matchKey, match] of Object.entries(matchClause)) {
@@ -379,8 +357,6 @@ const collectFiltersAndLookups = async (input, gqltype, aggregateClauses, aggreg
     if (controlKeys.has(key)) continue;
     const qlField = fields[key];
     const result = await buildQueryTerms(filterField, qlField, key, gqltype, aggregationsIncluded);
-    if (!result) continue;
-
     appendLookups(aggregateClauses, aggregationsIncluded, result.aggregateClauses);
     for (const matchClause of Object.values(result.matchesClauses)) {
       for (const [matchKey, match] of Object.entries(matchClause)) {

package/src/plugins.d.ts

@@ -0,0 +1,2 @@
+export * from '@simtlix/simfinity-core/plugins';
+export { default } from '@simtlix/simfinity-core/plugins';

package/src/scalars.d.ts

@@ -0,0 +1,2 @@
+export * from '@simtlix/simfinity-core/scalars';
+export { default } from '@simtlix/simfinity-core/scalars';

package/src/validators.d.ts

@@ -0,0 +1,2 @@
+export * from '@simtlix/simfinity-core/validators';
+export { default } from '@simtlix/simfinity-core/validators';

package/types/index.d.ts

@@ -52,6 +52,14 @@ export interface MongoAdapterOptions {
   /** Fixed at adapter creation. Defaults to off; transactional mode requires initialize(). */
   referentialIntegrity?: 'off' | 'transactional';
 }
+/**
+ * In the default 'off' mode, withTransaction(null, callback) without a model, as custom mutations
+ * call it, opens its session on the default mongoose.connection, unless that connection has no
+ * client, no model is compiled on it or on its useDb() descendants, and every model of the bound
+ * runtime's registrations uses one MongoDB client: then it opens it on that client. A supplied
+ * session or model is used as is. In transactional mode it uses the first protected model's
+ * connection.
+ */
 export interface MongoAdapter extends DatabaseAdapter {
   readonly referentialIntegrity: 'off' | 'transactional';
   /**
@@ -62,6 +70,14 @@ export interface MongoAdapter extends DatabaseAdapter {
   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;
+  /**
+   * Returns the raw stored data of a hydrated nested path or subdocument, or a Mongoose map's
+   * entries as a plain object, without running schema getters or virtuals. Returns the value
+   * unchanged when its schema declares a getter, a virtual other than Mongoose's automatic `id`, an
+   * alias or a subdocument method on a member at any depth inside it, so Simfinity keeps the object
+   * as stored, and for any other value.
+   */
+  rawEmbeddedValue(value: any): any;
   /** After connecting MongoDB and createSchema(), await the transaction capability and existing-reference audit. */
   initialize(): Promise<void>;
 }
@@ -120,6 +136,20 @@ export function addNoEndpointType(gqltype: GraphQLObjectType): void;
  * 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.
+ * Embedded types that contain each other throw INVALID_MODEL (400, `Embedded cycle at …`) when a
+ * generated model's embedded fields reach them, and always in transactional mode; in default mode a
+ * cycle that only supplied models reach is not checked.
+ * A generated input that would have no fields is left out with a warning, together with the
+ * collection operation, embedded field or add/update/state-action mutation that would take it; a
+ * non-null embedded field whose embedded type has no writable fields throws INVALID_MODEL (400)
+ * when the generated mutations reach its owner. An application type named FieldExtensionsType or
+ * RelationType renames Simfinity's introspection metadata types (SimfinityFieldExtensionsType,
+ * SimfinityRelationType) with a warning when it is in the process's first Simfinity schema. That
+ * schema fixes the names: in a later createSchema(), an application type with one of the current
+ * names (the original ones, or the fallback names after a rename) throws RESERVED_TYPE_NAME (500),
+ * before models are created when it is an included endpoint type, a registered mutation's input or
+ * output type, an output type they reach or a field argument's type, and when the schema is
+ * constructed otherwise.
  */
 export function createSchema(
   includedQueryTypes?: GraphQLObjectType[] | null,
@@ -187,7 +217,8 @@ 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).
  * References use IdInputType; embedded lists use nested inputs; referenced
- * collections use added/updated/deleted operation inputs.
+ * collections use added/updated/deleted operation inputs. It has no fields for a type without
+ * writable fields; such inputs are not part of generated schemas.
  */
 export function getInputType(type: GraphQLObjectType | { name: string }): GraphQLInputObjectType;