@simtlix/simfinity-core 3.6.0 → 3.7.0

package/README.md

@@ -18,6 +18,8 @@ For relational storage, `@simtlix/simfinity-sql` builds on core and delegates ph
 
 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.
 
+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.

package/package.json

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

package/src/runtime.js

@@ -1916,6 +1916,312 @@ const resolveById = async (type, args, context, requiredId) => {
   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 } = {}) => {
@@ -2555,14 +2861,7 @@ 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,
-        );
+        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

package/types/auth/index.d.ts

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

package/types/index.d.ts

@@ -340,6 +340,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 +398,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 +559,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 +629,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';