@simtlix/simfinity-core 3.8.0 → 3.10.0

package/src/runtime.js

@@ -4,7 +4,7 @@ import {
   GraphQLObjectType, GraphQLString, GraphQLID, GraphQLSchema, GraphQLList,
   GraphQLNonNull, GraphQLInputObjectType, GraphQLScalarType,
   GraphQLInt, GraphQLEnumType, GraphQLBoolean, GraphQLError, GraphQLInterfaceType, GraphQLUnionType,
-  Kind, getNamedType,
+  Kind, getNamedType, isObjectType, isOutputType,
 } from 'graphql';
 
 import SimfinityError from './errors/simfinity.error.js';
@@ -13,7 +13,11 @@ import { ForbiddenError } from './auth/errors.js';
 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 {
+  collectQueryOperators, collectQueryPathEntries, collectQueryPaths, walkQueryPath,
+} from './query-plan.js';
+import { QUERY_OPERATORS, isQueryOperator, resolveQueryFeatures } from './query-operators.js';
+import { assertEmptinessPath, describeEmptiness, isEmptinessOperator } from './query-emptiness.js';
 import { relationFieldOwners } from './relation-owners.js';
 import { isThenable } from './auth/thenable.js';
 import {
@@ -175,7 +179,10 @@ const prefixScopeArgs = (scopeArgs, prefix, typeName) => {
         throw new SimfinityError(`Scope filter ${typeName}.${name} requires non-empty terms`, 'MISSING_FILTER_PATH', 400);
       }
       for (const term of value.terms) {
-        conditions.push({ field: `${prefix}.${name}.${term?.path}`, operator: term?.operator, value: term?.value });
+        // An emptiness term without a path (omitted, null or "") tests the field itself; other
+        // operators keep the path as written.
+        const itself = isEmptinessOperator(term?.operator) && (term.path == null || term.path === '');
+        conditions.push({ field: itself ? `${prefix}.${name}` : `${prefix}.${name}.${term?.path}`, operator: term?.operator, value: term?.value });
       }
     } else conditions.push({ field: `${prefix}.${name}`, operator: value.operator, value: value.value });
   }
@@ -269,13 +276,22 @@ const assertFieldMetadataNamesFree = (roots) => {
   if (clash) throw reservedTypeNameError(clash);
 };
 
