@simtlix/simfinity-core 3.5.2 → 3.5.5

package/src/runtime.js

@@ -1,8 +1,10 @@
-import { configureQueryLimits, getQueryMaxPageSize } from './query-limits.js';
+import { configureQueryLimits, getQueryMaxPageSize, paginationStages } from './query-limits.js';
+import { configureMutationLimits, getMaxNestedOperations } from './mutation-limits.js';
 import {
   GraphQLObjectType, GraphQLString, GraphQLID, GraphQLSchema, GraphQLList,
   GraphQLNonNull, GraphQLInputObjectType, GraphQLScalarType,
-  GraphQLInt, GraphQLEnumType, GraphQLBoolean, Kind,
+  GraphQLInt, GraphQLEnumType, GraphQLBoolean, GraphQLError, GraphQLInterfaceType, GraphQLUnionType,
+  Kind, defaultFieldResolver, getNamedType,
 } from 'graphql';
 
 import SimfinityError from './errors/simfinity.error.js';
@@ -11,6 +13,11 @@ import QLOperator from './const/QLOperator.js';
 import QLValue from './const/QLValue.js';
 import QLSort from './const/QLSort.js';
 import { collectQueryPathEntries, collectQueryPaths, walkQueryPath } from './query-plan.js';
+import { relationFieldOwners } from './relation-owners.js';
+import { isThenable } from './auth/thenable.js';
+import {
+  getFieldStorageName, getListShape, markStoredIdentity, normalizeConnectionField,
+} from './relation-storage.js';
 import './introspection.js';
 
 // Resolvers Simfinity generates. Any other resolver on a registered type when its schema is first
