@simtlix/simfinity-core 3.6.0 → 3.8.0

package/README.md

@@ -16,24 +16,28 @@ For relational storage, `@simtlix/simfinity-sql` builds on core and delegates ph
 - `preventCreatingCollection` to pass validation-only storage setup to an adapter;
 - `configureQueryLimits` and `configureMutationLimits` for the process-wide page-size and nested-operation limits.
 
-The adapter supplies model creation, identifiers, transactions, record reads and writes, queries, counts, aggregations, and inverse collection reads. `DatabaseAdapter`, `Runtime`, controller, middleware, registration, and state-machine interfaces are exported in the TypeScript declarations. A runtime binds one adapter; create another runtime to use another database or configuration. An adapter can also define `getByIds(model, ids, { context })`, which returns the records it finds in `getById` shape and any order; the runtime then batches generated single-reference reads per request and type, matching records by `castId`, splitting batches at `maxPageSize`, and reading an ID with `getById` when a batch read fails or when `castId` would normalize or reject it. `castId` should throw a `NOT_VALID_ID` (400) `SimfinityError` for a malformed value and must not create a new identifier. An adapter can define `readByIdIsInert(model)`, returning `true` when a `getById` of that model has no side effects and `update()` and `delete()` reject the same malformed IDs with `NOT_VALID_ID` (400) and return null for a missing record; the runtime then skips the reads before deletes without an `onDelete` hook and before updates that merge no embedded value and have neither `onUpdating` nor nested collection items. The SQL adapter always reports it, and the MongoDB adapter does for models without `find`, `findOne`, `findOneAndUpdate` or `findOneAndDelete` middleware and without application `_id` setters or overrides of the statics those reads and writes call. When `getById` rejects a stored reference value that way, including one that `castId` rejected first, the generated reference field fails with an `InternalServerError` (500), since the client did not send the value. `update()` resolves to the updated record as stored, or null; nested collection children of that record are linked to and checked against its `_id`, else `id`, else the requested ID. An adapter that hydrates records can define `readEmbeddedValue(value)`: every nullable, singular embedded object field without a resolver then passes its value through it, so an explicitly stored `null` reads as `null`. The field is read as graphql's default resolver reads it, so a method on the parent is called and a promise it returns is awaited before the hook receives the value. Simfinity then reads as `null` an object that holds no data when a required member would read as `null`, not counting `id`, `readOnly`, interface and union members, members with an application resolver and referenced collections; runtimes that share the type read the same. It reads the stored members, never calling a getter, and counts a stored `_id` as `id`; it reads nothing from objects whose type has no member that counts, and an error while reading returns the object unchanged. An adapter whose hydrated records render members through getters can also define `rawEmbeddedValue(value)`, which returns a record's stored data as a plain object, or the record unchanged when that data does not show what it renders; a value that is not a plain object counts as data. The MongoDB adapter defines both.
+The adapter supplies model creation, identifiers, transactions, record reads and writes, queries, counts, aggregations, and inverse collection reads. `DatabaseAdapter`, `Runtime`, controller, middleware, registration, and state-machine interfaces are exported in the TypeScript declarations. A runtime binds one adapter; create another runtime to use another database or configuration. The GraphQL types that `prepare()` and `createModel()` receive still contain virtual fields, which must never be stored: an adapter that builds storage from a type's fields skips each field for which `isVirtualField(field)`, exported by this package with `virtualFieldOptions(field)`, returns true, on entities and embedded types alike, or builds it from `describeModels()`, which leaves them out. Generated writes, filters, sorts and aggregations never name a virtual field, but a controller hook can still assign one. An adapter can also define `getByIds(model, ids, { context })`, which returns the records it finds in `getById` shape and any order; the runtime then batches generated single-reference reads per request and type, matching records by `castId`, splitting batches at `maxPageSize`, and reading an ID with `getById` when a batch read fails or when `castId` would normalize or reject it. `castId` should throw a `NOT_VALID_ID` (400) `SimfinityError` for a malformed value and must not create a new identifier. An adapter can define `readByIdIsInert(model)`, returning `true` when a `getById` of that model has no side effects and `update()` and `delete()` reject the same malformed IDs with `NOT_VALID_ID` (400) and return null for a missing record; the runtime then skips the reads before deletes without an `onDelete` hook and before updates that merge no embedded value and have neither `onUpdating` nor nested collection items. The SQL adapter always reports it, and the MongoDB adapter does for models without `find`, `findOne`, `findOneAndUpdate` or `findOneAndDelete` middleware and without application `_id` setters or overrides of the statics those reads and writes call. When `getById` rejects a stored reference value that way, including one that `castId` rejected first, the generated reference field fails with an `InternalServerError` (500), since the client did not send the value. `update()` resolves to the updated record as stored, or null; nested collection children of that record are linked to and checked against its `_id`, else `id`, else the requested ID. An adapter that hydrates records can define `readEmbeddedValue(value)`: every nullable, singular embedded object field without a resolver then passes its value through it, so an explicitly stored `null` reads as `null`. The field is read as graphql's default resolver reads it, so a method on the parent is called and a promise it returns is awaited before the hook receives the value. Simfinity then reads as `null` an object that holds no data when a required member would read as `null`, not counting `id`, `readOnly` and virtual members, interface and union members, members with an application resolver and referenced collections; runtimes that share the type read the same. It reads the stored members, never calling a getter, and counts a stored `_id` as `id`; it reads nothing from objects whose type has no member that counts, and an error while reading returns the object unchanged. An adapter whose hydrated records render members through getters can also define `rawEmbeddedValue(value)`, which returns a record's stored data as a plain object, or the record unchanged when that data does not show what it renders; a value that is not a plain object counts as data. The MongoDB adapter defines both.
+
+An adapter can also define `findChildrenBatch(model, type, connectionField, parentIds, args, { context })`, the batch form of `findChildren` for generated collection fields, and a synchronous `batchesChildren(model, type, connectionField)` predicate. The runtime calls both as adapter methods and checks them on every read. When the method is missing or the predicate returns `false`, each field calls `findChildren` at once with the arguments object it built, as before. Otherwise, within one request (a context object), the runtime groups the collection reads of one related type and connection storage field whose effective arguments (after middleware, the scope and joined scopes) hold the same plain data and are requested in the same tick, that is before the promise jobs queued so far have run. It calls the method with 2 to 100 distinct parent IDs, each a raw ID that `castId` accepts without changing its string form, and with a copy of the arguments that the method may change; a group with one distinct parent calls `findChildren`. Return one array per parent ID, in order, each holding exactly the records, order and page that `findChildren` returns for that parent; records should show their parent under the connection field, or not show one. Fields of one parent share its records, each with its own array. After a rejection, or a result of another shape or with records of another parent, each field reads alone with `findChildren`; failures other than a `SimfinityError`, and results of another shape, are logged once per type. Pairing rule: the batch must reproduce `this.findChildren`, so `batchesChildren` must return `false` when `this.findChildren` is not the adapter's own function, as with a spread copy or an `Object.assign` override that changes how children are read. The bundled adapters follow this rule: both define the two members only with `batchedCollections: true`: the SQL adapter when the schema is prepared and its plugin's `compileChildrenQuery` is paired with its `compileQuery`, and the MongoDB adapter at creation. To opt out on one adapter instance, set `adapter.findChildrenBatch = undefined` (deleting it does nothing for a class whose method is on the prototype), or make `batchesChildren` return `false`. A copy that overrides `getById` still inherits the base `getByIds`, as before.
 
 Entity types, those registered with `connect()` and the targets of non-embedded relations, resolve `id` to `_id`, falling back to `id`, whatever the `createSchema()` allowlists include; types used only as embedded values keep their declared `id`. Embedded copies of an entity type resolve the same way, so they return their declared `id` unless the adapter stores an `_id` for them, as MongoDB does for embedded list items. The resolver is set on the type object, so it applies in every runtime that shares the type. `createSchema()` marks these registrations with `storedIdentity: true` before calling `adapter.prepare()`.
 
 When a runtime first creates a schema, it binds each GraphQL object type whose non-embedded relation fields receive its generated resolvers. It also reserves each reachable object type that still has a non-embedded relation field without a resolver, such as an unregistered custom mutation result. Registering a bound or reserved type in another runtime, or building another runtime's schema that reaches it through fields, interfaces, union members or custom mutation results, throws `TYPE_BOUND_TO_OTHER_RUNTIME` (409). `createSchema()` also rejects a type with a relation field copied, by `toConfig()` or a field spread, after another runtime generated that field's resolver. Create type objects once per runtime, for example with a factory function. Types without non-embedded relation fields, and types whose relation fields all have application resolvers, can be shared, and another runtime can use a `toConfig()` copy made before the first runtime built its schema. A shared custom mutation result type with an unresolved relation field is rejected.
 
