@simtlix/simfinity-core 3.5.3 → 3.5.5

package/README.md

@@ -16,11 +16,13 @@ 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 it.
+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. When `getById` rejects a stored reference value that way, including one that `castId` rejected first, the generated reference field fails with an `InternalServerError`, since the client did not send the value. 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. The MongoDB adapter defines it.
+
+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`).
+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 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simtlix/simfinity-core",
-  "version": "3.5.3",
+  "version": "3.5.5",
   "description": "Driver-free GraphQL runtime and model metadata for Simfinity",
   "type": "module",
   "main": "./src/index.js",
@@ -15,6 +15,7 @@
     "./auth/expressions": "./src/auth/expressions.js",
     "./auth/rules": "./src/auth/rules.js",
     "./internal/object-id": "./src/auth/object-id.js",
+    "./internal/relation-storage": "./src/relation-storage.js",
     "./plugins": "./src/plugins.js",
     "./scalars": "./src/scalars.js",
     "./validators": "./src/validators.js"

package/src/query-plan.js

@@ -4,12 +4,17 @@ import SimfinityError from './errors/simfinity.error.js';
 const fail = (message, code = 'INVALID_FILTER_VALUE') => { throw new SimfinityError(message, code, 400); };
 const operators = new Set(['EQ', 'NE', 'LT', 'LTE', 'GT', 'GTE', 'BTW', 'IN', 'NIN', 'LIKE']);
 const reserved = new Set(['AND', 'OR', 'sort', 'pagination', 'aggregation']);
+// `aggregation` is a generated argument only on aggregate endpoints; on find and count a field of
+// that name is filtered like any other.
+const listReserved = new Set(['AND', 'OR', 'sort', 'pagination']);
+const controlArgs = (operation) => (operation === 'aggregate' ? reserved : listReserved);
 const listOf = (value) => (Array.isArray(value) ? value : []);
 
 /**
  * Internal: the model paths named by generated query arguments, as `{ segments, group }` entries.
  * Covers filter keys and relation terms, AND/OR conditions, list sort terms, and aggregation
- * groupId and fact paths; aggregate sort terms name result keys. `group` is the AND/OR group
+ * groupId and fact paths; aggregate sort terms name result keys. Outside aggregate mode a key
+ * named `aggregation` is a field filter like any other. `group` is the AND/OR group
  * object whose `conditions` hold the path, or null for the other forms. Malformed entries are
  * left to the backends.
  */
@@ -27,8 +32,9 @@ export const collectQueryPathEntries = (args, operation = 'find') => {
     }
     for (const item of [...listOf(group.AND), ...listOf(group.OR)]) visit(item);
   };
+  const controls = controlArgs(operation);
   for (const [name, value] of Object.entries(args)) {
-    if (reserved.has(name) || value == null) continue;
+    if (controls.has(name) || value == null) continue;
     const terms = listOf(value.terms).filter((term) => typeof term?.path === 'string' && term.path);
     if (terms.length) for (const term of terms) add(`${name}.${term.path}`);
     else add(name);
@@ -100,9 +106,9 @@ export const createQueryPlan = (models, entityName, input = {}, { mode = 'find'
     if (op === 'BTW' && value.length !== 2) fail('BTW requires two values');
     return { kind: 'predicate', path: Array.isArray(path) ? path : path.split('.'), operator: op, value: value === undefined ? null : value };
   };
-  const validateGroup = (value) => {
+  const validateGroup = (value, keys = ['conditions', 'AND', 'OR']) => {
     if (!value || typeof value !== 'object' || Array.isArray(value)) fail('Expected a filter group object');
-    for (const key of ['conditions', 'AND', 'OR']) if (value[key] != null && !Array.isArray(value[key])) fail(`${key} requires an array`);
+    for (const key of keys) if (value[key] != null && !Array.isArray(value[key])) fail(`${key} requires an array`);
   };
   const group = (value, depth = 0) => {
     validateGroup(value);
@@ -117,10 +123,12 @@ export const createQueryPlan = (models, entityName, input = {}, { mode = 'find'
     terms.push(combine('or', (value.OR || []).map((item) => group(item, depth + 1))));
     return combine('and', terms);
   };
-  validateGroup(input);
+  // Top-level arguments are field filters plus AND/OR; `conditions` only lists conditions inside groups.
+  validateGroup(input, ['AND', 'OR']);
+  const controls = controlArgs(mode);
   const terms = [];
   for (const [name, value] of Object.entries(input)) {
-    if (reserved.has(name) || value == null) continue;
+    if (controls.has(name) || value == null) continue;
     const field = resolveModelPath(models, entityName, name).at(-1);
     if (typeof value !== 'object' || Array.isArray(value)) fail('Expected a filter object');
     if (field.kind !== 'scalar' && !field.inferred && (!Array.isArray(value.terms) || !value.terms.length)) fail('Object filters require non-empty terms', 'MISSING_FILTER_PATH');

package/src/relation-storage.js

@@ -0,0 +1,58 @@
+import { GraphQLList, GraphQLNonNull } from 'graphql';
+
+// 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.
+
+const unwrapNonNull = (type) => (type instanceof GraphQLNonNull ? type.ofType : type);
+
+export 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),
+  };
+};
+
+export const getFieldStorageName = (fieldName, field) => {
+  const relation = field.extensions?.relation;
+  return relation && !relation.embedded && !getListShape(field.type)
+    ? relation.connectionField || fieldName
+    : fieldName;
+};
+
+// Entity types, which keep their own stored identity. The generated id resolver lives on the type
+// object, which runtimes may share, so the identity rule is per type object, not per runtime
+// registration: a store path for `id` follows the resolver any runtime installed on the type.
+const storedIdentityTypes = new WeakSet();
+
+export const markStoredIdentity = (gqltype) => {
+  storedIdentityTypes.add(gqltype);
+};
+
+export const hasStoredIdentity = (gqltype) => storedIdentityTypes.has(gqltype);
+
+export 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,
+  };
+};

package/src/runtime.js

@@ -1,10 +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, GraphQLError, GraphQLInterfaceType, GraphQLUnionType,
-  Kind, getNamedType,
+  Kind, defaultFieldResolver, getNamedType,
 } from 'graphql';
 
 import SimfinityError from './errors/simfinity.error.js';
@@ -14,6 +14,10 @@ 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
@@ -78,7 +82,26 @@ const requireRegisteredType = (dict, type, fieldName, ownerName) => {
   }
   return registration;
 };
-const SCOPE_IGNORED_ARGS = new Set(['sort', 'pagination', 'aggregation']);
+// 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) => {
@@ -102,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);
@@ -475,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);
@@ -821,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;
@@ -959,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;
@@ -982,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);
           }
@@ -992,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)]: '',
       };
     }
   }
@@ -1079,6 +1082,7 @@ 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,
@@ -1109,10 +1113,50 @@ const assertNestedOperations = (gqltype, input, limit, state = { count: 0 }) =>
   }
 };
 
+// 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,
@@ -1142,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];
@@ -1568,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 } },
@@ -1580,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),
@@ -1616,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),
         };
@@ -1645,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;
@@ -1653,11 +1700,79 @@ 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);
@@ -1668,7 +1783,12 @@ const createSchema = (includedQueryTypes, includedMutationTypes, includedCustomM
   const schemaTypes = collectSchemaOutputTypes();
   schemaTypes.forEach(assertNotBoundElsewhere);
   schemaTypes.forEach(assertFieldsNotBoundElsewhere);
-  markReferencedTypesForModelGeneration();
+  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 });
   }
@@ -1688,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);
+      }
     }
   });
 
@@ -1749,6 +1880,16 @@ const claimRelationField = (fieldEntry, resolve, extensions = {}) => {
   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();
@@ -1766,8 +1907,7 @@ const autoGenerateResolvers = (gqltype) => {
         relation.connectionField || fieldName,
       );
       const relatedTypeInfo = requireRegisteredType(typesDict, relatedType, fieldName, gqltype.name);
-      const argsObject = createArgsForQuery(relatedTypeInfo.gqltype.getFields());
-      if (connection.graphqlFieldName) delete argsObject[connection.graphqlFieldName];
+      const argsObject = createArgsForQuery(relatedTypeInfo.gqltype, connection.graphqlFieldName);
 
       fieldEntry.args = formatArgs(Object.entries(argsObject));
       claimRelationField(fieldEntry, async (parent, args, context) => {
@@ -1783,7 +1923,7 @@ const autoGenerateResolvers = (gqltype) => {
           relatedTypeInfo.model,
           relatedTypeInfo.gqltype,
           connection.storageFieldName,
-          parent.id || parent._id,
+          parent._id ?? parent.id,
           params.args,
           null,
         );
@@ -1792,16 +1932,22 @@ const autoGenerateResolvers = (gqltype) => {
     } 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);
 
       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);
     }
@@ -1858,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

package/types/index.d.ts

@@ -66,6 +66,10 @@ export class SimfinityError extends Error {
   getCode(): string | undefined;
   getStatus(): number | undefined;
   getTimestamp(): string;
+  /** Set on errors that wrap a driver error, such as MongoDB's TRANSACTION_RETRY_EXCEEDED. */
+  cause?: unknown;
+  /** Set on errors that wrap a driver error, such as MongoDB's TRANSACTION_RETRY_EXCEEDED; returns `cause`. */
+  getCause?(): unknown;
 }
 
 export class InternalServerError extends SimfinityError {
@@ -129,6 +133,14 @@ export interface RuntimeRegistration<Model = any, Session = any> extends ModelRe
   controller?: EntityController<Session> | null;
   onModelCreated?: ((model: Model) => void) | null;
   stateMachine?: StateMachine<Session> | null;
+  /**
+   * Set by `createSchema()` before `adapter.prepare()`: true for entity types, those registered
+   * with `connect()` and the targets of non-embedded relations, whose `id` resolves to the stored
+   * `_id`, falling back to `id`. False for types this runtime uses only as embedded values. The `id`
+   * rule follows the type object, so a type that another runtime sharing it treats as an entity
+   * resolves `id` the same way here.
+   */
+  storedIdentity?: boolean;
 }
 export interface MiddlewareContext {
   args: any;
@@ -194,9 +206,15 @@ export interface Runtime<Model = any, Session = any> {
    * (`TYPE_BOUND_TO_OTHER_RUNTIME`) any reachable type that another runtime bound or reserved, or
    * whose field was copied with `toConfig()` after another runtime generated its relation
    * resolver, keeping the generated resolver or its extensions. A list or embedded relation to an unregistered type throws
-   * `UNREGISTERED_RELATION_TARGET` (500). The first schema binds the types whose relation
-   * resolvers it generates to this runtime, and reserves reachable types that still have a
+   * `UNREGISTERED_RELATION_TARGET` (500). A writable non-embedded list relation without a
+   * 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
+   * 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.
+   * Every entity type resolves `id` to `_id ?? id`, whatever the allowlists include.
    */
   createSchema(includedQueryTypes?: GraphQLObjectType[] | null, includedMutationTypes?: GraphQLObjectType[] | null, includedCustomMutations?: string[] | null): GraphQLSchema;
   getModel(type: GraphQLObjectType | { name: string }): Model | null | undefined;
@@ -225,12 +243,29 @@ export interface DatabaseAdapter<Model = any, Session = any> {
   validateRegistration?(registration: RuntimeRegistration<Model, Session>): void;
   prepare?(registrations: RuntimeRegistration<Model, Session>[], options: { createCollection: boolean }): void;
   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
+   * code `NOT_VALID_ID` (400) for a malformed value; never create a new identifier. A batched
+   * reference read whose ID throws or is normalized reads that ID alone with `getById`. When
+   * `getById` rejects a stored reference with that error, the generated reference field fails with
+   * an `InternalServerError` whose cause is that error, since the client did not send the value.
+   */
   castId(value: any): any;
   stateValue?(state: { name: string; value: any }): any;
   withTransaction<T>(session: Session | null | undefined, callback: (session: Session) => Promise<T> | T, model?: Model): Promise<T>;
   newRecord(model: Model, data: any, session?: Session): any;
   saveRecord(model: Model, record: any, session?: Session): any;
   toObject(record: any): any;
+  /**
+   * Optional. When defined, every nullable, singular embedded object field without a resolver
+   * passes its value through `readEmbeddedValue(value)`. The field is read as graphql's default
+   * resolver reads it: a method on the parent is called with (args, context, info), and the hook
+   * receives its result once a returned promise settles. Return null for a value that a hydrated
+   * record renders as an object although the stored value is an explicit null; return any other
+   * 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.
+   */
+  readEmbeddedValue?(value: any): any;
   getById(model: Model, id: any, session?: Session | null, options?: { projection?: Record<string, number>; plain?: boolean; lock?: boolean; requiredId?: any; context?: any }): any;
   /** Optional batch read: the records found for `ids`, in getById shape and any order. After a failure, the runtime reads each ID with getById. */
   getByIds?(model: Model, ids: any[], options?: { context?: any }): any;