@@ -28,8 +35,73 @@ const listApplicationResolvedFields = (gqltype) => new Set(Object.entries(gqltyp
 const hasApplicationResolver = (gqltype, fieldName) => (
   applicationResolvedFields.get(gqltype) || listApplicationResolvedFields(gqltype)
 ).has(fieldName);
+// Object types whose relation fields hold resolvers and filter arguments generated by one runtime,
+// mapped to that runtime. Those resolvers read through its adapter, registrations and middleware,
+// 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);
-const SCOPE_IGNORED_ARGS = new Set(['sort', 'pagination', 'aggregation']);
+
+// Query scopes restrict reads, so a scope Simfinity cannot run must fail rather than be skipped.
+const SCOPE_OPERATIONS = ['find', 'get_by_id', 'aggregate'];
+const invalidScope = (typeName, detail) => new SimfinityError(
+  `${typeName} extensions.scope ${detail}`, 'INVALID_SCOPE', 500,
+);
+const validateScope = (gqltype) => {
+  const extensions = gqltype.extensions || {};
+  if (!Object.hasOwn(extensions, 'scope')) return;
+  const { scope } = extensions;
+  if (!scope || typeof scope !== 'object' || Array.isArray(scope)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(scope))) {
+    throw invalidScope(gqltype.name, 'must be a plain object of find, get_by_id or aggregate functions');
+  }
+  // Every own string key, enumerable or not, because getScope reads any of them.
+  for (const operation of Object.getOwnPropertyNames(scope)) {
+    if (!SCOPE_OPERATIONS.includes(operation)) {
+      throw invalidScope(gqltype.name, `has unknown operation ${operation}; use find, get_by_id or aggregate`);
+    }
+    if (typeof scope[operation] !== 'function') {
+      throw invalidScope(gqltype.name, `${operation} must be a function`);
+    }
+  }
+};
+
+// Returns the type's scope function for an operation, or null when it declares none. Revalidates
+// on each call because extensions stay mutable after createSchema.
+const getScope = (gqltype, operation) => {
+  if (!gqltype?.extensions || !Object.hasOwn(gqltype.extensions, 'scope')) return null;
+  validateScope(gqltype);
+  const { scope } = gqltype.extensions;
+  return Object.hasOwn(scope, operation) ? scope[operation] : null;
+};
+
+const requireRegisteredType = (dict, type, fieldName, ownerName) => {
+  const registration = dict.types[type.name];
+  if (!registration) {
+    throw new SimfinityError(`Field ${ownerName ? `${ownerName}.` : ''}${fieldName} references ${type.name}, which is not `
+      + 'registered; register it with connect() or addNoEndpointType()', 'UNREGISTERED_RELATION_TARGET', 500);
+  }
+  return registration;
+};
+// A joined scope is a find scope, so `aggregation` is a field filter there, as on list queries.
+const SCOPE_IGNORED_ARGS = new Set(['sort', 'pagination']);
+
+// A joined scope cannot sort or paginate the records it restricts. Its sort and pagination values are
+// checked for shape only (INVALID_SORT: non-empty terms with a field and an ASC or DESC order;
+// INVALID_PAGINATION: as on direct queries), then ignored; sort field names are not resolved.
+const assertScopeControlArg = (name, value) => {
+  if (name === 'pagination') {
+    paginationStages(value, false);
+    return;
+  }
+  if (!Array.isArray(value.terms) || !value.terms.length) {
+    throw new SimfinityError('Sort requires non-empty terms', 'INVALID_SORT', 400);
+  }
+  for (const term of value.terms) {
+    if (typeof term?.field !== 'string' || !['ASC', 'DESC'].includes(term.order)) {
+      throw new SimfinityError('Sort terms require a field and an ASC or DESC order', 'INVALID_SORT', 400);
+    }
+  }
+};
 
 // Moves a joined type's scope group below the relation path that entered it.
 const prefixScopeGroup = (group, prefix) => {
@@ -53,7 +125,11 @@ const prefixScopeArgs = (scopeArgs, prefix, typeName) => {
   const conditions = [];
   const groups = [];
   for (const [name, value] of Object.entries(scopeArgs)) {
-    if (value == null || SCOPE_IGNORED_ARGS.has(name)) continue;
+    if (value == null) continue;
+    if (SCOPE_IGNORED_ARGS.has(name)) {
+      assertScopeControlArg(name, value);
+      continue;
+    }
     if (name === 'AND') groups.push(...[].concat(value).map((group) => prefixScopeGroup(group, prefix)));
     else if (name === 'OR') {
       const branches = [].concat(value);
@@ -105,22 +181,85 @@ const GraphQLJSON = new GraphQLScalarType({
   },
 });
 
-export const buildErrorFormatter = (callback) => {
-  const formatError = (err) => {
-    let result = null;
-    if (err instanceof SimfinityError) {
-      result = err;
-    } else {
-      result = new InternalServerError(err.message, err);
-    }
+// graphql-js wraps a value thrown while resolving a field (locatedError): the wrapper has the field
+// path and repeats the thrown error's message. A thrown non-Error becomes a NonErrorThrown whose
+// message prints the value.
+const isFieldErrorWrapper = (error) => Array.isArray(error.path) && error.originalError != null
+  && error.message === error.originalError.message
+  // locatedError adds no code of its own, so a thrown GraphQLError with its own code is not a wrapper.
+  && (error.originalError instanceof SimfinityError || typeof error.extensions?.code !== 'string'
+    || error.extensions === error.originalError.extensions);
+const thrownValueOf = (error) => (error.name === 'NonErrorThrown' && Object.hasOwn(error, 'thrownValue')
+  ? error.thrownValue : error);
+
+// The SimfinityError behind a GraphQLError, such as one a custom scalar threw, followed only through
+// GraphQLErrors; any other hidden cause is ignored.
+const simfinityCauseOf = (error) => {
+  let cause = error.originalError;
+  while (cause instanceof GraphQLError) cause = cause.originalError;
+  return cause instanceof SimfinityError ? cause : null;
+};
 
-    if (callback) {
-      const formattedError = callback(result);
-      return formattedError || result;
-    }
-    return result;
-  };
-  return formatError;
+// Request errors (syntax, validation, variable coercion) and application GraphQLErrors keep their own
+// message and extensions, such as the http status a server adds. A SimfinityError cause supplies only
+// the code and status, so a scalar's or application's hidden cause never replaces them.
+const classifyGraphQLError = (error) => {
+  const simfinity = simfinityCauseOf(error)?.extensions ?? {};
+  const extensions = error.extensions || {};
+  const code = [simfinity.code, extensions.code].find((value) => typeof value === 'string') ?? 'BAD_REQUEST';
+  const status = [simfinity.status, extensions.status].find(Number.isInteger)
+    ?? (code === 'INTERNAL_SERVER_ERROR' ? 500 : 400);
+  const classified = new SimfinityError(error.message, code, status);
+  classified.extensions = { ...extensions, ...classified.extensions };
+  return classified;
+};
+
+const classifyValue = (value) => {
+  if (value instanceof SimfinityError) return value;
+  if (value instanceof GraphQLError) return classifyGraphQLError(value);
+  // Never keep a non-Error value, such as a server's hook payload with request variables, as the cause.
+  return value instanceof Error
+    ? new InternalServerError(value.message, value)
+    : new InternalServerError('Unexpected error value');
+};
+
+// Errors raised while executing a field have a path; request errors (syntax, validation, variable
+// coercion) never do. GraphQL servers pass the GraphQLError that graphql-js created around the value
+// a resolver threw, and that value is classified, without unwrapping a GraphQLError the resolver
+// threw any further. A thrown GraphQLError that already has a path is passed as is.
+// graphql-js raises its own code-less GraphQLErrors there too when it cannot complete a value (scalar
+// or enum serialization, isTypeOf, abstract type resolution, a non-iterable list), and some print the
+// value. So a GraphQLError raised there is an application error only with its own code or a
+// SimfinityError cause; any other is unexpected.
+const classifyError = (error) => {
+  if (!(error instanceof GraphQLError)) return classifyValue(error);
+  if (!Array.isArray(error.path)) {
+    // Scalar validation errors can wrap a plain Error unchanged, with or without nodes. A server
+    // may report a source-stream failure in the same shape, so only an explicit internal cause
+    // identifies it as unexpected; applications must mark those failures at their source.
+    const cause = simfinityCauseOf(error);
+    return cause instanceof InternalServerError ? cause : classifyValue(error);
+  }
+  const thrown = isFieldErrorWrapper(error) ? thrownValueOf(error.originalError) : error;
+  if (thrown instanceof GraphQLError && typeof thrown.extensions?.code !== 'string' && !simfinityCauseOf(thrown)) {
+    return new InternalServerError(thrown.message, thrown);
+  }
+  return classifyValue(thrown);
+};
+
+export const buildErrorFormatter = (callback) => (error) => {
+  const classified = classifyError(error);
+  const chosen = (callback && callback(classified)) || classified;
+  if (chosen instanceof GraphQLError) return chosen;
+  const located = error instanceof GraphQLError ? error : null;
+  return new GraphQLError(chosen.message, {
+    nodes: located?.nodes,
+    source: located?.source,
+    positions: located?.positions,
+    path: located?.path,
+    originalError: chosen,
+    extensions: chosen.extensions && typeof chosen.extensions === 'object' ? { ...chosen.extensions } : {},
+  });
 };
 
 export { SimfinityError, InternalServerError };
@@ -152,6 +291,7 @@ export const createRuntime = (adapter) => {
   }
 
   const stateValue = adapter.stateValue || ((state) => state.name);
+  const runtimeIdentity = {};
   const typesDict = { types: {} };
   const waitingInputType = {};
   const typesDictForUpdate = { types: {} };
@@ -167,6 +307,9 @@ export const createRuntime = (adapter) => {
   };
 
   const use = (middleware) => {
+    if (typeof middleware !== 'function') {
+      throw new SimfinityError('Middleware must be a function', 'INVALID_MIDDLEWARE', 500);
+    }
     middlewares.push(middleware);
   };
 
@@ -176,6 +319,69 @@ export const createRuntime = (adapter) => {
     preventCollectionCreation = !!prevent;
   };
 
+  const assertNotBoundElsewhere = (gqltype) => {
+    const owner = runtimeBoundTypes.get(gqltype);
+    if (owner !== undefined && owner !== runtimeIdentity) {
+      throw new SimfinityError(
+        `Type ${gqltype.name} is bound to another Simfinity runtime. Its relation fields resolve through the runtime `
+          + 'that first created a schema reaching the type; define separate GraphQL types for each runtime, for example with a factory function',
+        'TYPE_BOUND_TO_OTHER_RUNTIME',
+        409,
+      );
+    }
+  };
+
+  const isForeign = (owner) => owner !== undefined && owner !== runtimeIdentity;
+  // A field copied, with toConfig() or a field spread, from a type after another runtime generated
+  // its relation resolver keeps that resolver or its extensions object. The extensions object counts
+  // only for a field whose resolver is untagged, such as one other code wrapped in place. A field
+  // without a resolver gets this runtime's own. graphql-js never runs interface field resolvers, so
+  // interface fields are not checked; the types they reference are.
+  const assertFieldsNotBoundElsewhere = (gqltype) => {
+    if (gqltype instanceof GraphQLInterfaceType) return;
+    for (const [fieldName, field] of Object.entries(gqltype.getFields())) {
+      if (!field.resolve) continue;
+      const resolverOwner = relationFieldOwners.get(field.resolve);
+      if (isForeign(resolverOwner)
+        || (resolverOwner === undefined && isForeign(relationFieldOwners.get(field.extensions)))) {
+        throw new SimfinityError(
+          `Field ${gqltype.name}.${fieldName} was copied from a relation field that another Simfinity runtime generated, `
+            + 'with its resolver or its extensions; define the field for each runtime instead of copying it from a type '
+            + 'that runtime already used',
+          'TYPE_BOUND_TO_OTHER_RUNTIME',
+          409,
+        );
+      }
+    }
+  };
+
+  // Object and interface types a schema of this runtime can reach from its registered types and
+  // custom mutation results, following the same references as GraphQLSchema.
+  const collectSchemaOutputTypes = () => {
+    const visited = new Set();
+    const outputTypes = [];
+    const visit = (type) => {
+      const named = type && getNamedType(type);
+      if (!named || visited.has(named)) return;
+      visited.add(named);
+      if (named instanceof GraphQLUnionType) {
+        named.getTypes().forEach(visit);
+        return;
+      }
+      if (!(named instanceof GraphQLObjectType || named instanceof GraphQLInterfaceType)) return;
+      outputTypes.push(named);
+      named.getInterfaces().forEach(visit);
+      for (const field of Object.values(named.getFields())) visit(field.type);
+    };
+    for (const { gqltype } of Object.values(typesDict.types)) visit(gqltype);
+    for (const { outputModel } of Object.values(registeredMutations)) visit(outputModel);
+    return outputTypes;
+  };
+
+  const hasUnresolvedRelation = (gqltype) => Object.values(gqltype.getFields()).some(
+    (field) => field.extensions?.relation && !field.extensions.relation.embedded && !field.resolve,
+  );
+
 const QLFilter = new GraphQLInputObjectType({
   name: 'QLFilter',
   fields: () => ({
@@ -296,46 +502,6 @@ const unwrapListAndNonNull = (type) => {
   return unwrapped;
 };
 
-const getListShape = (type) => {
-  const outerNonNull = type instanceof GraphQLNonNull;
-  const listType = unwrapNonNull(type);
-  if (!(listType instanceof GraphQLList)) return null;
-  const itemNonNull = listType.ofType instanceof GraphQLNonNull;
-  return {
-    outerNonNull,
-    itemNonNull,
-    itemType: unwrapNonNull(listType.ofType),
-  };
-};
-
-const getFieldStorageName = (fieldName, field) => {
-  const relation = field.extensions?.relation;
-  return relation && !relation.embedded && !getListShape(field.type)
-    ? relation.connectionField || fieldName
-    : fieldName;
-};
-
-const normalizeConnectionField = (childType, declaredFieldName) => {
-  if (!declaredFieldName) {
-    return { declaredFieldName, graphqlFieldName: null, storageFieldName: null };
-  }
-  const childFields = childType.getFields();
-  let graphqlFieldName = childFields[declaredFieldName] ? declaredFieldName : null;
-  if (!graphqlFieldName) {
-    const aliasedField = Object.entries(childFields).find(([fieldName, field]) => (
-      getFieldStorageName(fieldName, field) === declaredFieldName
-    ));
-    graphqlFieldName = aliasedField?.[0] || null;
-  }
-  return {
-    declaredFieldName,
-    graphqlFieldName,
-    storageFieldName: graphqlFieldName
-      ? getFieldStorageName(graphqlFieldName, childFields[graphqlFieldName])
-      : declaredFieldName,
-  };
-};
-
 const wrapListInputType = (itemType, listShape, preserveOuterNonNull) => {
   const wrappedItem = listShape.itemNonNull ? new GraphQLNonNull(itemType) : itemType;
   const listType = new GraphQLList(wrappedItem);
@@ -402,12 +568,13 @@ const createOneToManyInputType = (inputNamePrefix, fieldEntryName,
 };
 
 const graphQLListInputType = (dict, fieldEntry, fieldEntryName,
-  inputNamePrefix, connectionField, preserveOuterNonNull) => {
+  inputNamePrefix, connectionField, preserveOuterNonNull, ownerName) => {
   const listShape = getListShape(fieldEntry.type);
   if (!listShape) return null;
   const { itemType } = listShape;
 
-  if (itemType instanceof GraphQLObjectType && dict.types[itemType.name].inputType) {
+  if (itemType instanceof GraphQLObjectType
+    && requireRegisteredType(dict, itemType, fieldEntryName, ownerName).inputType) {
     if (!fieldEntry.extensions || !fieldEntry.extensions.relation
       || !fieldEntry.extensions.relation.embedded) {
       const oneToMany = createOneToManyInputType(inputNamePrefix, fieldEntryName,
@@ -471,7 +638,8 @@ const buildInputType = (gqltype) => {
               fieldArg.type = fieldEntry.type instanceof GraphQLNonNull
                 ? new GraphQLNonNull(IdInputType) : IdInputType;
               fieldArgForUpdate.type = IdInputType;
-            } else if (typesDict.types[fieldEntryNameValue].inputType
+            } else if (requireRegisteredType(typesDict, unwrapNonNull(fieldEntry.type), fieldEntryName,
+              gqltype.name).inputType
               && typesDictForUpdate.types[fieldEntryNameValue].inputType) {
               fieldArg.type = typesDict.types[fieldEntryNameValue].inputType;
               fieldArgForUpdate.type = typesDictForUpdate.types[fieldEntryNameValue].inputType;
@@ -488,10 +656,10 @@ const buildInputType = (gqltype) => {
           } else {
             const listInputTypeForAdd = graphQLListInputType(typesDict, fieldEntry,
               fieldEntryName, `${gqltype.name}A`,
-              fieldEntry.extensions?.relation?.connectionField, true);
+              fieldEntry.extensions?.relation?.connectionField, true, gqltype.name);
             const listInputTypeForUpdate = graphQLListInputType(typesDictForUpdate, fieldEntry,
               fieldEntryName, `${gqltype.name}U`,
-              fieldEntry.extensions?.relation?.connectionField, false);
+              fieldEntry.extensions?.relation?.connectionField, false, gqltype.name);
             if (listInputTypeForAdd && listInputTypeForUpdate) {
               fieldArg.type = listInputTypeForAdd;
               fieldArgForUpdate.type = listInputTypeForUpdate;
@@ -640,8 +808,7 @@ const materializeModel = async (args, gqltype, linkToParent, operation, session)
         || isNonNullOfType(fieldEntry.type, GraphQLObjectType)) {
         if (fieldEntry.extensions && fieldEntry.extensions.relation) {
           if (!fieldEntry.extensions.relation.embedded) {
-            const connectionField = fieldEntry.extensions.relation.connectionField || fieldEntryName;
-            modelArgs[connectionField] = adapter.castId(args[fieldEntryName].id);
+            modelArgs[getFieldStorageName(fieldEntryName, fieldEntry)] = adapter.castId(args[fieldEntryName].id);
           } else {
             const fieldType = fieldEntry.type instanceof GraphQLNonNull
               ? fieldEntry.type.ofType : fieldEntry.type;
@@ -778,6 +945,25 @@ const completeEmbeddedValue = (fieldName, fieldEntry, value, patch = null) => {
   }
 };
 
+// An explicit null for a nullable member of a singular embedded patch clears that member, as a
+// top-level null clears a field. Lists become empty lists; other members, including nested embedded
+// objects and references (under their storage name), are stored as null rather than removed, since
+// a removed nested object is materialized again from its list defaults. A null for a non-null member
+// keeps the stored value, also as at the top level. Nested objects in the patch replace the stored
+// ones wholesale.
+const clearNullEmbeddedMembers = (merged, fieldEntry, patch) => {
+  if (!patch || typeof patch !== 'object') return;
+  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;
+    const relation = member.extensions?.relation;
+    const listShape = getListShape(member.type);
+    if (relation && !relation.embedded && listShape) continue;
+    merged[getFieldStorageName(memberName, member)] = listShape ? [] : null;
+  }
+};
+
 const onUpdateSubject = async (Model, gqltype, controller, args, session, linkToParent, context) => {
   const materializedModel = await materializeModel(args, gqltype, linkToParent, 'UPDATE', session);
   const objectId = args.id;
@@ -801,6 +987,8 @@ const onUpdateSubject = async (Model, gqltype, controller, args, session, linkTo
             completeEmbeddedValue(fieldEntryName, argTypes[fieldEntryName], newObjectData);
           } else {
             materializedModel.modelArgs[fieldEntryName] = { ...oldObjectData, ...newObjectData };
+            clearNullEmbeddedMembers(materializedModel.modelArgs[fieldEntryName],
+              argTypes[fieldEntryName], args[fieldEntryName]);
             completeEmbeddedValue(fieldEntryName, argTypes[fieldEntryName],
               materializedModel.modelArgs[fieldEntryName], newObjectData);
           }
@@ -811,13 +999,9 @@ 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)) {
-      const relation = fieldEntry.extensions?.relation;
-      const storageFieldName = relation && !relation.embedded && !(unwrapNonNull(fieldEntry.type) instanceof GraphQLList)
-        ? relation.connectionField || fieldEntryName
-        : fieldEntryName;
       materializedModel.modelArgs.$unset = {
         ...materializedModel.modelArgs.$unset,
-        [storageFieldName]: '',
+        [getFieldStorageName(fieldEntryName, fieldEntry)]: '',
       };
     }
   }
@@ -898,14 +1082,81 @@ const onSaveObject = async (Model, gqltype, controller, args, session, linkToPar
 
 const saveObject = async (typeName, args, session, context) => {
   const type = typesDict.types[typeName];
+  assertCollectionWrites(type.gqltype, args);
   const snapshot = cloneInput(args, type.inputType);
   return adapter.withTransaction(session, (transaction) => onSaveObject(
     type.model, type.gqltype, type.controller, cloneInput(snapshot, type.inputType), transaction, null, context,
   ), type.model);
 };
 
+// Counts the added, updated and deleted entries of referenced collections, at every nesting level that
+// iterateOnCollectionFields executes, and stops once the configured maximum is exceeded.
+const assertNestedOperations = (gqltype, input, limit, state = { count: 0 }) => {
+  if (!input || typeof input !== 'object') return;
+  for (const [fieldName, field] of Object.entries(gqltype.getFields())) {
+    const value = input[fieldName];
+    const relation = field.extensions?.relation;
+    const listShape = getListShape(field.type);
+    if (value == null || !relation || relation.embedded || !listShape
+      || !(listShape.itemType instanceof GraphQLObjectType)) continue;
+    for (const key of ['added', 'updated', 'deleted']) {
+      if (!Array.isArray(value[key])) continue;
+      state.count += value[key].length;
+      if (state.count > limit) {
+        throw new SimfinityError(`A mutation may perform at most ${limit} nested collection operations`,
+          'NESTED_OPERATIONS_EXCEEDED', 400);
+      }
+      if (key !== 'deleted') {
+        for (const item of value[key]) assertNestedOperations(listShape.itemType, item, limit, state);
+      }
+    }
+  }
+};
+
+// A referenced collection links each child to its parent through the child's connectionField.
+const hasConnectionField = (relation) => typeof relation.connectionField === 'string'
+  && relation.connectionField !== '';
+const isUnlinkedCollection = (field) => {
+  const relation = field.extensions?.relation;
+  const listShape = getListShape(field.type);
+  return !!relation && !relation.embedded && !!listShape
+    && listShape.itemType instanceof GraphQLObjectType && !hasConnectionField(relation);
+};
+// Null entries are skipped by every nested operation, so a list of only nulls writes nothing.
+const hasNestedItems = (items) => !Array.isArray(items) || items.some((item) => item !== null);
+const unlinkedCollectionError = (gqltype, fieldName) => new SimfinityError(
+  `${gqltype.name}.${fieldName} cannot store nested items because it has no connectionField`,
+  'INVALID_MODEL',
+  500,
+);
+
+// Rejects nested items for a collection without a connectionField, at every nesting level that
+// iterateOnCollectionFields executes, before anything is written or any controller hook runs. Such a
+// collection only exists with its own resolver or as readOnly; createSchema rejects the others.
+const assertCollectionWrites = (gqltype, input) => {
+  if (!input || typeof input !== 'object') return;
+  for (const [fieldName, field] of Object.entries(gqltype.getFields())) {
+    const value = input[fieldName];
+    const relation = field.extensions?.relation;
+    const listShape = getListShape(field.type);
+    if (value == null || !relation || relation.embedded || !listShape
+      || !(listShape.itemType instanceof GraphQLObjectType)) continue;
+    for (const key of ['added', 'updated', 'deleted']) {
+      const items = value[key];
+      if (!items) continue;
+      if (!hasConnectionField(relation) && hasNestedItems(items)) throw unlinkedCollectionError(gqltype, fieldName);
+      if (key !== 'deleted' && Array.isArray(items)) {
+        for (const item of items) assertCollectionWrites(listShape.itemType, item);
+      }
+    }
+  }
+};
+
 const executeOperation = (Model, gqltype, controller, args, operation, actionField,
   session, context, inputType) => {
+  const limit = getMaxNestedOperations();
+  if (limit !== null && operation !== operations.DELETE) assertNestedOperations(gqltype, args, limit);
+  if (operation !== operations.DELETE) assertCollectionWrites(gqltype, args);
   const inputSnapshot = operation === operations.DELETE ? args : cloneInput(args, inputType);
   return adapter.withTransaction(
     session,
@@ -935,10 +1186,12 @@ const executeItemFunction = async (gqltype, collectionField, objectId, session,
   collectionFieldsList, operationType, context) => {
   const argTypes = gqltype.getFields();
   const collectionGQLType = unwrapListAndNonNull(argTypes[collectionField].type);
-  const connection = normalizeConnectionField(
-    collectionGQLType,
-    argTypes[collectionField].extensions.relation.connectionField,
-  );
+  const { relation } = argTypes[collectionField].extensions;
+  // Checked before the operation too; this also covers items that nested middleware added.
+  if (!hasConnectionField(relation) && hasNestedItems(collectionFieldsList)) {
+    throw unlinkedCollectionError(gqltype, collectionField);
+  }
+  const connection = normalizeConnectionField(collectionGQLType, relation.connectionField);
 
   const type = operationType === operations.UPDATE
     ? typesDictForUpdate.types[collectionGQLType.name] : typesDict.types[collectionGQLType.name];
@@ -982,39 +1235,41 @@ const executeItemFunction = async (gqltype, collectionField, objectId, session,
 const shouldNotBeIncludedInSchema = (includedTypes,
   type) => includedTypes && !includedTypes.includes(type);
 
+// Runs the chain in registration order. The rest of the chain runs at most once, and is awaited
+// even when a middleware calls next() without awaiting it, so its errors still cancel the operation
+// and never become unhandled rejections; a middleware that fails after starting it rejects only once
+// it settles. A next() called after the middleware finished does nothing, so later middleware never
+// runs after the operation.
 const executeMiddleware = async (context) => {
-  const buildNext = (middlewaresParam) => {
-    if (!middlewaresParam) {
-      return async () => {};
-    }
-    return async () => {
-      const middleware = middlewaresParam[0];
-      if (middleware) {
-        await middleware(context, buildNext(middlewaresParam.slice(1)));
+  const run = async (index) => {
+    if (index >= middlewares.length) return;
+    let downstream;
+    let finished = false;
+    const next = () => {
+      if (!downstream && !finished) {
+        downstream = run(index + 1);
+        // Handled here because the middleware may await other work first; awaited below.
+        downstream.catch(() => {});
       }
+      return downstream ?? Promise.resolve();
     };
+    try {
+      await middlewares[index](context, next);
+    } catch (error) {
+      finished = true;
+      if (downstream) await downstream.catch(() => {});
+      throw error;
+    }
+    finished = true;
+    if (downstream) await downstream;
   };
-
-  await buildNext(middlewares)();
+  await run(0);
 };
 
 const executeScope = async (params) => {
   const { type, args, operation, context } = params;
-
-  if (!type || !type.gqltype || !type.gqltype.extensions) {
-    return null;
-  }
-
-  const extensions = type.gqltype.extensions;
-  if (!extensions.scope || !extensions.scope[operation]) {
-    return null;
-  }
-
-  const scopeFunction = extensions.scope[operation];
-  if (typeof scopeFunction !== 'function') {
-    return null;
-  }
-
+  const scopeFunction = getScope(type?.gqltype, operation);
+  if (!scopeFunction) return null;
   return scopeFunction({ type, args, operation, context });
 };
 
@@ -1049,7 +1304,7 @@ const inspectClientPaths = (gqltype, args, operation) => {
       const relation = field.extensions?.relation;
       if (!relation || relation.embedded) return;
       const target = typesDict.types[unwrapListAndNonNull(field.type).name];
-      if (typeof target?.gqltype?.extensions?.scope?.find !== 'function') return;
+      if (!getScope(target?.gqltype, 'find')) return;
       if (!joinedScopes.has(path)) {
         joinedScopes.set(path, {
           target,
@@ -1210,7 +1465,7 @@ const loadReference = (type, id, requiredId, context) => {
 const resolveById = async (type, args, context, requiredId) => {
   const requestedId = args.id;
   await executeMiddleware({ type, args, operation: 'get_by_id', context });
-  if (!type.gqltype.extensions?.scope?.get_by_id) {
+  if (!getScope(type.gqltype, 'get_by_id')) {
     if (requiredId != null && args.id === requestedId && typeof context === 'object' && context !== null
       && typeof adapter.getByIds === 'function' && type.gqltype.getFields().id) {
       return loadReference(type, args.id, requiredId, context);
@@ -1359,10 +1614,6 @@ const buildRootQuery = (name, includedTypes) => {
     if (!shouldNotBeIncludedInSchema(includedTypes, type.gqltype)) {
       const wasAddedAsNoEnpointType = !type.simpleEntityEndpointName;
       if (!wasAddedAsNoEnpointType) {
-        if (type.gqltype.getFields().id && !type.gqltype.getFields().id.resolve) {
-          type.gqltype.getFields().id.resolve = markGenerated((parent) => parent._id);
-        }
-
         rootQueryArgs.fields[type.simpleEntityEndpointName] = {
           type: type.gqltype,
           args: { id: { type: GraphQLID } },
@@ -1371,9 +1622,7 @@ const buildRootQuery = (name, includedTypes) => {
           },
         };
 
-        const argTypes = type.gqltype.getFields();
-
-        const argsObject = createArgsForQuery(argTypes);
+        const argsObject = createArgsForQuery(type.gqltype);
 
         rootQueryArgs.fields[type.listEntitiesEndpointName] = {
           type: new GraphQLList(type.gqltype),
@@ -1407,6 +1656,11 @@ const buildRootQuery = (name, includedTypes) => {
         };
 
         const aggregateArgsObject = { ...argsObject };
+        if (Object.hasOwn(type.gqltype.getFields(), '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.');
+        }
         aggregateArgsObject.aggregation = {
           type: new GraphQLNonNull(QLTypeAggregationExpression),
         };
@@ -1436,7 +1690,9 @@ const buildRootQuery = (name, includedTypes) => {
   return new GraphQLObjectType(rootQueryArgs);
 };
 
+// Returns the registrations that a non-embedded relation of a registered type targets.
 const markReferencedTypesForModelGeneration = () => {
+  const referenced = new Set();
   Object.values(typesDict.types).forEach((typeInfo) => {
     Object.values(typeInfo.gqltype.getFields()).forEach((fieldEntry) => {
       const relation = fieldEntry.extensions?.relation;
@@ -1444,17 +1700,95 @@ const markReferencedTypesForModelGeneration = () => {
 
       const relatedType = unwrapListAndNonNull(fieldEntry.type);
       const relatedTypeInfo = typesDict.types[relatedType.name];
+      if (relatedTypeInfo) referenced.add(relatedTypeInfo);
       if (relatedTypeInfo && !relatedTypeInfo.endpoint) {
         relatedTypeInfo.needsModel = true;
       }
     });
   });
+  return referenced;
+};
+
+// Entity records keep their identity in `_id`; MongoDB records have no `id` value, while the SQL
+// store and other adapters may set both. Embedded-only types keep the default resolver, which
+// returns their declared `id` member.
+const installIdResolver = (gqltype) => {
+  const idField = gqltype.getFields().id;
+  if (idField && !idField.resolve) idField.resolve = markGenerated((parent) => parent._id ?? parent.id);
+};
+
+// An adapter that hydrates stored records may render an explicitly null singular embedded object as
+// an object (MongoDB nested paths do); readEmbeddedValue returns null for it. Nullable singular
+// embedded fields of registered types, and of the embedded types they reach, read through it. The
+// hook depends only on the value and reads no data, so these resolvers do not bind their types to
+// this runtime: another runtime that reaches a shared type reads the same value through it.
+// The value is read as graphql's default resolver reads it, so a method on the parent, such as one a
+// custom mutation result supplies, is still called; a promise it returns is read once it settles.
+const readEmbeddedField = markGenerated((parent, args, context, info) => {
+  const value = defaultFieldResolver(parent, args, context, info);
+  return isThenable(value)
+    ? value.then((resolved) => adapter.readEmbeddedValue(resolved))
+    : adapter.readEmbeddedValue(value);
+});
+
+const installEmbeddedValueResolvers = (gqltype, visited) => {
+  if (!(gqltype instanceof GraphQLObjectType) || visited.has(gqltype)) return;
+  visited.add(gqltype);
+  for (const fieldEntry of Object.values(gqltype.getFields())) {
+    if (fieldEntry.extensions?.relation?.embedded !== true) continue;
+    const listShape = getListShape(fieldEntry.type);
+    if (!listShape && !(fieldEntry.type instanceof GraphQLNonNull) && !fieldEntry.resolve) {
+      fieldEntry.resolve = readEmbeddedField;
+    }
+    installEmbeddedValueResolvers(listShape ? listShape.itemType : unwrapNonNull(fieldEntry.type), visited);
+  }
+};
+
+// Configuration issues this runtime already reported, per type, so a repeated createSchema call or a
+// type reached from several places logs each one once.
+const reportedIssues = new WeakMap();
+const warnOnce = (gqltype, key, message) => {
+  if (!reportedIssues.has(gqltype)) reportedIssues.set(gqltype, new Set());
+  const reported = reportedIssues.get(gqltype);
+  if (reported.has(key)) return;
+  reported.add(key);
+  console.warn(message);
+};
+
+// 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
+// one warns unless it has its own resolver.
+const assertCollectionConnections = () => {
+  for (const { gqltype } of Object.values(typesDict.types)) {
+    for (const [fieldName, field] of Object.entries(gqltype.getFields())) {
+      if (!isUnlinkedCollection(field)) continue;
+      const problem = `${gqltype.name}.${fieldName} requires a child connectionField`;
+      const readOnly = !!field.extensions.readOnly;
+      const ownResolver = hasApplicationResolver(gqltype, fieldName);
+      if (!readOnly && !ownResolver) throw new SimfinityError(problem, 'INVALID_MODEL', 400);
+      if (!readOnly || !ownResolver) {
+        warnOnce(gqltype, `connectionField:${fieldName}`,
+          `Configuration issue: ${problem}; nested writes through it are rejected`);
+      }
+    }
+  }
 };
 
 const getRegistrations = () => Object.values(typesDict.types);
 
 const createSchema = (includedQueryTypes, includedMutationTypes, includedCustomMutations) => {
-  markReferencedTypesForModelGeneration();
+  // Reject before models, resolvers or roots are built, so a rejected schema changes nothing.
+  Object.values(typesDict.types).forEach(({ gqltype }) => validateScope(gqltype));
+  const schemaTypes = collectSchemaOutputTypes();
+  schemaTypes.forEach(assertNotBoundElsewhere);
+  schemaTypes.forEach(assertFieldsNotBoundElsewhere);
+  assertCollectionConnections();
+  const referencedTypes = markReferencedTypesForModelGeneration();
+  // Entities, which keep their own stored identity: connect() types and relation targets.
+  Object.values(typesDict.types).forEach((typeInfo) => {
+    typeInfo.storedIdentity = typeInfo.endpoint === true || referencedTypes.has(typeInfo);
+  });
   if (adapter.prepare) {
     adapter.prepare(getRegistrations(), { createCollection: !preventCollectionCreation });
   }
@@ -1474,12 +1808,23 @@ const createSchema = (includedQueryTypes, includedMutationTypes, includedCustomM
   Object.keys(typesDict.types).forEach((typeName) => {
     if (typesDictForUpdate.types[typeName]) {
       typesDictForUpdate.types[typeName].model = typesDict.types[typeName].model;
+      typesDictForUpdate.types[typeName].storedIdentity = typesDict.types[typeName].storedIdentity;
     }
   });
 
+  // Every entity resolves `id`, whatever the query and mutation allowlists include. The type object
+  // is marked too, so query paths of any runtime that shares it follow the same identity.
+  const embeddedValueTypes = new Set();
   Object.values(typesDict.types).forEach((typeInfo) => {
     if (typeInfo.gqltype) {
+      if (typeInfo.storedIdentity) {
+        markStoredIdentity(typeInfo.gqltype);
+        installIdResolver(typeInfo.gqltype);
+      }
       autoGenerateResolvers(typeInfo.gqltype);
+      if (typeof adapter.readEmbeddedValue === 'function') {
+        installEmbeddedValueResolvers(typeInfo.gqltype, embeddedValueTypes);
+      }
     }
   });
 
@@ -1490,10 +1835,18 @@ const createSchema = (includedQueryTypes, includedMutationTypes, includedCustomM
     }
   });
 
-  return new GraphQLSchema({
+  const schema = new GraphQLSchema({
     query,
     mutation: buildMutation('Mutation', includedMutationTypes, includedCustomMutations),
   });
+  // Reserve reachable types whose relation fields still have no resolver, such as an unregistered
+  // custom mutation result, so another runtime cannot later generate resolvers this schema executes.
+  schemaTypes.forEach((type) => {
+    if (type instanceof GraphQLObjectType && hasUnresolvedRelation(type)) {
+      runtimeBoundTypes.set(type, runtimeIdentity);
+    }
+  });
+  return schema;
 };
 
 const getModel = (gqltype) => typesDict.types[gqltype.name]?.model;
@@ -1517,7 +1870,28 @@ const registerMutation = (name, description, inputModel, outputModel, callback)
   };
 };
 
+// Gives the field a new extensions object as well as the resolver, so a copy made before keeps
+// untagged extensions. It has a null prototype because graphql-js keeps such an object, rather than
+// copying it, when a type is rebuilt from toConfig().
+const claimRelationField = (fieldEntry, resolve, extensions = {}) => {
+  fieldEntry.extensions = Object.assign(Object.create(null), fieldEntry.extensions, extensions);
+  fieldEntry.resolve = markGenerated(resolve);
+  relationFieldOwners.set(fieldEntry.extensions, runtimeIdentity);
+  relationFieldOwners.set(fieldEntry.resolve, runtimeIdentity);
+};
+
+// The identifier a single reference reads is stored, not sent by the client, so one the adapter
+// rejects as malformed, such as a value written outside Simfinity, is a data error rather than a bad
+// request. Missing records and other errors keep their own classification.
+const storedReferenceError = (error, gqltype, fieldName) => {
+  if (!(error instanceof SimfinityError) || error.getCode() !== 'NOT_VALID_ID' || error.getStatus() !== 400) {
+    return error;
+  }
+  return new InternalServerError(`${gqltype.name}.${fieldName} stores an invalid identifier`, error);
+};
+
 const autoGenerateResolvers = (gqltype) => {
+  assertFieldsNotBoundElsewhere(gqltype);
   const fields = gqltype.getFields();
 
   for (const [fieldName, fieldEntry] of Object.entries(fields)) {
@@ -1532,16 +1906,11 @@ const autoGenerateResolvers = (gqltype) => {
         relatedType,
         relation.connectionField || fieldName,
       );
-      const relatedTypeInfo = typesDict.types[relatedType.name];
-      const argsObject = createArgsForQuery(relatedTypeInfo.gqltype.getFields());
-      if (connection.graphqlFieldName) delete argsObject[connection.graphqlFieldName];
+      const relatedTypeInfo = requireRegisteredType(typesDict, relatedType, fieldName, gqltype.name);
+      const argsObject = createArgsForQuery(relatedTypeInfo.gqltype, connection.graphqlFieldName);
 
       fieldEntry.args = formatArgs(Object.entries(argsObject));
-      fieldEntry.extensions = {
-        ...fieldEntry.extensions,
-        simfinityQuery: { typeName: relatedType.name, operation: 'find' },
-      };
-      fieldEntry.resolve = markGenerated(async (parent, args, context) => {
+      claimRelationField(fieldEntry, async (parent, args, context) => {
         if (!relatedTypeInfo || !relatedTypeInfo.model) {
           throw new Error(`Related type ${relatedType.name} not found or not connected. Make sure it's connected with simfinity.connect() or simfinity.addNoEndpointType().`);
         }
@@ -1554,25 +1923,33 @@ const autoGenerateResolvers = (gqltype) => {
           relatedTypeInfo.model,
           relatedTypeInfo.gqltype,
           connection.storageFieldName,
-          parent.id || parent._id,
+          parent._id ?? parent.id,
           params.args,
           null,
         );
-      });
+      }, { simfinityQuery: { typeName: relatedType.name, operation: 'find' } });
+      runtimeBoundTypes.set(gqltype, runtimeIdentity);
     } else if (fieldEntry.type instanceof GraphQLObjectType
       || (fieldEntry.type instanceof GraphQLNonNull && fieldEntry.type.ofType instanceof GraphQLObjectType)) {
       const relatedType = unwrapNonNull(fieldEntry.type);
-      const connectionField = relation.connectionField || fieldName;
+      const connectionField = getFieldStorageName(fieldName, fieldEntry);
 
-      fieldEntry.resolve = markGenerated(async (parent, args, context) => {
+      claimRelationField(fieldEntry, async (parent, args, context) => {
         const relatedTypeInfo = typesDict.types[relatedType.name];
         if (!relatedTypeInfo || !relatedTypeInfo.model) {
           throw new Error(`Related type ${relatedType.name} not found or not connected. Make sure it's connected with simfinity.connect() or simfinity.addNoEndpointType().`);
         }
-        const relatedId = parent[connectionField] || parent[fieldName];
-        const id = relatedId?._id || relatedId;
-        return id ? resolveById(relatedTypeInfo, { id: String(id) }, context, id) : null;
+        // Any stored identifier except null or an empty string, so numeric IDs such as 0 resolve.
+        const relatedId = parent[connectionField] ?? parent[fieldName];
+        const id = relatedId?._id ?? relatedId;
+        if (id == null || id === '') return null;
+        try {
+          return await resolveById(relatedTypeInfo, { id: String(id) }, context, id);
+        } catch (error) {
+          throw storedReferenceError(error, gqltype, fieldName);
+        }
       });
+      runtimeBoundTypes.set(gqltype, runtimeIdentity);
     }
   }
 };
@@ -1589,6 +1966,8 @@ const connect = (model, gqltype, simpleEntityEndpointName,
     stateMachine,
     onModelCreated,
   };
+  assertNotBoundElsewhere(gqltype);
+  validateScope(gqltype);
   if (adapter.validateRegistration) adapter.validateRegistration(registration);
 
   waitingInputType[gqltype.name] = {
@@ -1601,6 +1980,7 @@ const connect = (model, gqltype, simpleEntityEndpointName,
 };
 
 const addNoEndpointType = (gqltype) => {
+  assertNotBoundElsewhere(gqltype);
   const fields = gqltype.getFields();
   let needsModel = false;
   for (const fieldEntry of Object.values(fields)) {
@@ -1616,6 +1996,7 @@ const addNoEndpointType = (gqltype) => {
   const registration = {
     gqltype, endpoint: false, model: null, needsModel,
   };
+  validateScope(gqltype);
   if (adapter.validateRegistration) adapter.validateRegistration(registration);
 
   waitingInputType[gqltype.name] = { gqltype };
@@ -1623,10 +2004,24 @@ const addNoEndpointType = (gqltype) => {
   typesDictForUpdate.types[gqltype.name] = { ...typesDict.types[gqltype.name] };
 };
 
-const createArgsForQuery = (argTypes) => {
+// Arguments that every list query and collection field generates, after the field filters.
+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.
+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)) {
+        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.');
+      }
+    }
 
     for (const [fieldEntryName, fieldEntry] of Object.entries(argTypes)) {
+      if (fieldEntryName === omit) continue;
       argsObject[fieldEntryName] = {};
 
       if (fieldEntry.type instanceof GraphQLScalarType
@@ -1683,6 +2078,7 @@ function formatArgs(argsArray) {
 
   return {
     configureQueryLimits,
+    configureMutationLimits,
     connect,
     addNoEndpointType,
     createSchema,