-Registration and `createSchema()` validate `extensions.scope` (`INVALID_SCOPE`) and reject list or embedded relations to unregistered types (`UNREGISTERED_RELATION_TARGET`); `use()` rejects non-functions (`INVALID_MIDDLEWARE`). Before `adapter.prepare()`, `createSchema()` rejects a writable non-embedded list relation without a non-empty child `connectionField` whose resolver it would generate (`INVALID_MODEL`, 400). A collection without `connectionField` that has an application resolver, or is `readOnly`, only logs a `Configuration issue` warning, unless it is both, and nested writes through it fail with `INVALID_MODEL` (500) before anything is written; adapters that describe the whole model, such as PostgreSQL and transactional MongoDB, still reject it in `prepare()`. Fields named like generated query arguments (`sort`, `pagination`, `AND`, `OR`, and `aggregation` on aggregate endpoints) also log a warning once per runtime. Generated inputs that would have no fields are left out with a `Configuration issue` warning, with the collection operations, embedded fields and mutations that would take them; a non-null embedded field whose embedded type has no writable fields throws `INVALID_MODEL` (400) when generated mutations reach its owner. An application type named `FieldExtensionsType` or `RelationType` makes Simfinity rename its introspection metadata types to `SimfinityFieldExtensionsType` and `SimfinityRelationType` 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 `adapter.prepare()` 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, such as for a type inside an input object's fields.
+Registration and `createSchema()` validate `extensions.scope` (`INVALID_SCOPE`) and reject list or embedded relations to unregistered types (`UNREGISTERED_RELATION_TARGET`); `use()` rejects non-functions (`INVALID_MIDDLEWARE`). Before `adapter.prepare()`, `createSchema()` rejects a writable non-embedded list relation without a non-empty child `connectionField` whose resolver it would generate (`INVALID_MODEL`, 400). A collection without `connectionField` that has an application resolver, or is `readOnly`, only logs a `Configuration issue` warning, unless it is both, and nested writes through it fail with `INVALID_MODEL` (500) before anything is written; adapters that describe the whole model, such as PostgreSQL and transactional MongoDB, still reject it in `prepare()`. Fields named like generated query arguments (`sort`, `pagination`, `AND`, `OR`, and `aggregation` on aggregate endpoints) also log a warning once per runtime. Virtual fields (`extensions: { virtual: true }` or `{ virtual: { mcp: 'tool' | 'select' | false } }`, with the field's own `resolve`) are never stored, get no generated input and no filter argument, and resolve wherever their type appears; `createSchema()` rejects an invalid declaration, a virtual field without its own resolver or with `relation`, `unique: true`, `validations`, `queryable: true` or `readOnly: false`, and a virtual identity, index, state-machine `state` or `connectionField` field (`INVALID_MODEL`, 400). A client filter, sort, `groupId` or fact path through a virtual field fails with `FORBIDDEN_FILTER_PATH` (403), and one that middleware or a scope adds fails with `INVALID_MODEL` (500). A `readOnly` field with arguments and its own resolver that is not virtual, a reference or a collection logs a `Configuration issue` warning once per runtime. Generated inputs that would have no fields are left out with a `Configuration issue` warning, with the collection operations, embedded fields and mutations that would take them; a non-null embedded field whose embedded type has no writable fields throws `INVALID_MODEL` (400) when generated mutations reach its owner. An application type named `FieldExtensionsType` or `RelationType` makes Simfinity rename its introspection metadata types to `SimfinityFieldExtensionsType` and `SimfinityRelationType` 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 `adapter.prepare()` 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, such as for a type inside an input object's fields.
 
 Generated and custom mutations run through `adapter.withTransaction`. Retried attempts receive fresh clones of GraphQL input objects, lists, and dates while enum values keep their identity. An adapter can define `stateValue` when its persisted enum representation differs from GraphQL enum names.
 
-Importing the runtime installs Simfinity's `__Field.extensions` introspection field once per GraphQL module instance. Multiple runtimes and driver packages can be imported together without cloning schemas or duplicating introspection types.
+Importing the runtime installs Simfinity's `__Field.extensions` introspection field once per GraphQL module instance; its `readOnly` flag reads `true` for virtual fields. Multiple runtimes and driver packages can be imported together without cloning schemas or duplicating introspection types.
 
 ## Shared metadata and helpers
 
-`describeModels([{ gqltype, endpoint }])` discovers the persistent entity graph from `GraphQLObjectType` definitions and `extensions.relation`. Types registered with `endpoint: false` are still included when referenced. Reciprocal one-to-many definitions resolve to one child reference; explicit linking entities represent many-to-many relationships.
+`describeModels([{ gqltype, endpoint }])` discovers the persistent entity graph from `GraphQLObjectType` definitions and `extensions.relation`, leaving virtual fields out and describing no type that only virtual fields reach. Types registered with `endpoint: false` are still included when referenced. Reciprocal one-to-many definitions resolve to one child reference; explicit linking entities represent many-to-many relationships.
 
 `createQueryPlan` and `resolveModelPath` turn Simfinity filter, sort, pagination, and aggregation inputs into a driver-neutral plan resolved against that metadata.
 
+`isVirtualField(field)` tells whether a GraphQL field is virtual, and `virtualFieldOptions(field)` returns its normalized options, `{ mcp }`, or `null` for any other field. Adapters that build storage from GraphQL types use them to skip virtual fields.
+
 The package also exports the `auth`, `validators`, `scalars`, and `plugins` helper namespaces alongside `createValidatedScalar`, `SimfinityError`, `InternalServerError`, `UnauthenticatedError` and `ForbiddenError` (the same classes as `auth.UnauthenticatedError` and `auth.ForbiddenError`), `buildErrorFormatter`, `configureQueryLimits`, `configureMutationLimits`, `QLOperator`, `QLSort`, and `QLValue`. `buildErrorFormatter` returns a `GraphQLError` whose `originalError` is the classified Simfinity error. Database packages reuse these exports so helpers, errors, and globally named GraphQL types retain one identity.
 
 The same helpers are available from the `@simtlix/simfinity-core/auth`, `/auth/errors`, `/auth/expressions`, `/auth/rules`, `/plugins`, `/scalars` and `/validators` subpaths, each with TypeScript declarations whose types match the root namespaces. `moduleResolution` `node16`, `nodenext` and `bundler` read them through the export map, and `node10` through `typesVersions`. The `internal/*` subpaths are not public API and have no declarations.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simtlix/simfinity-core",
-  "version": "3.6.0",
+  "version": "3.8.0",
   "description": "Driver-free GraphQL runtime and model metadata for Simfinity",
   "type": "module",
   "main": "./src/index.js",

package/src/index.js

@@ -1,4 +1,5 @@
 export { describeModels } from './metadata.js';
+export { isVirtualField, virtualFieldOptions } from './relation-storage.js';
 export { default as SimfinityError } from './errors/simfinity.error.js';
 export { createValidatedScalar } from './scalars/factory.js';
 export {

package/src/introspection.js

@@ -4,6 +4,7 @@ import {
   GraphQLString,
   __Field,
 } from 'graphql';
+import { isVirtualField } from './relation-storage.js';
 
 // The object types of `__Field.extensions`: FieldExtensionsType and the RelationType of its
 // `relation` field, under the given names.
@@ -27,6 +28,14 @@ const createFieldMetadataType = (extensionsName, relationName) => {
   });
 };
 
+// The metadata `__Field.extensions` returns: the field's own extensions, except that a virtual field
+// reads `readOnly: true`, which virtual implies. The metadata types keep their fields, so schemas
+// without virtual fields introspect exactly as before; client metadata about virtual fields belongs
+// in a descriptor of its own (#101), not in this process-wide extension.
+const fieldMetadataOf = (field) => (isVirtualField(field)
+  ? { ...field.extensions, readOnly: true }
+  : field.extensions);
+
 // getFields() supports both lazy and already materialized introspection fields.
 // Reuse the shared field on repeated module evaluation to preserve type identity.
 const introspectionFields = __Field.getFields();