+const buildSchemaConfig = (query, mutation) => {
+  const config = { query };
+  if (Object.keys(mutation.getFields()).length > 0) {
+    config.mutation = mutation;
+  }
+  return config;
+};
+
 // Constructs the schema of these roots. When one of its types has the name of a field metadata type,
 // those are renamed SimfinityFieldExtensionsType and SimfinityRelationType, with a number appended
 // when the schema also has those names, in every schema the process constructs from then on. A
 // construction that fails puts the previous metadata types back, so only a schema that exists fixes
 // the names.
 const constructSchema = (query, mutation) => {
-  const roots = [query, mutation];
+  const config = buildSchemaConfig(query, mutation);
+  const roots = Object.values(config);
   const clash = fieldMetadataClash(roots);
   if (clash && fieldMetadataNamesFixed()) throw reservedTypeNameError(clash);
   let names = null;
@@ -290,7 +306,7 @@ const constructSchema = (query, mutation) => {
   const restore = names ? renameFieldMetadataTypes(...names) : null;
   let schema;
   try {
-    schema = new GraphQLSchema({ query, mutation });
+    schema = new GraphQLSchema(config);
   } catch (error) {
     if (restore) restore();
     throw error;
@@ -451,6 +467,10 @@ export const createRuntime = (adapter) => {
   if (!adapter) {
     throw new SimfinityError('A database adapter is required', 'ADAPTER_REQUIRED', 500);
   }
+  // The filter operators the adapter compiles, read once: its queryFeatures.operators, or the 3.7.0
+  // operators when it declares none.
+  const supportedOperators = resolveQueryFeatures(adapter.queryFeatures).operators;
+  const supportsEveryOperator = QUERY_OPERATORS.every((operator) => supportedOperators.has(operator));
 
   const stateValue = adapter.stateValue || ((state) => state.name);
   const runtimeIdentity = {};
@@ -466,6 +486,7 @@ export const createRuntime = (adapter) => {
   const selfCollectionNameHolders = new Map();
   const qualifiedSelfCollections = new Map();
   const registeredMutations = {};
+  const registeredQueries = {};
   const middlewares = [];
 
   const operations = {
@@ -474,6 +495,7 @@ export const createRuntime = (adapter) => {
     DELETE: 'delete',
     STATE_CHANGED: 'state_changed',
     CUSTOM_MUTATION: 'custom_mutation',
+    CUSTOM_QUERY: 'custom_query',
   };
 
   const use = (middleware) => {
@@ -526,7 +548,7 @@ export const createRuntime = (adapter) => {
   };
 
   // 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.
+  // custom operation results, following the same references as GraphQLSchema.
   const collectSchemaOutputTypes = () => {
     const visited = new Set();
     const outputTypes = [];
@@ -543,8 +565,13 @@ export const createRuntime = (adapter) => {
       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);
+    const registeredTypes = Object.values(typesDict.types).map(({ gqltype }) => gqltype);
+    const customOperations = [
+      ...Object.values(registeredMutations),
+      ...Object.values(registeredQueries),
+    ];
+    const customOutputTypes = customOperations.map(({ outputModel }) => outputModel);
+    [...registeredTypes, ...customOutputTypes].forEach(visit);
     return outputTypes;
   };
 
@@ -1267,10 +1294,15 @@ const materializeModel = async (args, gqltype, linkToParent, operation, session)
   return { modelArgs, collectionFields };
 };
 
-const executeRegisteredMutation = (args, callback, context, session, inputModel) => {
+// Custom queries run without a transaction or session; custom mutations run in one, which may retry.
+const executeRegisteredOperation = (args, registration, operation, context) => {
+  const { inputModel, callback } = registration;
+  if (operation === operations.CUSTOM_QUERY) {
+    return callback(cloneInput(args, inputModel), context);
+  }
   const nextInput = attemptInputs(args, inputModel);
   return adapter.withTransaction(
-    session,
+    null,
     (mySession) => callback(nextInput(), mySession, context),
   );
 };
@@ -1734,12 +1766,15 @@ const copyFilterGroups = (groups) => (Array.isArray(groups) ? groups.map((group)
 // client AND/OR groups whose conditions use each path, or `topLevel` for every other form.
 // graphql-js passes the same variable values to every resolver call of a request, so the client's
 // AND/OR groups are first copied onto this call's args, and joined scopes are only placed in those copies.
+// An emptiness condition on an embedded object reads its stored members, so their paths are checked
+// as client paths too (#108 part 2a); a member path only gets the 403 checks, and enters no joined
+// scope.
 const inspectClientPaths = (gqltype, args, operation) => {
   for (const key of ['AND', 'OR']) {
     if (Object.hasOwn(args, key)) args[key] = copyFilterGroups(args[key]);
   }
   const joinedScopes = new Map();
-  for (const { segments, group } of collectQueryPathEntries(args, operation)) {
+  for (const { segments, group, member } of collectQueryPathEntries(args, operation, { gqltype, expandMembers: true })) {
     walkQueryPath(gqltype, segments, ({ type, fieldName, field, index }) => {
       const path = segments.slice(0, index + 1).join('.');
       if (isVirtualField(field)) {
@@ -1749,6 +1784,7 @@ const inspectClientPaths = (gqltype, args, operation) => {
       if (queryable === false || (queryable !== true && hasApplicationResolver(type, fieldName))) {
         throw forbiddenPath(`Query path ${path} uses the non-queryable field ${type.name}.${fieldName}`);
       }
+      if (member) return;
       const relation = field.extensions?.relation;
       if (!relation || relation.embedded) return;
       const target = typesDict.types[unwrapListAndNonNull(field.type).name];
@@ -1787,6 +1823,105 @@ const assertStoredQueryPaths = (gqltype, args, operation) => {
   }
 };
 
+const assertDeclaredOperator = (gqltype, operator, path) => {
+  if (!supportedOperators.has(operator)) {
+    throw new SimfinityError(`The database adapter does not support the ${operator} filter operator, used on `
+      + `${gqltype.name}.${path}`, 'UNSUPPORTED_QUERY', 400);
+  }
+};
+
+// The checks of an emptiness condition (#108 part 2a) that come before rules 3 to 6 of
+// describeEmptiness, with the codes and messages of createQueryPlan: the group depth, a dotted field
+// next to a path, an emptiness operator on an object filter without terms or beside terms, the
+// fields of the path (rule 1), then the adapter's operators (rule 2). Returns false when the backends
+// never read the condition as one, so that rules 3 to 6 do not apply: a term of a field that is not
+// an object (they read that filter's own operator) and a condition without a string field (they
+// reject it their own way; when the adapter does not declare the operator, no compiler sees it, so
+// the gate gives createQueryPlan's rule-1 code).
+const assertEmptinessForm = (gqltype, {
+  operator, path, segments, form, field, depth, ambiguous,
+}) => {
+  if (form === 'condition') {
+    if (depth > MAX_FILTER_GROUP_DEPTH) throw new SimfinityError('Filter nesting too deep', 'FILTER_DEPTH_EXCEEDED', 400);
+    if (typeof field !== 'string') {
+      if (!supportedOperators.has(operator)) throw new SimfinityError('Invalid filter path', 'INVALID_FILTER_PATH', 400);
+      return false;
+    }
+    if (ambiguous) {
+      throw new SimfinityError('Filter condition cannot use both dotted field syntax and a separate path', 'AMBIGUOUS_FILTER_FIELD', 400);
+    }
+  } else {
+    assertEmptinessPath(gqltype, [field]);
+    const type = getNamedType(gqltype.getFields()[field].type);
+    if (isObjectType(type) && form !== 'term') {
+      throw new SimfinityError(`Filter on ${field} takes ${operator} only in a term; to test the field itself, use a term `
+        + `without a path: ${field}: { terms: [{ operator: ${operator} }] }`, 'MISSING_FILTER_PATH', 400);
+    }
+    if (form === 'term' && !isObjectType(type) && !(type instanceof GraphQLInterfaceType) && !(type instanceof GraphQLUnionType)) {
+      assertDeclaredOperator(gqltype, operator, path);
+      return false;
+    }
+  }
+  assertEmptinessPath(gqltype, segments, { path });
+  assertDeclaredOperator(gqltype, operator, path);
+  return true;
+};
+
+// Rejects a QLOperator value that the adapter does not declare in queryFeatures, with
+// UNSUPPORTED_QUERY (400), so an adapter never drops or misreads a condition it does not compile,
+// and applies to every IS_EMPTY or IS_NOT_EMPTY condition the order of checks of #108 part 2a,
+// whatever the adapter declares. Runs on the client's arguments before middleware and on the final
+// arguments before the adapter call, which covers what middleware, scopes and joined scopes added,
+// so that an emptiness condition gets the code that a direct createQueryPlan call gives, whoever
+// wrote it and whatever the caller may read. Operators that QLOperator does not list are left to the
+// adapter, which reports them as before.
+const assertQueryConditions = (gqltype, args, operation) => {
+  for (const entry of collectQueryOperators(args, operation)) {
+    const { operator, path } = entry;
+    if (isEmptinessOperator(operator)) {
+      if (assertEmptinessForm(gqltype, entry)) describeEmptiness(gqltype, entry.segments, { operator, value: entry.value, path });
+    } else if (!supportsEveryOperator && isQueryOperator(operator)) assertDeclaredOperator(gqltype, operator, path);
+  }
+};
+
+// Decision 3 of #108 part 2a: a target find scope with an emptiness condition is not applied below a
+// client's relation path, because the prefix makes the condition cross a reference, which 2a
+// rejects. Runs after the scoped-collection and assertJoinedScopePaths 403s. The raw scope arguments,
+// operators beside terms included, first get the checks they get on the target's own endpoint (the
+// stored paths, then each emptiness condition's), so that a rejection the scope has there keeps its
+// code; otherwise the request fails with UNSUPPORTED_QUERY naming the scope and the prefixed condition.
+// A prefix that continues inside an embedded list or a collection (`olines.shop`, `reviews.item`)
+// adds more than a reference crossing. After its form and operator, each prefixed condition is checked
+// on `rootType`, the queried type, where rule 3, which comes before rules 4 to 6, rejects it with the
+// permanent INVALID_FILTER_PATH that the final gate and createQueryPlan give it wherever it is written.
+const assertJoinedScopeConditions = (rootType, scopeArgs, groups, prefix, target) => {
+  const { gqltype } = target;
+  const entries = collectQueryOperators(scopeArgs, 'find').filter(({ operator }) => isEmptinessOperator(operator));
+  if (!entries.length) return;
+  assertStoredQueryPaths(gqltype, scopeArgs, 'find');
+  let throughList = false;
+  walkQueryPath(rootType, prefix.split('.'), ({ field }) => { throughList ||= !!getListShape(field.type); });
+  // Rule 6, here or on the target's own endpoint, is the rejection thrown below.
+  const exceptRule6 = (check) => {
+    try {
+      check();
+    } catch (error) {
+      if (!(error instanceof SimfinityError) || error.getCode() !== 'UNSUPPORTED_QUERY') throw error;
+    }
+  };
+  for (const entry of entries) {
+    if (!assertEmptinessForm(gqltype, entry)) continue;
+    const { operator, value } = entry;
+    if (throughList) exceptRule6(() => describeEmptiness(rootType, `${prefix}.${entry.path}`, { operator, value }));
+    exceptRule6(() => describeEmptiness(gqltype, entry.segments, { operator, value, path: entry.path }));
+  }
+  const prefixed = collectQueryOperators({ AND: groups }).find(({ operator }) => isEmptinessOperator(operator))
+    ?? { operator: entries[0].operator, path: `${prefix}.${entries[0].path}` };
+  throw new SimfinityError(`Query path ${prefix} enters ${gqltype.name}, whose find scope tests ${prefixed.path} with `
+    + `${prefixed.operator}: emptiness through references and collections arrives with reference emptiness (#108); `
+    + `until then, use EQ null in the ${gqltype.name} find scope`, 'UNSUPPORTED_QUERY', 400);
+};
+
 // A joined scope must not repeat the rows it restricts: its paths may not cross a collection, nor
 // reach a non-embedded relation inside an embedded list, which is joined once per list item.
 const assertJoinedScopePaths = (groups, prefix, target) => {
@@ -1845,6 +1980,7 @@ const applyJoinedScopes = async (joinedScopes, params) => {
     if (!groups.length) continue;
     if (collection) throw forbiddenPath(`Query path ${prefix} enters the scoped collection ${collection}`);
     assertJoinedScopePaths(groups, prefix, target);
+    assertJoinedScopeConditions(params.type.gqltype, scopeArgs, groups, prefix, target);
     queryGroups ??= collectFilterGroups(params.args);
     const addedDepth = 1 + Math.max(...groups.map(groupDepth));
     if (topLevel || [...owners].some((owner) => !queryGroups.has(owner)
@@ -1941,6 +2077,7 @@ const resolveById = async (type, args, context, requiredId) => {
   const queryArgs = { id: { operator: 'EQ', value: args.id } };
   await executeScope({ type, args: queryArgs, operation: 'get_by_id', context });
   assertStoredQueryPaths(type.gqltype, queryArgs, 'find');
+  assertQueryConditions(type.gqltype, queryArgs, 'find');
   const results = await adapter.find(type.model, type.gqltype, queryArgs, null, { requiredId, context });
   return results[0] || null;
 };
@@ -2261,6 +2398,33 @@ const withoutWritableFields = (type, { noWritableId = false } = {}) => {
   return `${type.gqltype.name} has no writable fields${state}${id}`;
 };
 
+const createArgsForRegisteredOperation = (inputModel) => {
+  if (!inputModel) return null;
+  return { input: { type: new GraphQLNonNull(inputModel) } };
+};
+
+const buildRegisteredOperationField = (entry, registration, operation) => {
+  const field = {
+    type: registration.outputModel,
+    description: registration.description,
+    args: createArgsForRegisteredOperation(registration.inputModel),
+    async resolve(parent, args, context) {
+      const params = {
+        args,
+        operation,
+        entry,
+        context,
+      };
+      await executeMiddleware(params);
+      return executeRegisteredOperation(args.input, registration, operation, context);
+    },
+  };
+  if (operation === operations.CUSTOM_MUTATION) {
+    field.extensions = { simfinityMutation: { operation } };
+  }
+  return field;
+};
+
 // Every generated mutation field carries extensions.simfinityMutation with its operation (and, for
 // a state-machine action, the action and its from/to states), so tools such as the MCP package can
 // classify it without guessing from its name. Extensions do not appear in SDL or introspection.
@@ -2396,32 +2560,15 @@ const buildMutation = (name, includedMutationTypes, includedCustomMutations) =>
 
   for (const [entry, registeredMutation] of Object.entries(registeredMutations)) {
     if (!shouldNotBeIncludedInSchema(includedCustomMutations, entry)) {
-      const argsObject = registeredMutation.inputModel
-        ? { input: { type: new GraphQLNonNull(registeredMutation.inputModel) } } : null;
-      rootQueryArgs.fields[entry] = {
-        type: registeredMutation.outputModel,
-        description: registeredMutation.description,
-        args: argsObject,
-        extensions: { simfinityMutation: { operation: operations.CUSTOM_MUTATION } },
-        async resolve(parent, args, context) {
-          const params = {
-            args,
-            operation: operations.CUSTOM_MUTATION,
-            entry,
-            context,
-          };
-          await executeMiddleware(params);
-          return executeRegisteredMutation(args.input, registeredMutation.callback,
-            context, null, registeredMutation.inputModel);
-        },
-      };
+      rootQueryArgs.fields[entry] = buildRegisteredOperationField(entry, registeredMutation,
+        operations.CUSTOM_MUTATION);
     }
   }
 
   return new GraphQLObjectType(rootQueryArgs);
 };
 
-const buildRootQuery = (name, includedTypes, aggregationResultType = QLTypeAggregationResult) => {
+const buildRootQuery = (name, includedTypes, aggregationResultType = QLTypeAggregationResult, includedCustomQueries = null) => {
   const rootQueryArgs = {};
   rootQueryArgs.name = name;
   rootQueryArgs.fields = {};
@@ -2448,6 +2595,7 @@ const buildRootQuery = (name, includedTypes, aggregationResultType = QLTypeAggre
           extensions: { simfinityQuery: { typeName: type.gqltype.name, operation: 'find', countSink: true } },
           async resolve(parent, args, context, info) {
             const joinedScopes = inspectClientPaths(type.gqltype, args, 'find');
+            assertQueryConditions(type.gqltype, args, 'find');
             const params = {
               type,
               args,
@@ -2458,6 +2606,7 @@ const buildRootQuery = (name, includedTypes, aggregationResultType = QLTypeAggre
             await executeScope(params);
             await applyJoinedScopes(joinedScopes, params);
             assertStoredQueryPaths(type.gqltype, params.args, 'find');
+            assertQueryConditions(type.gqltype, params.args, 'find');
             const queryArgs = params.args;
             const wantsCount = !!(queryArgs.pagination && queryArgs.pagination.count)
               && canReportCount(parent, info, context);
@@ -2494,6 +2643,7 @@ const buildRootQuery = (name, includedTypes, aggregationResultType = QLTypeAggre
           extensions: { simfinityQuery: { typeName: type.gqltype.name, operation: 'aggregate' } },
           async resolve(parent, args, context) {
             const joinedScopes = inspectClientPaths(type.gqltype, args, 'aggregate');
+            assertQueryConditions(type.gqltype, args, 'aggregate');
             const params = {
               type,
               args,
@@ -2504,6 +2654,7 @@ const buildRootQuery = (name, includedTypes, aggregationResultType = QLTypeAggre
             await executeScope(params);
             await applyJoinedScopes(joinedScopes, params);
             assertStoredQueryPaths(type.gqltype, params.args, 'aggregate');
+            assertQueryConditions(type.gqltype, params.args, 'aggregate');
             return adapter.aggregate(type.model, type.gqltype, params.args, null);
           },
         };
@@ -2511,6 +2662,13 @@ const buildRootQuery = (name, includedTypes, aggregationResultType = QLTypeAggre
     }
   }
 
+  for (const [entry, registeredQuery] of Object.entries(registeredQueries)) {
+    if (!shouldNotBeIncludedInSchema(includedCustomQueries, entry)) {
+      rootQueryArgs.fields[entry] = buildRegisteredOperationField(entry, registeredQuery,
+        operations.CUSTOM_QUERY);
+    }
+  }
+
   return new GraphQLObjectType(rootQueryArgs);
 };
 
@@ -2786,22 +2944,66 @@ const warnUndeclaredVirtualFields = () => {
 
 const getRegistrations = () => Object.values(typesDict.types);
 
+const includedOperationTypes = (registrations, includedOperations) => Object.entries(registrations)
+  .filter(([entry]) => !shouldNotBeIncludedInSchema(includedOperations, entry))
+  .flatMap(([, { inputModel, outputModel }]) => [inputModel, outputModel].filter(Boolean));
+
 // Application types that a schema with these allowlists contains, whatever else it reaches: the
-// endpoint types of its queries and mutations, and the input and output types of its registered
-// mutations.
-const includedApplicationTypes = (includedQueryTypes, includedMutationTypes, includedCustomMutations) => [
+// endpoint types of its queries and mutations, and the input and output types of its custom operations.
+const includedApplicationTypes = (includedQueryTypes, includedMutationTypes, includedCustomMutations, includedCustomQueries) => [
   ...Object.values(typesDict.types)
     .filter((type) => type.endpoint
       && ((type.simpleEntityEndpointName && !shouldNotBeIncludedInSchema(includedQueryTypes, type.gqltype))
         || !shouldNotBeIncludedInSchema(includedMutationTypes, type.gqltype)))
     .map((type) => type.gqltype),
-  ...Object.entries(registeredMutations)
-    .filter(([entry]) => !shouldNotBeIncludedInSchema(includedCustomMutations, entry))
-    .flatMap(([, { inputModel, outputModel }]) => [inputModel, outputModel].filter(Boolean)),
+  ...includedOperationTypes(registeredMutations, includedCustomMutations),
+  ...includedOperationTypes(registeredQueries, includedCustomQueries),
 ];
 
-const createSchema = (includedQueryTypes, includedMutationTypes, includedCustomMutations) => {
+const queryNameConflict = (name) => new SimfinityError(
+  `Query ${name} is already registered or conflicts with a generated query in this schema`,
+  'QUERY_NAME_CONFLICT', 500,
+);
+
+const assertQueryNamesAvailable = (includedQueryTypes, includedCustomQueries) => {
+  for (const type of Object.values(typesDict.types)) {
+    if (!type.simpleEntityEndpointName || shouldNotBeIncludedInSchema(includedQueryTypes, type.gqltype)) continue;
+    for (const name of [type.simpleEntityEndpointName, type.listEntitiesEndpointName, `${type.listEntitiesEndpointName}_aggregate`]) {
+      if (Object.hasOwn(registeredQueries, name) && !shouldNotBeIncludedInSchema(includedCustomQueries, name)) {
+        throw queryNameConflict(name);
+      }
+    }
+  }
+};
+
+const invalidSchemaOptions = (detail) => new SimfinityError(
+  `createSchema options ${detail}`, 'INVALID_SCHEMA_OPTIONS', 500,
+);
+
+const SCHEMA_OPTION_KEYS = new Set(['includedCustomQueries']);
+
+// The fourth createSchema() argument: omitted, or a plain object with known keys only.
+const readSchemaOptions = (options) => {
+  if (options === undefined) return {};
+  if (options === null || typeof options !== 'object' || !isPlainObject(options)) {
+    throw invalidSchemaOptions('must be a plain object');
+  }
+  const unknown = Reflect.ownKeys(options).find((key) => !SCHEMA_OPTION_KEYS.has(key));
+  if (unknown !== undefined) {
+    throw invalidSchemaOptions(`has an unknown option ${String(unknown)}`);
+  }
+  const { includedCustomQueries } = options;
+  if (includedCustomQueries != null && (!Array.isArray(includedCustomQueries)
+    || includedCustomQueries.some((name) => typeof name !== 'string'))) {
+    throw invalidSchemaOptions('includedCustomQueries must be an array of strings, null or undefined');
+  }
+  return { includedCustomQueries };
+};
+
+const createSchema = (includedQueryTypes, includedMutationTypes, includedCustomMutations, options) => {
   // Reject before models, resolvers or roots are built, so a rejected schema changes nothing.
+  const { includedCustomQueries } = readSchemaOptions(options);
+  assertQueryNamesAvailable(includedQueryTypes, includedCustomQueries);
   Object.values(typesDict.types).forEach(({ gqltype }) => validateScope(gqltype));
   const schemaTypes = collectSchemaOutputTypes();
   schemaTypes.forEach(assertNotBoundElsewhere);
@@ -2814,7 +3016,7 @@ const createSchema = (includedQueryTypes, includedMutationTypes, includedCustomM
   // only generated types or the fields of an input object reach is found when the schema is
   // constructed.
   assertFieldMetadataNamesFree(includedApplicationTypes(includedQueryTypes, includedMutationTypes,
-    includedCustomMutations));
+    includedCustomMutations, includedCustomQueries));
   const referencedTypes = markReferencedTypesForModelGeneration();
   // Entities, which keep their own stored identity: connect() types and relation targets.
   Object.values(typesDict.types).forEach((typeInfo) => {
@@ -2862,7 +3064,7 @@ const createSchema = (includedQueryTypes, includedMutationTypes, includedCustomM
   const objectMemberTypes = new Set();
   Object.values(typesDict.types).forEach(({ gqltype }) => installObjectMemberResolvers(gqltype, objectMemberTypes));
 
-  let query = buildRootQuery('RootQueryType', includedQueryTypes);
+  let query = buildRootQuery('RootQueryType', includedQueryTypes, undefined, includedCustomQueries);
   Object.values(typesDict.types).forEach(({ gqltype }) => {
     if (gqltype && !applicationResolvedFields.has(gqltype)) {
       applicationResolvedFields.set(gqltype, listApplicationResolvedFields(gqltype));
@@ -2873,12 +3075,13 @@ const createSchema = (includedQueryTypes, includedMutationTypes, includedCustomM
   // other type named JSON still collides, and GraphQLSchema reports the duplicate name.
   const applicationJSON = findSchemaType([query, mutation], 'JSON', QLTypeAggregationResult);
   if (applicationJSON instanceof GraphQLScalarType) {
-    query = buildRootQuery('RootQueryType', includedQueryTypes, aggregationResultTypeFor(applicationJSON));
+    query = buildRootQuery('RootQueryType', includedQueryTypes, aggregationResultTypeFor(applicationJSON),
+      includedCustomQueries);
   }
 
   const schema = constructSchema(query, mutation);
   // 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.
+  // custom operation result, so another runtime cannot later generate resolvers this schema executes.
   schemaTypes.forEach((type) => {
     if (type instanceof GraphQLObjectType && hasUnresolvedRelation(type)) {
       runtimeBoundTypes.set(type, runtimeIdentity);
@@ -2908,6 +3111,43 @@ const registerMutation = (name, description, inputModel, outputModel, callback)
   };
 };
 
+const invalidQueryRegistration = (detail) => new SimfinityError(
+  `registerCustomQuery ${detail}`, 'INVALID_QUERY_REGISTRATION', 500,
+);
+
+const validateQueryRegistration = (name, registration) => {
+  const { description, inputModel, outputModel, callback } = registration;
+  if (typeof name !== 'string' || !/^[_A-Za-z][_0-9A-Za-z]*$/.test(name) || name.startsWith('__')) {
+    throw invalidQueryRegistration('requires a valid GraphQL field name that does not start with __');
+  }
+  if (description != null && typeof description !== 'string') {
+    throw invalidQueryRegistration('description must be a string');
+  }
+  if (inputModel != null && !(inputModel instanceof GraphQLInputObjectType)) {
+    throw invalidQueryRegistration('input must be a GraphQLInputObjectType, null or undefined');
+  }
+  if (!isOutputType(outputModel)) {
+    throw invalidQueryRegistration('output must be a GraphQL output type');
+  }
+  if (typeof callback !== 'function') {
+    throw invalidQueryRegistration('callback must be a function');
+  }
+};
+
+const registerCustomQuery = (name, description, inputModel, outputModel, callback) => {
+  const registration = {
+    description,
+    inputModel,
+    outputModel,
+    callback,
+  };
+  validateQueryRegistration(name, registration);
+  if (Object.hasOwn(registeredQueries, name)) {
+    throw queryNameConflict(name);
+  }
+  registeredQueries[name] = registration;
+};
+
 // 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().
@@ -2953,11 +3193,13 @@ const autoGenerateResolvers = (gqltype) => {
           throw new Error(`Related type ${relatedType.name} not found or not connected. Make sure it's connected with simfinity.connect() or simfinity.addNoEndpointType().`);
         }
         const joinedScopes = inspectClientPaths(relatedType, args, 'find');
+        assertQueryConditions(relatedType, args, 'find');
         const params = { type: relatedTypeInfo, args, operation: 'find', context };
         await executeMiddleware(params);
         await executeScope(params);
         await applyJoinedScopes(joinedScopes, params);
         assertStoredQueryPaths(relatedType, params.args, 'find');
+        assertQueryConditions(relatedType, params.args, 'find');
         return loadChildren(relatedTypeInfo, connection, parent._id ?? parent.id, params.args, context);
       }, { simfinityQuery: { typeName: relatedType.name, operation: 'find' } });
       runtimeBoundTypes.set(gqltype, runtimeIdentity);
@@ -3142,6 +3384,7 @@ function formatArgs(argsArray) {
     getRegistrations,
     use,
     registerMutation,
+    registerCustomQuery,
     saveObject,
     preventCreatingCollection,
   };