@@ -34,7 +43,7 @@ if (!introspectionFields.extensions) {
   introspectionFields.extensions = {
     type: createFieldMetadataType('FieldExtensionsType', 'RelationType'),
     name: 'extensions',
-    resolve: (obj) => obj.extensions,
+    resolve: fieldMetadataOf,
     args: [],
     isDeprecated: false,
   };

package/src/metadata.js

@@ -2,6 +2,10 @@ import {
   isObjectType, isScalarType, isEnumType, isNonNullType, isListType,
 } from 'graphql';
 import SimfinityError from './errors/simfinity.error.js';
+import {
+  assertVirtualConnection, assertVirtualDeclaration, assertVirtualIndexes, assertVirtualStateField,
+} from './virtual-fields.js';
+import { assertPlainConnectionField } from './relation-storage.js';
 
 const invalid = (message) => {
   throw new SimfinityError(message, 'INVALID_MODEL', 400);
@@ -42,7 +46,11 @@ const scalarDescription = (type) => {
   return { scalar };
 };
 
-/** Describe persistent entities without importing a database driver or mutating GraphQL types. */
+/**
+ * Describe persistent entities without importing a database driver or mutating GraphQL types.
+ * Virtual fields (`extensions.virtual`) store nothing, so they are left out of every entity and
+ * embedded type, and their result types are neither described nor required to declare a relation.
+ */
 export const describeModels = (registrations) => {
   if (!Array.isArray(registrations)) invalid('registrations must be an array');
   const knownTypes = new Map();
@@ -61,12 +69,16 @@ export const describeModels = (registrations) => {
     }
   };
   for (const registration of registrations) registerType(registration.gqltype);
+  for (const registration of registrations) assertVirtualStateField(registration.gqltype, registration.stateMachine);
   for (const registration of registrations) if (registration.endpoint !== false) addEntity(registration.gqltype);
 
   const fieldsOf = (type, ancestors, path, embedded = false) => {
     if (ancestors.includes(type)) invalid(`Embedded cycle at ${path}`);
     registerType(type);
-    const fields = Object.values(type.getFields()).map((field) => {
+    const stored = Object.values(type.getFields()).filter((field) => !assertVirtualDeclaration(
+      type.name, field.name, field, () => typeof field.resolve === 'function',
+    ));
+    const fields = stored.map((field) => {
       const { named, ...wrappers } = unwrap(field.type);
       const extensions = field.extensions || {};
       const descriptor = {
@@ -79,12 +91,14 @@ export const describeModels = (registrations) => {
       if (!isObjectType(named)) invalid(`Unsupported field type at ${path}.${field.name}`);
       const relation = extensions.relation;
       if (!relation) invalid(`${path}.${field.name} requires extensions.relation`);
+      assertVirtualConnection(type, field.name, field);
       if (relation.embedded) {
         return {
           ...descriptor, kind: 'embedded',
           fields: fieldsOf(named, [...ancestors, type], `${path}.${field.name}`, true),
         };
       }
+      assertPlainConnectionField(type.name, field.name, field);
       addEntity(named);
       if (wrappers.list) {
         if (!relation.connectionField) invalid(`${path}.${field.name} requires a child connectionField`);
@@ -111,6 +125,7 @@ export const describeModels = (registrations) => {
       }
       return { fields: [...index.fields], unique: index.unique === true };
     });
+    assertVirtualIndexes(type);
   }
   for (const entity of entities.values()) {
     for (const field of entity.fields.filter((item) => item.kind === 'collection')) {

package/src/relation-storage.js

@@ -1,8 +1,11 @@
 import { GraphQLList, GraphQLNonNull } from 'graphql';
+import SimfinityError from './errors/simfinity.error.js';
 
-// Internal helpers that decide where a relation stores its link and which types keep a stored
-// identity. They are shared by the core runtime and the MongoDB adapter through the
-// `./internal/relation-storage` subpath, which is not public API.
+// Internal helpers that decide where a relation stores its link, which types keep a stored
+// identity and which fields store nothing (virtual fields). They are shared by the core runtime and
+// the other packages through the `./internal/relation-storage` subpath, which is not public API.
+// isVirtualField and virtualFieldOptions are also public, as root exports of the core package, for
+// custom adapters that build storage from GraphQL fields.
 
 const unwrapNonNull = (type) => (type instanceof GraphQLNonNull ? type.ofType : type);
 
@@ -18,6 +21,53 @@ export const getListShape = (type) => {
   };
 };
 
+export const VIRTUAL_MCP_MODES = Object.freeze(['tool', 'select', false]);
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+  && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+
+// A virtual field (`extensions.virtual`) is resolved by its own resolver and stored nowhere: it has
+// no storage, no generated input and no query path. Only `true` and a plain options object with
+// known options declare one, and this returns its normalized options, `{ mcp }`, with `mcp`
+// defaulting to 'tool'; it returns null for any other field. createSchema() and describeModels()
+// reject other `virtual` values with INVALID_MODEL, so in their schemas a field with
+// `extensions.virtual` is always virtual.
+export const virtualFieldOptions = (field) => {
+  const virtual = field?.extensions?.virtual;
+  if (virtual === true) return { mcp: 'tool' };
+  if (!isPlainObject(virtual) || Object.keys(virtual).some((key) => key !== 'mcp')) return null;
+  if (virtual.mcp !== undefined && !VIRTUAL_MCP_MODES.includes(virtual.mcp)) return null;
+  return { mcp: virtual.mcp ?? 'tool' };
+};
+
+export const isVirtualField = (field) => virtualFieldOptions(field) !== null;
+
+// A relation's connectionField is a field of the record that stores the link: the reference's own
+// type, or a collection's item type. It is a field name, never a path into an embedded value, which
+// would put the link inside another value: MongoDB would store it in that value's member and read it
+// back as missing, and PostgreSQL would name a column after the whole path. A link that belongs to an
+// embedded value is declared there, as a reference of the embedded type. Throws INVALID_MODEL (400)
+// for a connectionField that is not a string, or that contains a dot; an omitted or empty one keeps
+// its existing meaning.
+export const assertPlainConnectionField = (typeName, fieldName, field) => {
+  const relation = field?.extensions?.relation;
+  if (!relation || relation.embedded) return;
+  const { connectionField } = relation;
+  if (connectionField === undefined || connectionField === null || connectionField === '') return;
+  const name = `${typeName}.${fieldName}`;
+  const listShape = getListShape(field.type);
+  const holder = listShape ? listShape.itemType.name : typeName;
+  if (typeof connectionField !== 'string') {
+    throw new SimfinityError(`${name} extensions.relation.connectionField must be the name of a field of ${holder}`,
+      'INVALID_MODEL', 400);
+  }
+  if (connectionField.includes('.')) {
+    throw new SimfinityError(`${name} extensions.relation.connectionField ${connectionField} must name a field of ${holder}, `
+      + 'not a path into an embedded value'
+      + (listShape ? '' : '; declare a reference that belongs to an embedded value inside the embedded type'),
+    'INVALID_MODEL', 400);
+  }
+};
+
 export const getFieldStorageName = (fieldName, field) => {
   const relation = field.extensions?.relation;
   return relation && !relation.embedded && !getListShape(field.type)

package/src/runtime.js

@@ -17,8 +17,11 @@ import { collectQueryPathEntries, collectQueryPaths, walkQueryPath } from './que
 import { relationFieldOwners } from './relation-owners.js';
 import { isThenable } from './auth/thenable.js';
 import {
-  getFieldStorageName, getListShape, markStoredIdentity, normalizeConnectionField,
+  assertPlainConnectionField, getFieldStorageName, getListShape, isVirtualField, markStoredIdentity, normalizeConnectionField,
 } from './relation-storage.js';
+import {
+  assertVirtualConnection, assertVirtualDeclaration, assertVirtualIndexes, assertVirtualStateField, virtualConflicts,
+} from './virtual-fields.js';
 import {
   fieldMetadataNamesFixed, fieldMetadataTypes, fixFieldMetadataNames, renameFieldMetadataTypes,
 } from './introspection.js';
@@ -71,6 +74,8 @@ const hasApplicationResolver = (gqltype, fieldName) => (
 // so a bound type cannot be registered in, or reached from, another runtime's schema.
 const runtimeBoundTypes = new WeakMap();
 const forbiddenPath = (message) => new SimfinityError(message, 'FORBIDDEN_FILTER_PATH', 403);
+// Generated inputs never write a readOnly field, nor a virtual one, which virtual implies.
+const isReadOnlyField = (field) => !!field.extensions?.readOnly || isVirtualField(field);
 
 // Query scopes restrict reads, so a scope Simfinity cannot run must fail rather than be skipped.
 const SCOPE_OPERATIONS = ['find', 'get_by_id', 'aggregate'];
@@ -816,7 +821,7 @@ const graphQLListInputType = (dict, fieldEntry, fieldEntryName,
 const selfCollectionFieldNames = (gqltype) => {
   const hasStateMachine = !!typesDict.types[gqltype.name]?.stateMachine;
   return Object.entries(gqltype.getFields())
-    .filter(([fieldName, field]) => !field.extensions?.readOnly
+    .filter(([fieldName, field]) => !isReadOnlyField(field)
       && !(fieldName === 'state' && hasStateMachine)
       && getListShape(field.type)?.itemType === gqltype)
     .map(([fieldName]) => fieldName);
@@ -896,7 +901,7 @@ const buildInputType = (gqltype, reachable) => {
     const fieldArg = {};
     const fieldArgForUpdate = {};
 
-    if (!fieldEntry.extensions || !fieldEntry.extensions.readOnly) {
+    if (!isReadOnlyField(fieldEntry)) {
       const hasStateMachine = !!typesDict.types[gqltype.name].stateMachine;
       const stateFieldManagedByStateMachine = !!(fieldEntryName === 'state' && hasStateMachine);
 
@@ -1037,7 +1042,7 @@ const typesWithReachableInputs = (includedMutationTypes) => {
     if (reached.has(gqltype)) return;
     reached.add(gqltype);
     for (const field of Object.values(gqltype.getFields())) {
-      if (field.extensions?.readOnly) continue;
+      if (isReadOnlyField(field)) continue;
       const listShape = getListShape(field.type);
       const target = listShape ? listShape.itemType : unwrapNonNull(field.type);
       // A single reference is an IdInputType, so it reaches no input of its target.
@@ -1181,6 +1186,8 @@ const materializeModel = async (args, gqltype, linkToParent, operation, session)
   const collectionFields = {};
 
   for (const [fieldEntryName, fieldEntry] of Object.entries(argTypes)) {
+    // A virtual field stores nothing, whatever middleware or saveObject() passes for it.
+    if (isVirtualField(fieldEntry)) continue;
     const fieldValue = ownValue(args, fieldEntryName);
     if (fieldEntry.extensions && fieldEntry.extensions.validations
       && fieldEntry.extensions.validations[operation]) {
@@ -1339,7 +1346,7 @@ const completeEmbeddedValue = (fieldName, fieldEntry, value, patch = null) => {
     for (const [memberName, member] of Object.entries(embeddedType.getFields())) {
       const relation = member.extensions?.relation;
       const memberList = getListShape(member.type);
-      if (relation && !relation.embedded && memberList) continue;
+      if ((relation && !relation.embedded && memberList) || isVirtualField(member)) continue;
       const storageName = getFieldStorageName(memberName, member);
       if (ownValue(item, storageName) === undefined && memberList) item[storageName] = [];
       if (memberName === 'id' || member.extensions?.readOnly) continue;
@@ -1366,7 +1373,7 @@ const clearNullEmbeddedMembers = (merged, fieldEntry, patch) => {
   const members = unwrapNonNull(fieldEntry.type).getFields();
   for (const [memberName, value] of Object.entries(patch)) {
     const member = members[memberName];
-    if (value !== null || !member || member.type instanceof GraphQLNonNull) continue;
+    if (value !== null || !member || member.type instanceof GraphQLNonNull || isVirtualField(member)) continue;
     const relation = member.extensions?.relation;
     const listShape = getListShape(member.type);
     if (relation && !relation.embedded && listShape) continue;
@@ -1429,7 +1436,7 @@ const onUpdateSubject = async (Model, gqltype, controller, args, session, linkTo
   }
 
   for (const [fieldEntryName, fieldEntry] of Object.entries(argTypes)) {
-    if (args[fieldEntryName] === null && !(fieldEntry.type instanceof GraphQLNonNull)) {
+    if (args[fieldEntryName] === null && !(fieldEntry.type instanceof GraphQLNonNull) && !isVirtualField(fieldEntry)) {
       materializedModel.modelArgs.$unset = {
         ...materializedModel.modelArgs.$unset,
         [getFieldStorageName(fieldEntryName, fieldEntry)]: '',
@@ -1735,6 +1742,9 @@ const inspectClientPaths = (gqltype, args, operation) => {
   for (const { segments, group } of collectQueryPathEntries(args, operation)) {
     walkQueryPath(gqltype, segments, ({ type, fieldName, field, index }) => {
       const path = segments.slice(0, index + 1).join('.');
+      if (isVirtualField(field)) {
+        throw forbiddenPath(`Query path ${path} uses the virtual field ${type.name}.${fieldName}, which is not stored`);
+      }
       const queryable = field.extensions?.queryable;
       if (queryable === false || (queryable !== true && hasApplicationResolver(type, fieldName))) {
         throw forbiddenPath(`Query path ${path} uses the non-queryable field ${type.name}.${fieldName}`);
@@ -1759,6 +1769,24 @@ const inspectClientPaths = (gqltype, args, operation) => {
   return joinedScopes;
 };
 
+// Whether a schema of this runtime declared a virtual field, so that query paths may name one.
+let virtualFieldsDeclared = false;
+
+// Client paths through a virtual field were rejected before middleware and scopes ran
+// (inspectClientPaths), so a path through one now is a trusted path that middleware or a scope added.
+// It would compile against storage that does not exist, so the operation fails with INVALID_MODEL
+// (500), the code of model declarations that cannot be honored at request time.
+const assertStoredQueryPaths = (gqltype, args, operation) => {
+  if (!virtualFieldsDeclared) return;
+  for (const { segments } of collectQueryPathEntries(args, operation)) {
+    walkQueryPath(gqltype, segments, ({ type, fieldName, field, index }) => {
+      if (!isVirtualField(field)) return;
+      throw new SimfinityError(`Query path ${segments.slice(0, index + 1).join('.')}, added by middleware or a `
+        + `scope, uses the virtual field ${type.name}.${fieldName}, which is not stored`, 'INVALID_MODEL', 500);
+    });
+  }
+};
+
 // A joined scope must not repeat the rows it restricts: its paths may not cross a collection, nor
 // reach a non-embedded relation inside an embedded list, which is joined once per list item.
 const assertJoinedScopePaths = (groups, prefix, target) => {
@@ -1912,10 +1940,317 @@ const resolveById = async (type, args, context, requiredId) => {
   }
   const queryArgs = { id: { operator: 'EQ', value: args.id } };
   await executeScope({ type, args: queryArgs, operation: 'get_by_id', context });
+  assertStoredQueryPaths(type.gqltype, queryArgs, 'find');
   const results = await adapter.find(type.model, type.gqltype, queryArgs, null, { requiredId, context });
   return results[0] || null;
 };
 
+// Batched collection reads. A generated collection field reads its children with one
+// adapter.findChildren call per parent unless the adapter defines findChildrenBatch and its
+// batchesChildren predicate does not return false. Then, within one request (a context object), the
+// reads of one related type and connection storage field whose effective arguments (after
+// middleware, the scope and joined scopes) hold the same plain data wait until the promise jobs
+// queued so far have run, as references do, and are read together, at most CHILD_BATCH_SIZE
+// distinct parents per call.
+const CHILD_BATCH_SIZE = 100;
+// Arguments whose canonical key would exceed this many characters, such as a long IN list, read
+// alone, so a field never spends more than this on canonicalization.
+const CHILD_ARGS_KEY_BUDGET = 64 * 1024;
+const NOT_PLAIN = Symbol('not plain data');
+
+// The canonical key of a collection read's effective arguments: two reads share it only when their
+// arguments hold the same data. Only plain data qualifies: strings, numbers (-0, NaN and Infinity
+// kept distinct), booleans, undefined, null, bigints, dates (by time, with no own properties), dense
+// arrays, and objects with the Object or a null prototype whose own string-keyed properties are
+// enumerable data properties, all writable and configurable, or all fixed by freezing. The key keeps
+// property order, null prototypes, frozen objects and shared references. Anything else, such as a
+// function, a symbol, a class instance (an ObjectId included), an accessor, a non-enumerable,
+// sealed or non-extensible member, a sparse or decorated array, a cycle, an exotic object that fails
+// while it is read, or a key over the budget, returns null, and the read runs alone.
+const childArgsKey = (args) => {
+  if (args === null || typeof args !== 'object' || Array.isArray(args)) return null;
+  const parts = [];
+  let size = 0;
+  const push = (part) => {
+    size += part.length;
+    if (size > CHILD_ARGS_KEY_BUDGET) throw NOT_PLAIN;
+    parts.push(part);
+  };
+  const seen = new Map();
+  const visit = (value) => {
+    switch (typeof value) {
+      case 'string':
+        if (value.length > CHILD_ARGS_KEY_BUDGET) throw NOT_PLAIN;
+        push(JSON.stringify(value));
+        return;
+      case 'number': push(Object.is(value, -0) ? '-0' : String(value)); return;
+      case 'boolean':
+      case 'undefined': push(String(value)); return;
+      case 'bigint': push(`${value}n`); return;
+      case 'object': if (value !== null) break; push('null'); return;
+      default: throw NOT_PLAIN;
+    }
+    const known = seen.get(value);
+    if (known) {
+      // A shared reference repeats the index of its first visit; a cycle is not plain data.
+      if (!known.done) throw NOT_PLAIN;
+      push(`@${known.index}`);
+      return;
+    }
+    const entry = { index: seen.size, done: false };
+    seen.set(value, entry);
+    const prototype = Object.getPrototypeOf(value);
+    const frozen = Object.isFrozen(value);
+    const keys = Reflect.ownKeys(value);
+    if (prototype === Date.prototype) {
+      if (keys.length) throw NOT_PLAIN;
+      // Throws a TypeError, caught below, for an object that only inherits from Date.prototype.
+      push(`D${frozen ? 'F' : ''}${Date.prototype.getTime.call(value)}`);
+    } else {
+      const array = Array.isArray(value);
+      if (array ? prototype !== Array.prototype : prototype !== Object.prototype && prototype !== null) throw NOT_PLAIN;
+      // A dense array owns its indices, in order, then its length, and nothing else.
+      if (array && (keys.length !== value.length + 1
+        || keys.some((key, index) => key !== (index < value.length ? String(index) : 'length'))
+        || Reflect.getOwnPropertyDescriptor(value, 'length').writable === frozen)) throw NOT_PLAIN;
+      if (!frozen && !Object.isExtensible(value)) throw NOT_PLAIN;
+      push(`${array ? '[' : '{'}${prototype === null ? '0' : ''}${frozen ? 'F' : ''}`);
+      for (const key of keys) {
+        if (typeof key === 'symbol') throw NOT_PLAIN;
+        if (array && key === 'length') continue;
+        const descriptor = Reflect.getOwnPropertyDescriptor(value, key);
+        if (!descriptor || !('value' in descriptor) || !descriptor.enumerable
+          || descriptor.writable === frozen || descriptor.configurable === frozen) throw NOT_PLAIN;
+        if (!array) push(`${JSON.stringify(key)}:`);
+        visit(descriptor.value);
+        push(',');
+      }
+      push(array ? ']' : '}');
+    }
+    entry.done = true;
+  };
+  try {
+    visit(args);
+    return parts.join('');
+  } catch {
+    // Not plain data, too large, or an exotic object (such as a proxy) that failed while it was read.
+    return null;
+  }
+};
+
+// A copy of arguments that childArgsKey accepted, with the same prototypes, frozen objects, dates
+// and shared references, so the adapter may change it without reaching the request's objects.
+const clonePlainArgs = (value, copies = new Map()) => {
+  if (value === null || typeof value !== 'object') return value;
+  if (copies.has(value)) return copies.get(value);
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype === Date.prototype) {
+    const date = new Date(Date.prototype.getTime.call(value));
+    copies.set(value, date);
+    return Object.isFrozen(value) ? Object.freeze(date) : date;
+  }
+  const copy = Array.isArray(value) ? [] : Object.create(prototype);
+  copies.set(value, copy);
+  for (const key of Object.keys(value)) {
+    Object.defineProperty(copy, key, {
+      value: clonePlainArgs(value[key], copies), writable: true, enumerable: true, configurable: true,
+    });
+  }
+  return Object.isFrozen(value) ? Object.freeze(copy) : copy;
+};
+
+// The batch key of a parent ID: its string form, when the adapter casts the ID without changing
+// that form. A missing ID (which keeps the adapter's own semantics, such as MongoDB matching
+// children without a parent), an object whose string form says nothing of its value, an ID castId
+// rejects and one it normalizes have none, and read alone.
+const childParentKey = (parentId) => {
+  try {
+    if (parentId == null) return null;
+    const key = String(parentId);
+    if (typeof parentId === 'object' && key === Object.prototype.toString.call(parentId)) return null;
+    return String(adapter.castId(parentId)) === key ? key : null;
+  } catch {
+    return null;
+  }
+};
+
+// Collection reads of one request that wait for a batch: context -> related type registration ->
+// (connection storage field + canonical arguments) -> group. Nothing is cached: each group is read
+// once and dropped.
+const childBatches = new WeakMap();
+
+const readChildrenAlone = (type, connection, parentId, args) => adapter.findChildren(
+  type.model, type.gqltype, connection.storageFieldName, parentId, args, null,
+);
+
+// Whether the adapter reads this type's children in batches, checked on every read as an adapter
+// method call. A predicate that throws keeps per-parent reads; an error other than a SimfinityError
+// is reported once per type.
+const batchesChildren = (type, connection) => {
+  if (adapter.batchesChildren == null) return true;
+  try {
+    return adapter.batchesChildren(type.model, type.gqltype, connection.storageFieldName) !== false;
+  } catch (error) {
+    if (!(error instanceof SimfinityError)) {
+      warnOnce(type.gqltype, 'batchesChildren', 'Configuration issue: adapter.batchesChildren failed for '
+        + `${type.gqltype.name} (${error?.message ?? String(error)}); its collection fields read one parent at a time.`);
+    }
+    return false;
+  }
+};
+
+// Whether a batched child record may belong to the parent with this key: it is an object, and the
+// parent it stores under the connection storage field (or its GraphQL name), when it shows one, has
+// that key by string form or by castId. A stored list (a multikey connection) needs one such entry.
+const belongsToParent = (record, connection, key) => {
+  if (record === null || typeof record !== 'object') return false;
+  let stored = ownValue(record, connection.storageFieldName);
+  if (stored === undefined && connection.graphqlFieldName) stored = ownValue(record, connection.graphqlFieldName);
+  if (stored === undefined) return true;
+  const matches = (value) => {
+    const id = value?._id ?? value;
+    if (id == null) return false;
+    try {
+      return String(id) === key || String(adapter.castId(id)) === key;
+    } catch {
+      return false;
+    }
+  };
+  return Array.isArray(stored) ? stored.some(matches) : matches(stored);
+};
+
+// The fields of one parent share its records, as references do, but each gets its own list.
+const settleChildren = (waiters, list) => waiters.forEach(({ resolve }, index) => {
+  resolve(index === 0 ? list : [...list]);
+});
+
+// After a failed read, each field reads alone, in its own promise job, with its own copy of the
+// arguments and its own parent ID, so an error fails only the fields it would fail alone.
+const readEachChildAlone = (type, group, waiters) => {
+  for (const { parentId, resolve, reject } of waiters) {
+    Promise.resolve()
+      .then(() => readChildrenAlone(type, group.connection, parentId, clonePlainArgs(group.args)))
+      .then(resolve, reject);
+  }
+};
+
+// Whether a batch result holds one list per parent, in order, of records of that parent. Every index is
+// checked, holes included, since Array.prototype.every skips empty slots.
+const listsMatchParents = (lists, parents, connection) => {
+  if (!Array.isArray(lists) || lists.length !== parents.length) return false;
+  for (let index = 0; index < lists.length; index++) {
+    const records = Object.hasOwn(lists, index) ? lists[index] : undefined;
+    if (!Array.isArray(records)) return false;
+    for (let position = 0; position < records.length; position++) {
+      if (!Object.hasOwn(records, position) || !belongsToParent(records[position], connection, parents[index].key)) return false;
+    }
+  }
+  return true;
+};
+
+const readChildren = async (type, group, parents, context) => {
+  const { connection } = group;
+  if (parents.length === 1) {
+    // One distinct parent reads with findChildren, as before, shared by the fields that read it.
+    const { waiters } = parents[0];
+    let list;
+    try {
+      list = await readChildrenAlone(type, connection, waiters[0].parentId, clonePlainArgs(group.args));
+    } catch (error) {
+      if (waiters.length === 1) waiters[0].reject(error);
+      else readEachChildAlone(type, group, waiters);
+      return;
+    }
+    if (waiters.length > 1 && !Array.isArray(list)) readEachChildAlone(type, group, waiters);
+    else settleChildren(waiters, list);
+    return;
+  }
+  let lists;
+  try {
+    lists = await adapter.findChildrenBatch(type.model, type.gqltype, connection.storageFieldName,
+      parents.map(({ waiters }) => waiters[0].parentId), clonePlainArgs(group.args), { context });
+  } catch (error) {
+    if (!(error instanceof SimfinityError)) {
+      warnOnce(type.gqltype, 'findChildrenBatch', `adapter.findChildrenBatch failed for ${type.gqltype.name} `
+        + `(${error?.message ?? String(error)}); the fields it read were read one parent at a time. Later failures `
+        + 'for this type are not reported.');
+    }
+    parents.forEach(({ waiters }) => readEachChildAlone(type, group, waiters));
+    return;
+  }
+  if (!listsMatchParents(lists, parents, connection)) {
+    warnOnce(type.gqltype, 'findChildrenBatch', 'Configuration issue: adapter.findChildrenBatch did not return one '
+      + `list of ${type.gqltype.name} records per parent ID, in parentIds order; the fields it read were read one `
+      + 'parent at a time.');
+    parents.forEach(({ waiters }) => readEachChildAlone(type, group, waiters));
+    return;
+  }
+  parents.forEach(({ waiters }, index) => settleChildren(waiters, lists[index]));
+};
+
+const flushChildren = (type, group, context) => {
+  const parents = [...group.parents].map(([key, { waiters }]) => ({ key, waiters }));
+  for (let start = 0; start < parents.length; start += CHILD_BATCH_SIZE) {
+    const chunk = parents.slice(start, start + CHILD_BATCH_SIZE);
+    // An unexpected error settles every field of the chunk that is still waiting.
+    readChildren(type, group, chunk, context).catch((error) => {
+      for (const { waiters } of chunk) waiters.forEach(({ reject }) => reject(error));
+    });
+  }
+};
+
+// A generated collection read. It runs at once, with the arguments object it received, as before,
+// unless the adapter batches this type's children, the request has a context object, the parent ID
+// has a batch key, and the effective arguments are plain data with valid pagination and a key within
+// the budget. Then it joins the request's group for its related type, connection storage field and
+// arguments: the first read of a group copies the arguments, and later reads compute only the key.
+const loadChildren = (type, connection, parentId, args, context) => {
+  if (typeof adapter.findChildrenBatch !== 'function' || typeof context !== 'object' || context === null
+    || !batchesChildren(type, connection)) return readChildrenAlone(type, connection, parentId, args);
+  const key = childParentKey(parentId);
+  const argsKey = key === null ? null : childArgsKey(args);
+  if (argsKey === null) return readChildrenAlone(type, connection, parentId, args);
+  try {
+    // Invalid pagination fails each field alone, as findChildren reports it.
+    paginationStages(args.pagination, true);
+  } catch {
+    return readChildrenAlone(type, connection, parentId, args);
+  }
+  let byType = childBatches.get(context);
+  if (!byType) {
+    byType = new Map();
+    childBatches.set(context, byType);
+  }
+  let groups = byType.get(type);
+  if (!groups) {
+    groups = new Map();
+    byType.set(type, groups);
+  }
+  const groupKey = `${JSON.stringify(connection.storageFieldName)}${argsKey}`;
+  let group = groups.get(groupKey);
+  if (!group) {
+    let snapshot;
+    try {
+      snapshot = clonePlainArgs(args);
+    } catch {
+      return readChildrenAlone(type, connection, parentId, args);
+    }
+    group = { connection, args: snapshot, parents: new Map() };
+    groups.set(groupKey, group);
+    const created = group;
+    // As for references, flush once the promise jobs queued so far have run.
+    Promise.resolve().then(() => process.nextTick(() => {
+      groups.delete(groupKey);
+      if (!groups.size && byType.get(type) === groups) byType.delete(type);
+      flushChildren(type, created, context);
+    }));
+  }
+  return new Promise((resolve, reject) => {
+    if (!group.parents.has(key)) group.parents.set(key, { waiters: [] });
+    group.parents.get(key).waiters.push({ parentId, resolve, reject });
+  });
+};
+
 // Why a type's generated create or update input has no fields, for the warnings of buildMutation. An
 // update input also needs a writable id.
 const withoutWritableFields = (type, { noWritableId = false } = {}) => {
@@ -2122,6 +2457,7 @@ const buildRootQuery = (name, includedTypes, aggregationResultType = QLTypeAggre
             await executeMiddleware(params);
             await executeScope(params);
             await applyJoinedScopes(joinedScopes, params);
+            assertStoredQueryPaths(type.gqltype, params.args, 'find');
             const queryArgs = params.args;
             const wantsCount = !!(queryArgs.pagination && queryArgs.pagination.count)
               && canReportCount(parent, info, context);
@@ -2142,7 +2478,8 @@ const buildRootQuery = (name, includedTypes, aggregationResultType = QLTypeAggre
         };
 
         const aggregateArgsObject = { ...argsObject };
-        if (Object.hasOwn(type.gqltype.getFields(), 'aggregation')) {
+        const fields = type.gqltype.getFields();
+        if (Object.hasOwn(fields, 'aggregation') && !isVirtualField(fields.aggregation)) {
           warnOnce(type.gqltype, 'aggregation', `Configuration issue: ${type.gqltype.name}.aggregation has the name `
             + `of the aggregation argument of ${type.listEntitiesEndpointName}_aggregate, so that endpoint cannot `
             + 'filter it with a top-level argument; filter it in AND/OR group conditions or rename the field.');
@@ -2166,6 +2503,7 @@ const buildRootQuery = (name, includedTypes, aggregationResultType = QLTypeAggre
             await executeMiddleware(params);
             await executeScope(params);
             await applyJoinedScopes(joinedScopes, params);
+            assertStoredQueryPaths(type.gqltype, params.args, 'aggregate');
             return adapter.aggregate(type.model, type.gqltype, params.args, null);
           },
         };
@@ -2270,7 +2608,7 @@ const holdsNoData = (stored, type, ancestors = []) => !ancestors.includes(stored
 // which buildInputType leaves out; nor do referenced collections or members with an application
 // resolver, which may compute a value.
 const countsAsRequired = (type, memberName, member) => member.type instanceof GraphQLNonNull
-  && !isReferencedCollection(member) && memberName !== 'id' && !member.extensions?.readOnly
+  && !isReferencedCollection(member) && memberName !== 'id' && !isReadOnlyField(member)
   && !isAbstractOutputType(unwrapListAndNonNull(member.type)) && !hasApplicationResolver(type, memberName);
 const hasRequiredMember = (type) => Object.entries(type.getFields())
   .some(([memberName, member]) => countsAsRequired(type, memberName, member));
@@ -2365,6 +2703,23 @@ const warnOnce = (gqltype, key, message) => {
   console.warn(message);
 };
 
+// A connectionField names a field, never a path (assertPlainConnectionField), in every type a model
+// stores: the registered types and the embedded types they store, at any depth, whether or not an
+// embedded type is registered itself, as describeModels and MongoDB's generated models reach them.
+const assertPlainConnectionFields = () => {
+  const visited = new Set();
+  const visit = (gqltype) => {
+    if (visited.has(gqltype)) return;
+    visited.add(gqltype);
+    for (const [fieldName, field] of Object.entries(gqltype.getFields())) {
+      assertPlainConnectionField(gqltype.name, fieldName, field);
+      const named = field.extensions?.relation?.embedded && getNamedType(field.type);
+      if (named instanceof GraphQLObjectType) visit(named);
+    }
+  };
+  for (const { gqltype } of Object.values(typesDict.types)) visit(gqltype);
+};
+
 // A writable referenced collection without a child connectionField would store unlinked children
 // through generated nested writes and read none back, so it is rejected before anything is built.
 // One with its own resolver only warns, and its nested writes are rejected per request; a readOnly
@@ -2385,6 +2740,50 @@ const assertCollectionConnections = () => {
   }
 };
 
+// Virtual fields (`extensions.virtual`) of the object types a schema reaches, registered or not, and
+// the uses of them that registered types declare, are checked before anything is built
+// (INVALID_MODEL, 400). Returns whether any field is virtual.
+const assertVirtualFields = (schemaTypes) => {
+  let declared = false;
+  for (const type of schemaTypes) {
+    if (!(type instanceof GraphQLObjectType)) continue;
+    for (const [fieldName, field] of Object.entries(type.getFields())) {
+      if (assertVirtualDeclaration(type.name, fieldName, field, () => hasApplicationResolver(type, fieldName))) {
+        declared = true;
+      }
+      assertVirtualConnection(type, fieldName, field, () => hasApplicationResolver(type, fieldName));
+    }
+  }
+  for (const { gqltype, stateMachine } of Object.values(typesDict.types)) {
+    assertVirtualIndexes(gqltype);
+    assertVirtualStateField(gqltype, stateMachine);
+  }
+  return declared;
+};
+
+// A readOnly field with arguments and its own resolver is almost always computed, yet unless it is
+// virtual it is stored and filterable like any other field. References and collections, whose
+// storage is a link rather than the field's value and which cannot be virtual, are not reported.
+// The advice also names the settings it declares that a virtual field cannot, such as the
+// `relation: { embedded: true }` of a computed embedded value.
+const warnUndeclaredVirtualFields = () => {
+  for (const { gqltype } of Object.values(typesDict.types)) {
+    for (const [fieldName, field] of Object.entries(gqltype.getFields())) {
+      const relation = field.extensions?.relation;
+      if (!field.extensions?.readOnly || !field.args.length || isVirtualField(field)
+        || (relation && !relation.embedded) || !hasApplicationResolver(gqltype, fieldName)) continue;
+      const conflicts = virtualConflicts(field.extensions);
+      const removal = conflicts.length
+        ? ` and remove ${conflicts.length < 3 ? conflicts.join(' and ') : `${conflicts.slice(0, -1).join(', ')} and ${conflicts.at(-1)}`}`
+        : '';
+      warnOnce(gqltype, `undeclaredVirtual:${fieldName}`, `Configuration issue: ${gqltype.name}.${fieldName} is `
+        + 'readOnly and has arguments and its own resolver, but it is not virtual, so Simfinity describes it as '
+        + 'stored data: backends may store it, and list queries get a filter argument for it. If its resolver '
+        + `computes it, declare extensions: { virtual: true }${removal}.`);
+    }
+  }
+};
+
 const getRegistrations = () => Object.values(typesDict.types);
 
 // Application types that a schema with these allowlists contains, whatever else it reaches: the
@@ -2407,6 +2806,9 @@ const createSchema = (includedQueryTypes, includedMutationTypes, includedCustomM
   const schemaTypes = collectSchemaOutputTypes();
   schemaTypes.forEach(assertNotBoundElsewhere);
   schemaTypes.forEach(assertFieldsNotBoundElsewhere);
+  if (assertVirtualFields(schemaTypes)) virtualFieldsDeclared = true;
+  warnUndeclaredVirtualFields();
+  assertPlainConnectionFields();
   assertCollectionConnections();
   // An application type with the name of a field metadata type that an earlier schema fixed; one that
   // only generated types or the fields of an input object reach is found when the schema is
@@ -2555,14 +2957,8 @@ const autoGenerateResolvers = (gqltype) => {
         await executeMiddleware(params);
         await executeScope(params);
         await applyJoinedScopes(joinedScopes, params);
-        return adapter.findChildren(
-          relatedTypeInfo.model,
-          relatedTypeInfo.gqltype,
-          connection.storageFieldName,
-          parent._id ?? parent.id,
-          params.args,
-          null,
-        );
+        assertStoredQueryPaths(relatedType, params.args, 'find');
+        return loadChildren(relatedTypeInfo, connection, parent._id ?? parent.id, params.args, context);
       }, { simfinityQuery: { typeName: relatedType.name, operation: 'find' } });
       runtimeBoundTypes.set(gqltype, runtimeIdentity);
     } else if (fieldEntry.type instanceof GraphQLObjectType
@@ -2662,11 +3058,12 @@ const LIST_QUERY_ARGS = ['pagination', 'sort', 'AND', 'OR'];
 
 // `omit` is a collection's back-reference field, which its parent supplies, so it gets no filter.
 // A field named like a generated argument gets no top-level filter either; it is reported once.
+// A virtual field is not part of the query language, so it gets no filter at all.
 const createArgsForQuery = (gqltype, omit = null) => {
     const argsObject = {};
     const argTypes = gqltype.getFields();
     for (const name of LIST_QUERY_ARGS) {
-      if (name !== omit && Object.hasOwn(argTypes, name)) {
+      if (name !== omit && Object.hasOwn(argTypes, name) && !isVirtualField(argTypes[name])) {
         warnOnce(gqltype, name, `Configuration issue: ${gqltype.name}.${name} has the name of a generated list `
           + 'query argument, so list queries and collection fields cannot filter it with a top-level argument; '
           + 'filter it in AND/OR group conditions or rename the field.');
@@ -2674,7 +3071,7 @@ const createArgsForQuery = (gqltype, omit = null) => {
     }
 
     for (const [fieldEntryName, fieldEntry] of Object.entries(argTypes)) {
-      if (fieldEntryName === omit) continue;
+      if (fieldEntryName === omit || isVirtualField(fieldEntry)) continue;
       let filterType = null;
 
       if (fieldEntry.type instanceof GraphQLScalarType

package/src/virtual-fields.js

@@ -0,0 +1,135 @@
+import { getNamedType } from 'graphql';
+import SimfinityError from './errors/simfinity.error.js';
+import { getListShape, isVirtualField, VIRTUAL_MCP_MODES } from './relation-storage.js';
+
+// Internal checks of virtual field declarations (`extensions.virtual`), shared by createSchema() and
+// describeModels(). A virtual field is resolved by its own resolver and stored nowhere, so every
+// setting or use that needs storage, a generated input or a query path is rejected.
+
+const invalid = (message) => {
+  throw new SimfinityError(message, 'INVALID_MODEL', 400);
+};
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+  && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+
+// Settings that describe storage, writes or the query language, which a virtual field has none of.
+// `readOnly: true` and `queryable: false` restate what virtual implies, so they are allowed.
+const CONFLICTING_SETTINGS = [
+  ['relation', (value) => !!value, 'extensions.relation'],
+  ['unique', (value) => value === true, 'unique: true'],
+  ['validations', (value) => !!value, 'extensions.validations'],
+  ['queryable', (value) => value === true, 'queryable: true'],
+  ['readOnly', (value) => value === false, 'readOnly: false'],
+];
+
+/**
+ * The settings of a field's extensions that a virtual field cannot declare, as its INVALID_MODEL message
+ * names them (such as 'extensions.relation'), in the order they are checked. Empty when it could be virtual.
+ */
+export const virtualConflicts = (extensions = {}) => CONFLICTING_SETTINGS
+  .filter(([key, conflicts]) => conflicts(extensions[key])).map(([, , setting]) => setting);
+
+const ownField = (type, name) => {
+  const fields = typeof type?.getFields === 'function' ? type.getFields() : null;
+  return fields && typeof name === 'string' && Object.hasOwn(fields, name) ? fields[name] : undefined;
+};
+
+// The virtual field that a stored path names or passes through, with the type that holds it, or null.
+// A MongoDB connectionField or index key may be a dotted path into embedded values, such as
+// `meta.key`, so each segment is a member of the embedded type that the previous segment holds. A
+// path stops at a segment that is not a declared field or not an embedded value: storage then has
+// no member to name there, and a reference stores only its own link, not its target's fields.
+const virtualFieldOnPath = (type, path) => {
+  let holder = type;
+  const segments = path.split('.');
+  for (const [index, segment] of segments.entries()) {
+    const field = ownField(holder, segment);
+    if (!field) return null;
+    if (isVirtualField(field)) return { holder, name: segment };
+    if (index === segments.length - 1 || !field.extensions?.relation?.embedded) return null;
+    holder = getNamedType(field.type);
+  }
+  return null;
+};
+
+// ` (through meta.key)` for a dotted path, so the message names the path that was declared.
+const throughPath = (path, found) => (path === found.name ? '' : ` (through ${path})`);
+
+/**
+ * Checks the `extensions.virtual` declaration of `typeName.fieldName` and returns whether the field is
+ * virtual. `hasOwnResolver()` tells whether the field has its own resolver; it is called only for a
+ * field that declares `virtual`. Throws INVALID_MODEL (400), naming the type and field, for a value
+ * other than `true` or a plain options object, an unknown option, an `mcp` option other than 'tool',
+ * 'select' or false, a missing resolver, a conflicting setting, and an identity field (`id` or `_id`).
+ */
+export const assertVirtualDeclaration = (typeName, fieldName, field, hasOwnResolver) => {
+  const extensions = field.extensions || {};
+  const { virtual } = extensions;
+  if (virtual === undefined) return false;
+  const name = `${typeName}.${fieldName}`;
+  if (virtual !== true) {
+    if (!isPlainObject(virtual)) invalid(`${name} extensions.virtual must be true or an options object such as { mcp: 'select' }`);
+    const unknown = Object.keys(virtual).find((key) => key !== 'mcp');
+    if (unknown !== undefined) invalid(`${name} extensions.virtual has the unknown option ${unknown}; its only option is mcp`);
+    if (virtual.mcp !== undefined && !VIRTUAL_MCP_MODES.includes(virtual.mcp)) {
+      invalid(`${name} extensions.virtual.mcp must be 'tool', 'select' or false`);
+    }
+  }
+  if (!hasOwnResolver()) invalid(`${name} is virtual, so it requires its own resolve function`);
+  const [setting] = virtualConflicts(extensions);
+  if (setting) invalid(`${name} is virtual, which is never stored, so it cannot declare ${setting}`);
+  if (fieldName === 'id' || fieldName === '_id') invalid(`${name} is the identity field, so it cannot be virtual`);
+  return true;
+};
+
+/**
+ * A reference stores its link under its connectionField, on its own type, and a collection reads its
+ * items by their type's connectionField, or by their own field name without one. Throws INVALID_MODEL
+ * (400) when that field is virtual, or when a dotted connectionField passes through or ends at a
+ * virtual member of an embedded type. `hasOwnResolver()` tells whether the application resolves the
+ * field itself, so that Simfinity never reads its items; it defaults to the field having a resolver.
+ */
+export const assertVirtualConnection = (type, fieldName, field, hasOwnResolver = () => typeof field.resolve === 'function') => {
+  const relation = field.extensions?.relation;
+  if (!relation || relation.embedded) return;
+  const listShape = getListShape(field.type);
+  const holder = listShape ? listShape.itemType : type;
+  const { connectionField } = relation;
+  // Storage keys the link by the declared value as a property name, so a non-string value reaches
+  // the same path as its string form. A collection without one, whose items Simfinity reads, reads
+  // them by its own field name.
+  let path = null;
+  if (connectionField !== undefined && connectionField !== null && connectionField !== '') path = String(connectionField);
+  else if (listShape && !hasOwnResolver()) path = fieldName;
+  const found = path ? virtualFieldOnPath(holder, path) : null;
+  if (found) {
+    invalid(`${type.name}.${fieldName} uses the virtual field ${found.holder.name}.${found.name} as its connectionField`
+      + `${throughPath(path, found)}; a virtual field is never stored`);
+  }
+};
+
+/**
+ * Throws INVALID_MODEL (400) when an entry of the type's `extensions.indexes` names a virtual field, or a
+ * dotted key that passes through or ends at a virtual member of an embedded type.
+ */
+export const assertVirtualIndexes = (type) => {
+  const indexes = type.extensions?.indexes;
+  if (!Array.isArray(indexes)) return;
+  for (const index of indexes) {
+    for (const name of Array.isArray(index?.fields) ? index.fields : []) {
+      const found = typeof name === 'string' ? virtualFieldOnPath(type, name) : null;
+      if (found) {
+        invalid(`An index of ${type.name} names the virtual field ${found.holder.name}.${found.name}`
+          + `${throughPath(name, found)}, which is never stored`);
+      }
+    }
+  }
+};
+
+/** Throws INVALID_MODEL (400) when the `state` field of a type with a state machine is virtual. */
+export const assertVirtualStateField = (type, stateMachine) => {
+  if (stateMachine && isVirtualField(ownField(type, 'state'))) {
+    invalid(`${type.name}.state holds the state of its state machine, so it cannot be virtual`);
+  }
+};

package/types/auth/index.d.ts

@@ -8,6 +8,7 @@ export type {
   AuthPluginOptions,
   AuthRule,
   AuthRuleFunction,
+  AuthSchemaPlugin,
   EnvelopSchemaPlugin,
   PermissionSchema,
   PolicyExpression,

package/types/index.d.ts

@@ -43,7 +43,65 @@ export interface ModelDescription {
     indexes: Array<{ fields: string[]; unique: boolean }>;
   }>;
 }
+/**
+ * Describes the stored data of the registered entities and the embedded types they reach. Virtual
+ * fields are left out of every entity and embedded type, and the types only they reach are not
+ * described. Throws `INVALID_MODEL` (400) for an invalid `extensions.virtual` declaration, as
+ * `createSchema()` does (see {@link VirtualFieldOptions}).
+ */
 export function describeModels(registrations: ModelRegistration[]): ModelDescription;
+/**
+ * Options of a virtual field. A field declares itself virtual with `extensions: { virtual: true }` or
+ * `extensions: { virtual: { mcp } }` (see {@link VirtualFieldDeclaration}), and must have its own
+ * `resolve`, which receives the record, the field's arguments and the request context. No backend
+ * stores it, generated inputs leave it out, and it is not part of the query language: list,
+ * aggregate and collection fields have no filter argument for it, a client filter, sort, `groupId`
+ * or fact path through it fails with `FORBIDDEN_FILTER_PATH` (403), and a path that middleware or a
+ * scope adds through it fails with `INVALID_MODEL` (500). Virtual implies `readOnly`, and
+ * introspection reads `extensions { readOnly }` as true for it. Any output type may be its
+ * result, registered or not; a registered type needs no `relation`, and gets no reference or
+ * collection storage and no inferred inverse reference.
+ *
+ * `createSchema()` and `describeModels()` throw `INVALID_MODEL` (400), naming the type and field, for
+ * a value other than `true` or a plain options object, an unknown option, an invalid `mcp` value, a
+ * field without its own `resolve`, a field that also declares `relation`, `unique: true`,
+ * `validations`, `queryable: true` or `readOnly: false`, an identity field (`id` or `_id`), and for a
+ * virtual field named in the type's `extensions.indexes`, used as the `state` field of its state
+ * machine, or used as the `connectionField` of a reference or a collection.
+ */
+export interface VirtualFieldOptions {
+  /**
+   * How generated MCP tools read the field. `'tool'`, the default, generates a
+   * `<byIdQuery>_<field>` read tool for a field with a required argument on a type with a generated
+   * by-ID query. `'select'` also lets tools select a field without required arguments below a list
+   * position, as in the records of list tools and the items of nested collections, where each item
+   * runs its resolver; elsewhere, such as at the top of by-ID results, tools always select it. A
+   * field with a required argument still gets its tool. `false` generates no per-field tool, and
+   * changes nothing else: by-ID and mutation tools still select a field without required
+   * arguments, so for such a field `'tool'` and `false` behave the same.
+   */
+  mcp?: 'tool' | 'select' | false;
+}
+/** The value of a virtual field's `extensions.virtual`. */
+export type VirtualFieldDeclaration = true | VirtualFieldOptions;
+/** A GraphQL field, or its configuration, as far as the virtual field helpers read it. */
+export interface VirtualFieldCandidate {
+  readonly extensions?: Readonly<{ [name: string]: unknown }> | null;
+}
+/**
+ * Whether a field is virtual: its `extensions.virtual` is `true`, or a plain object whose only key is
+ * a valid `mcp`. The GraphQL types that `DatabaseAdapter.prepare()` and `createModel()` receive still
+ * contain virtual fields, so an adapter that builds storage from a type's fields skips the fields for
+ * which this returns true, on entities and embedded types alike. In a schema that `createSchema()`
+ * accepted, every field that declares `extensions.virtual` (other than `undefined`) is virtual,
+ * because it rejects every other value.
+ */
+export function isVirtualField(field: VirtualFieldCandidate | null | undefined): boolean;
+/**
+ * The normalized options of a virtual field, `{ mcp }` with `mcp` defaulting to `'tool'`, or null
+ * when the field is not virtual (see {@link isVirtualField}).
+ */
+export function virtualFieldOptions(field: VirtualFieldCandidate | null | undefined): Required<VirtualFieldOptions> | null;
 /**
  * Creates the scalar `${name}_${baseScalarType.name}`. `validate` throws to reject a value and
  * receives the base scalar's internal value: the base's `parseValue` result for variables, the
@@ -222,7 +280,10 @@ export interface Runtime<Model = any, Session = any> {
    * non-empty child `connectionField`, whose resolver this runtime would generate, throws
    * `INVALID_MODEL` (400) before `adapter.prepare()`; one with an application resolver or
    * `readOnly` only logs a `Configuration issue` warning, and its nested writes fail with
-   * `INVALID_MODEL` (500). Fields named like generated query arguments also log a warning. The
+   * `INVALID_MODEL` (500). Fields named like generated query arguments also log a warning. Invalid
+   * virtual field declarations throw `INVALID_MODEL` (400) before `adapter.prepare()` (see
+   * {@link VirtualFieldOptions}), and a `readOnly` field with arguments and its own resolver that is
+   * not virtual, and is not a reference or collection, logs a `Configuration issue` warning once. The
    * first schema binds the types whose relation resolvers it generates to this runtime and
    * reserves reachable types that still have a
    * non-embedded relation field without a resolver, such as an unregistered custom mutation result.
@@ -272,7 +333,16 @@ export interface Runtime<Model = any, Session = any> {
 export interface DatabaseAdapter<Model = any, Session = any> {
   bind?(runtime: Pick<Runtime<Model, Session>, 'getModel' | 'getType' | 'getRegistrations'>): void;
   validateRegistration?(registration: RuntimeRegistration<Model, Session>): void;
+  /**
+   * Optional. Receives every registration before models are created. Their GraphQL types, like the
+   * type that `createModel()` receives, still contain virtual fields (`extensions.virtual`), which
+   * must never be stored: an adapter that builds storage from a type's fields skips each field for
+   * which {@link isVirtualField} returns true, on the types its embedded fields reach as well, or
+   * builds it from `describeModels(registrations)`, which leaves them out. Generated writes, filters,
+   * sorts and aggregations never name a virtual field; a controller hook can still assign one.
+   */
   prepare?(registrations: RuntimeRegistration<Model, Session>[], options: { createCollection: boolean }): void;
+  /** Creates the model of a registered type. Its fields include virtual fields; see `prepare()`. */
   createModel(type: GraphQLObjectType, callback: ((model: Model) => void) | null | undefined, options: { createCollection: boolean }): Model;
   /**
    * Casts a reference or batch key to the stored identifier type. Throw a `SimfinityError` with
@@ -296,8 +366,8 @@ export interface DatabaseAdapter<Model = any, Session = any> {
    * value unchanged. It must depend only on the value: these resolvers read no data and do not bind
    * their types, so a runtime that reaches a shared type may read through another runtime's hook.
    * Simfinity then reads as null an object that holds no data when a non-null member would read as
-   * null, whatever the selection. These members do not count: `id`, readOnly members, interface and
-   * union members, members with their own resolver and referenced collections. An object whose type
+   * null, whatever the selection. These members do not count: `id`, readOnly and virtual members,
+   * interface and union members, members with their own resolver and referenced collections. An object whose type
    * has no member that counts is returned untouched. Otherwise Simfinity reads the stored members
    * (see `rawEmbeddedValue`), never calling a getter, and counts a stored `_id` as `id`; an error
    * while reading them returns the object unchanged. Runtimes that share the type read through the
@@ -340,6 +410,41 @@ export interface DatabaseAdapter<Model = any, Session = any> {
   count(model: Model, type: GraphQLObjectType, args: any, session?: Session | null): Promise<number> | number;
   aggregate(model: Model, type: GraphQLObjectType, args: any, session?: Session | null): any;
   findChildren(model: Model, type: GraphQLObjectType, connectionField: string, parentId: any, args: any, session?: Session | null): any;
+  /**
+   * Optional batch form of `findChildren` for generated collection fields. The runtime calls it as
+   * an adapter method (`this` is the adapter) only when `batchesChildren` does not return false, and
+   * checks both members on every read. Within one request (a GraphQL context object), it groups the
+   * collection reads of one related type and connection storage field whose effective arguments
+   * (after middleware, the scope and joined scopes) hold the same plain data and are requested
+   * before the promise jobs queued so far have run, and calls this method with 2 to 100 distinct
+   * parent IDs: each one the raw ID the first of its fields read, never null, and one that `castId`
+   * accepts without changing its string form. A group with one distinct parent calls `findChildren`
+   * instead. `args` is a copy the method may change; it holds only plain data and dates, and its
+   * pagination is valid. `options.context` is the request context; the runtime passes no session.
+   *
+   * Return, or resolve to, one array per parent ID, in `parentIds` order, each holding exactly the
+   * records, order and page that `findChildren(model, type, connectionField, parentIds[i], args, null)`
+   * returns for that parent; the result must not depend on `options.context`. Records should show
+   * their parent under `connectionField` (or the connection field's GraphQL name), as `findChildren`
+   * records do, or not show one. Fields that read the same parent share its records, each with its
+   * own array. After a rejection or throw, or a result of another shape (not an array, another
+   * length, an entry that is not an array, or a record that shows another parent), each field reads
+   * alone with `findChildren`; a failure other than a `SimfinityError` and a result of another shape
+   * are reported once per type with `console.warn`. To keep per-parent reads for a model or field,
+   * return false from `batchesChildren`.
+   */
+  findChildrenBatch?: ((model: Model, type: GraphQLObjectType, connectionField: string, parentIds: any[], args: any, options?: { context?: any }) => any[][] | PromiseLike<any[][]>) | undefined;
+  /**
+   * Optional, synchronous. Return false to read the children of `model` through `connectionField`
+   * with one `findChildren` call per field, as an adapter without `findChildrenBatch` does: at once,
+   * with the arguments object the field built. The runtime calls it as an adapter method on every
+   * read that could join a batch. Return false whenever `findChildrenBatch` would not reproduce
+   * `this.findChildren`, such as when `this.findChildren` is not the adapter's own function (a copy
+   * or an `Object.assign` override that changes how children are read), or for a model whose reads
+   * have hooks or settings that a batched read would bypass. When it is absent, the runtime batches
+   * every read it can.
+   */
+  batchesChildren?: ((model: Model, type: GraphQLObjectType, connectionField: string) => boolean) | undefined;
 }
 export function createRuntime<Model = any, Session = any>(adapter: DatabaseAdapter<Model, Session>): Runtime<Model, Session>;
 
@@ -363,15 +468,34 @@ export function configureQueryLimits(options?: { maxPageSize?: number }): void;
 export function configureMutationLimits(options?: MutationLimitsOptions): void;
 export function paginationStages(pagination: { page: number; size: number } | null | undefined, withDefault: boolean): Array<{ $skip: number } | { $limit: number }>;
 
-/** Envelop-style schema plugin used by the shared authorization helpers. */
+/**
+ * Envelop-style schema plugin, as MCP `schemaPlugins` accepts it; `createAuthPlugin` returns the
+ * narrower {@link AuthSchemaPlugin}. `@simtlix/simfinity-mcp` re-exports this declaration, so
+ * `export *` of both packages exports one `EnvelopSchemaPlugin`.
+ */
 export interface EnvelopSchemaPlugin {
+  /**
+   * Wraps resolvers in place. MCP `schemaPlugins` awaits a returned promise; Envelop and Yoga do
+   * not, so plugins shared with them should install synchronously.
+   */
   onSchemaChange?: (payload: {
     schema: GraphQLSchema;
     replaceSchema: (schema: GraphQLSchema) => void;
-  }) => void;
+  }) => void | Promise<void>;
   [key: string]: unknown;
 }
 
+/**
+ * What `createAuthPlugin` returns: an {@link EnvelopSchemaPlugin} whose hook wraps the resolvers
+ * synchronously and returns nothing.
+ */
+export interface AuthSchemaPlugin extends EnvelopSchemaPlugin {
+  onSchemaChange?: (payload: {
+    schema: GraphQLSchema;
+    replaceSchema: (schema: GraphQLSchema) => void;
+  }) => void;
+}
+
 /** A single field validator (throws SimfinityError VALIDATION_ERROR on failure). */
 export interface FieldValidator {
   validate(typeName: string, fieldName: string, value: unknown, session?: unknown): Promise<void>;
@@ -505,7 +629,7 @@ export const auth: {
    * `onSchemaChange` throws TypeError, before wrapping any field, when a schema type was created
    * by another copy of the graphql module.
    */
-  createAuthPlugin(permissions: PermissionSchema, options?: AuthPluginOptions): EnvelopSchemaPlugin;
+  createAuthPlugin(permissions: PermissionSchema, options?: AuthPluginOptions): AuthSchemaPlugin;
   /** @deprecated Use createAuthPlugin instead. graphql-middleware compatible middleware. */
   createAuthMiddleware(
     permissions: PermissionSchema,
@@ -575,7 +699,7 @@ export const auth: {
 
 /** GraphQL server plugins: auth plugin factory plus count-extension plugins. */
 export const plugins: {
-  createAuthPlugin(permissions: PermissionSchema, options?: AuthPluginOptions): EnvelopSchemaPlugin;
+  createAuthPlugin(permissions: PermissionSchema, options?: AuthPluginOptions): AuthSchemaPlugin;
   /** Apollo Server plugin that copies `contextValue.count` into `extensions.count`. */
   apolloCountPlugin(): {
     requestDidStart(): Promise<{

package/types/plugins.d.ts

@@ -4,7 +4,7 @@
  */
 import { plugins } from './index.js';
 
-export type { AuthPluginOptions, EnvelopSchemaPlugin, PermissionSchema } from './index.js';
+export type { AuthPluginOptions, AuthSchemaPlugin, EnvelopSchemaPlugin, PermissionSchema } from './index.js';
 // The /auth declaration itself, as the runtime re-exports that binding, so the two subpaths can be
 // re-exported together.
 export { createAuthPlugin } from './auth/index.js';