@simtlix/simfinity-core 3.9.0 → 3.11.0

package/src/runtime.js

@@ -1,10 +1,12 @@
-import { configureQueryLimits, getQueryMaxPageSize, paginationStages } from './query-limits.js';
+import {
+  configureQueryLimits, getQueryMaxPageSize, getQueryMaxReferenceFrames, 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, getNamedType, isObjectType, isOutputType,
 } from 'graphql';
 
 import SimfinityError from './errors/simfinity.error.js';
@@ -17,6 +19,9 @@ import {
   collectQueryOperators, collectQueryPathEntries, collectQueryPaths, walkQueryPath,
 } from './query-plan.js';
 import { QUERY_OPERATORS, isQueryOperator, resolveQueryFeatures } from './query-operators.js';
+import {
+  assertEmptinessPath, describeEmptiness, emptinessScopePaths, emptinessScopeTargets, isEmptinessOperator,
+} from './query-emptiness.js';
 import { relationFieldOwners } from './relation-owners.js';
 import { isThenable } from './auth/thenable.js';
 import {
@@ -178,7 +183,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 });
   }
@@ -272,13 +280,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;
@@ -293,7 +310,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;
@@ -455,8 +472,12 @@ export const createRuntime = (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;
+  // operators when it declares none. With queryFeatures.referenceEmptiness, it also compiles
+  // IS_EMPTY and IS_NOT_EMPTY through references and collections (#108 part 2b), and a client's
+  // conditions of that kind carry a scope marker from the runtime (see markClientConstructs).
+  const {
+    operators: supportedOperators, referenceEmptiness: supportsReferenceEmptiness,
+  } = resolveQueryFeatures(adapter.queryFeatures);
   const supportsEveryOperator = QUERY_OPERATORS.every((operator) => supportedOperators.has(operator));
 
   const stateValue = adapter.stateValue || ((state) => state.name);
@@ -473,6 +494,7 @@ export const createRuntime = (adapter) => {
   const selfCollectionNameHolders = new Map();
   const qualifiedSelfCollections = new Map();
   const registeredMutations = {};
+  const registeredQueries = {};
   const middlewares = [];
 
   const operations = {
@@ -481,6 +503,7 @@ export const createRuntime = (adapter) => {
     DELETE: 'delete',
     STATE_CHANGED: 'state_changed',
     CUSTOM_MUTATION: 'custom_mutation',
+    CUSTOM_QUERY: 'custom_query',
   };
 
   const use = (middleware) => {
@@ -533,7 +556,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 = [];
@@ -550,8 +573,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;
   };
 
@@ -1274,10 +1302,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),
   );
 };
@@ -1725,28 +1758,69 @@ const executeScope = async (params) => {
   return scopeFunction({ type, args, operation, context });
 };
 
-// Copies AND/OR group lists with new group objects and arrays, leaving conditions and other values
-// shared.
-const copyFilterGroups = (groups) => (Array.isArray(groups) ? groups.map((group) => {
-  if (!group || typeof group !== 'object' || Array.isArray(group)) return group;
-  const copy = { ...group };
-  if (Array.isArray(group.conditions)) copy.conditions = [...group.conditions];
-  if (Object.hasOwn(group, 'AND')) copy.AND = copyFilterGroups(group.AND);
-  if (Object.hasOwn(group, 'OR')) copy.OR = copyFilterGroups(group.OR);
+// The arguments of a list, aggregate or collection field call that are not filters. On aggregate
+// endpoints `aggregation` is one; elsewhere a field of that name is filtered like any other.
+const LIST_CONTROL_ARGS = new Set(['sort', 'pagination']);
+const AGGREGATE_CONTROL_ARGS = new Set(['sort', 'pagination', 'aggregation']);
+const isFilterObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+// A new object with the same prototype and own enumerable properties: graphql-js builds inline literals
+// with a null prototype and variables with Object's, and childArgsKey tells them apart.
+const copyFilterObject = (value) => Object.assign(Object.create(Object.getPrototypeOf(value)), value);
+// A term, a group condition or a field filter: a value array becomes a new Array with the same items.
+const copyFilterCondition = (condition) => {
+  if (!isFilterObject(condition)) return condition;
+  const copy = copyFilterObject(condition);
+  if (Array.isArray(condition.value)) copy.value = [...condition.value];
   return copy;
-}) : groups);
+};
+const copyFilterGroup = (group) => {
+  if (!isFilterObject(group)) return group;
+  const copy = copyFilterObject(group);
+  if (Array.isArray(group.conditions)) copy.conditions = group.conditions.map(copyFilterCondition);
+  if (Array.isArray(group.AND)) copy.AND = group.AND.map(copyFilterGroup);
+  if (Array.isArray(group.OR)) copy.OR = group.OR.map(copyFilterGroup);
+  return copy;
+};
+const copyFieldFilter = (filter) => {
+  const copy = copyFilterCondition(filter);
+  if (isFilterObject(filter) && Array.isArray(filter.terms)) copy.terms = filter.terms.map(copyFilterCondition);
+  return copy;
+};
+
+// A tree copy of the query-language structure of one call's filter arguments, onto that call's args:
+// field filters and their terms, AND/OR groups and their conditions. Every place gets its own object,
+// also where graphql-js hands one variable object to several arguments or list items, so that a
+// middleware edit or a client scope marker stays within the call. Value arrays are copied shallowly,
+// and every other value, sort, pagination and aggregation included, is kept as it is. GraphQL input
+// has no cycles, so nothing is memoized.
+const copyClientFilters = (args, operation) => {
+  const controls = operation === 'aggregate' ? AGGREGATE_CONTROL_ARGS : LIST_CONTROL_ARGS;
+  for (const [name, value] of Object.entries(args)) {
+    if (name === 'AND' || name === 'OR') {
+      if (Array.isArray(value)) args[name] = value.map(copyFilterGroup);
+    } else if (!controls.has(name)) args[name] = copyFieldFilter(value);
+  }
+};
 
 // Checks the filter, sort and aggregation paths a client supplied, before middleware and scopes
 // add trusted paths. Returns the scoped relations those paths enter, keyed by path, with the
 // 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.
+// filters are first copied onto this call's args (copyClientFilters), 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. When the adapter compiles reference emptiness (#108 part 2b), a client's emptiness term or
+// condition reads its references and collections through scoped joins and frames instead, so it
+// enters no joined scope either; every other entry, beside it or on the same path, records its own.
 const inspectClientPaths = (gqltype, args, operation) => {
-  for (const key of ['AND', 'OR']) {
-    if (Object.hasOwn(args, key)) args[key] = copyFilterGroups(args[key]);
-  }
+  copyClientFilters(args, operation);
   const joinedScopes = new Map();
-  for (const { segments, group } of collectQueryPathEntries(args, operation)) {
+  const entries = collectQueryPathEntries(args, operation, { gqltype, expandMembers: true });
+  for (const {
+    segments, group, member, operator,
+  } of entries) {
+    const joins = !member && !(supportsReferenceEmptiness && isEmptinessOperator(operator));
     walkQueryPath(gqltype, segments, ({ type, fieldName, field, index }) => {
       const path = segments.slice(0, index + 1).join('.');
       if (isVirtualField(field)) {
@@ -1756,6 +1830,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 (!joins) return;
       const relation = field.extensions?.relation;
       if (!relation || relation.embedded) return;
       const target = typesDict.types[unwrapListAndNonNull(field.type).name];
@@ -1794,19 +1869,119 @@ 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.
-// 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. Operators that QLOperator does
-// not list are left to the adapter, which reports them as before.
-const assertSupportedOperators = (gqltype, args, operation) => {
-  if (supportsEveryOperator) return;
-  for (const { operator, path } of collectQueryOperators(args, operation)) {
-    if (isQueryOperator(operator) && !supportedOperators.has(operator)) {
-      throw new SimfinityError(`The database adapter does not support the ${operator} filter operator, used on `
-        + `${gqltype.name}.${path}`, 'UNSUPPORTED_QUERY', 400);
+// 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, rule 6 only when it does not declare reference emptiness. 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.
+// Returns every condition as `{ entry, shape }`: its collectQueryOperators entry, and the shape of an
+// emptiness condition that the backends read as one, or null.
+const assertQueryConditions = (gqltype, args, operation) => {
+  const checked = [];
+  for (const entry of collectQueryOperators(args, operation)) {
+    const { operator, path } = entry;
+    let shape = null;
+    if (isEmptinessOperator(operator)) {
+      if (assertEmptinessForm(gqltype, entry)) {
+        shape = describeEmptiness(gqltype, entry.segments, {
+          operator, value: entry.value, path, referenceEmptiness: supportsReferenceEmptiness,
+        });
+      }
+    } else if (!supportsEveryOperator && isQueryOperator(operator)) assertDeclaredOperator(gqltype, operator, path);
+    checked.push({ entry, shape });
+  }
+  return checked;
+};
+
+// 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.
+// An adapter that compiles reference emptiness lifts decision 3 (#108 part 2b): after the same checks,
+// the prefixed conditions are applied as trusted ones, which read stored data.
+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;
     }
+  };
+  const referenceEmptiness = supportsReferenceEmptiness;
+  for (const entry of entries) {
+    if (!assertEmptinessForm(gqltype, entry)) continue;
+    const { operator, value } = entry;
+    if (throughList) exceptRule6(() => describeEmptiness(rootType, `${prefix}.${entry.path}`, { operator, value, referenceEmptiness }));
+    exceptRule6(() => describeEmptiness(gqltype, entry.segments, {
+      operator, value, path: entry.path, referenceEmptiness,
+    }));
   }
+  if (referenceEmptiness) return;
+  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}: the database adapter does not support emptiness through references and collections; `
+    + `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
@@ -1867,6 +2042,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)
@@ -1875,6 +2051,181 @@ const applyJoinedScopes = async (joinedScopes, params) => {
   }
 };
 
+// Client scope markers (#108 part 2b). When the adapter compiles reference emptiness, each IS_EMPTY or
+// IS_NOT_EMPTY term or group condition that a client sends and that crosses or ends at a reference or a
+// collection, or reads one as a member, gets `__scope: { id }` on this call's copy, before middleware.
+// After middleware, the query's own scope and joined scopes, the runtime checks that every marker it
+// issued is still there and that no other one is, gates the final arguments, then fills each marker
+// with the raw find scope arguments of every type the construct reads through, `__scope: { id, scopes:
+// { [path]: args | null } }`, which the compilers apply as scoped joins and frames, so that a record
+// those scopes hide reads as missing. Constructs without a marker are trusted and read stored data.
+// Markers live only on the terms and group conditions collectQueryOperators returns; a `__scope`
+// anywhere else, inside a value for one, is never read.
+const SCOPE_MARKER = '__scope';
+const DETACHED_ADVICE = 'middleware and scopes must keep the client\'s filter objects: copy them instead of rebuilding '
+  + 'them, and append restrictions instead of assigning over them (docs/guide/middleware.md)';
+const detachedClientFilter = (message) => new SimfinityError(`${message}; ${DETACHED_ADVICE}`, 'DETACHED_CLIENT_FILTER', 500);
+const hasScopeMarker = (construct) => construct != null && Object.hasOwn(construct, SCOPE_MARKER);
+
+// Marks the client's constructs that read references or collections, from the gate's conditions on the
+// client's arguments, then applies maxReferenceFrames to the distinct (kind, path) pairs of their
+// scoped joins and frames in this call, so every 2a code comes first. Returns the issued markers, as
+// id -> the client's operator and path, or null when the adapter does not compile reference
+// emptiness. Ids are ordinals in the order of the conditions, so identical arguments get identical
+// markers and sibling collection reads keep one batch key.
+const markClientConstructs = (checked) => {
+  if (!supportsReferenceEmptiness) return null;
+  const issued = new Map();
+  const pairs = new Set();
+  for (const { entry, shape } of checked) {
+    const { construct } = entry;
+    if (!shape || !construct || hasScopeMarker(construct)) continue;
+    const { joins, frames } = emptinessScopePaths(shape, entry.segments);
+    if (!joins.length && !frames.length) continue;
+    const id = issued.size;
+    construct[SCOPE_MARKER] = { id };
+    issued.set(id, { operator: entry.operator, path: entry.path });
+    for (const path of joins) pairs.add(`join ${path}`);
+    for (const path of frames) pairs.add(`frame ${path}`);
+  }
+  const limit = getQueryMaxReferenceFrames();
+  if (pairs.size > limit) {
+    throw new SimfinityError(`Emptiness conditions through references and collections need ${pairs.size} scoped joins and `
+      + `frames in one query field, more than the limit of ${limit} (maxReferenceFrames)`, 'FILTER_DEPTH_EXCEEDED', 400);
+  }
+  return issued;
+};
+
+// The detach check: every marker issued in this call sits, well formed (an object whose only own key
+// is its id), on a term or group condition of the final arguments, possibly on several when middleware
+// copied or duplicated the construct; no other marker sits on one.
+const assertClientMarkers = (args, operation, issued) => {
+  const found = new Set();
+  for (const { construct, operator, path } of collectQueryOperators(args, operation)) {
+    if (!hasScopeMarker(construct)) continue;
+    const marker = construct[SCOPE_MARKER];
+    const origin = isFilterObject(marker) ? issued.get(marker.id) : undefined;
+    if (!isFilterObject(marker) || Reflect.ownKeys(marker).length !== 1 || !Object.hasOwn(marker, 'id')) {
+      const named = origin ? `, the client's ${origin.operator} condition on ${origin.path},` : '';
+      throw detachedClientFilter(`The ${operator} condition on ${path}${named} carries a malformed client scope marker`);
+    }
+    if (!origin) {
+      throw detachedClientFilter(`The ${operator} condition on ${path} carries a client scope marker that this query field did not issue`);
+    }
+    found.add(marker.id);
+  }
+  for (const [id, origin] of issued) {
+    if (!found.has(id)) {
+      throw detachedClientFilter(`The client's ${origin.operator} condition on ${origin.path} is no longer in the arguments `
+        + 'after middleware and scopes');
+    }
+  }
+};
+
+// The first reference or collection a path crosses or ends at, as its dotted path, or null.
+const relationOnPath = (gqltype, segments) => {
+  let found = null;
+  walkQueryPath(gqltype, segments, ({ field, index }) => {
+    const relation = field.extensions?.relation;
+    if (!found && relation && !relation.embedded) found = segments.slice(0, index + 1).join('.');
+  });
+  return found;
+};
+
+// The find scope arguments of a type that a client's constructs read through, once per call and type
+// (`cache`): its find scope runs with empty arguments, operation 'find' and the request context, as
+// joined scopes do; its sort and pagination are checked for shape and dropped; the rest gets the final
+// gate on the type, where everything is trusted. Null when the type has no find scope or the scope
+// added nothing.
+const clientScopeArgs = async (typeName, context, cache) => {
+  if (cache.has(typeName)) return cache.get(typeName);
+  const target = typesDict.types[typeName];
+  let result = null;
+  if (getScope(target?.gqltype, 'find')) {
+    const scopeArgs = {};
+    await executeScope({ type: target, args: scopeArgs, operation: 'find', context });
+    const kept = {};
+    for (const [name, value] of Object.entries(scopeArgs)) {
+      if (!SCOPE_IGNORED_ARGS.has(name)) kept[name] = value;
+      else if (value != null) assertScopeControlArg(name, value);
+    }
+    assertStoredQueryPaths(target.gqltype, kept, 'find');
+    assertQueryConditions(target.gqltype, kept, 'find');
+    if (Object.values(kept).some((value) => value != null && !(Array.isArray(value) && !value.length))) result = kept;
+  }
+  cache.set(typeName, result);
+  return result;
+};
+
+// The fill, on the final arguments the gate passed (`checked`). Each marked object is read at each of
+// its final positions, with its final operator and path:
+// - an emptiness condition that crosses, ends at or has as members references or collections gets a
+//   fresh `__scope: { id, scopes }`, one key per scoped join and frame path, with the union of the
+//   keys of every position when middleware placed the object at several;
+// - an emptiness condition narrowed to the record's own fields loses its marker, and is trusted;
+// - another operator loses it too, unless its path still crosses or ends at a reference or a
+//   collection: no joined scope was recorded for it, so it fails with DETACHED_CLIENT_FILTER.
+// An object that reads references at one position and none at another fails the same way, since one
+// marker cannot serve both. Every check comes before any target scope runs.
+const fillClientScopes = async (gqltype, checked, context, issued) => {
+  const marked = new Map();
+  for (const item of checked) {
+    const { construct } = item.entry;
+    if (!hasScopeMarker(construct)) continue;
+    if (!marked.has(construct)) marked.set(construct, []);
+    marked.get(construct).push(item);
+  }
+  const fills = [];
+  for (const [construct, positions] of marked) {
+    const { id } = construct[SCOPE_MARKER];
+    const origin = issued.get(id);
+    const targets = {};
+    const unread = [];
+    for (const { entry, shape } of positions) {
+      if (!entry.emptiness) {
+        const relation = relationOnPath(gqltype, entry.segments);
+        if (relation) {
+          throw detachedClientFilter(`The client's ${origin.operator} condition on ${origin.path} now uses ${entry.operator} on `
+            + `${entry.path}, which reads through ${relation} without its scope`);
+        }
+        unread.push(entry.path);
+      } else {
+        const keys = shape ? emptinessScopeTargets(shape, entry.segments) : {};
+        if (Object.keys(keys).length) Object.assign(targets, keys);
+        else unread.push(entry.path);
+      }
+    }
+    const paths = Object.keys(targets);
+    if (paths.length && unread.length) {
+      throw detachedClientFilter(`The client's ${origin.operator} condition on ${origin.path} is used where it reads `
+        + `references or collections and where it reads none (${unread.join(', ')})`);
+    }
+    fills.push({ construct, id, targets: paths.length ? targets : null });
+  }
+  const cache = new Map();
+  for (const { construct, id, targets } of fills) {
+    if (!targets) {
+      delete construct[SCOPE_MARKER];
+      continue;
+    }
+    const scopes = {};
+    for (const [path, typeName] of Object.entries(targets)) scopes[path] = await clientScopeArgs(typeName, context, cache);
+    construct[SCOPE_MARKER] = { id, scopes };
+  }
+};
+
+// After middleware, the query's own scope and joined scopes, and before the adapter call: the detach
+// check, the final gate (stored paths, then every condition), then the fill. Markers exist only when
+// the adapter compiles reference emptiness. get_by_id builds its own arguments and never runs it.
+// Returns the fill's promise, or null when no marker was issued, so that a call without one reaches
+// the adapter after as many promise jobs as before.
+const settleClientArgs = (gqltype, params, operation, issued) => {
+  if (issued) assertClientMarkers(params.args, operation, issued);
+  assertStoredQueryPaths(gqltype, params.args, operation);
+  const checked = assertQueryConditions(gqltype, params.args, operation);
+  return issued?.size ? fillClientScopes(gqltype, checked, params.context, issued) : null;
+};
+
 // Unscoped relation reads of one request, grouped by related type until the promise jobs queued so
 // far have run, and keyed by cast ID. Nothing is cached: each batch is read once and dropped.
 const referenceBatches = new WeakMap();
@@ -1963,7 +2314,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');
-  assertSupportedOperators(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;
 };
@@ -2284,6 +2635,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.
@@ -2419,32 +2797,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 = {};
@@ -2471,7 +2832,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');
-            assertSupportedOperators(type.gqltype, args, 'find');
+            const issued = markClientConstructs(assertQueryConditions(type.gqltype, args, 'find'));
             const params = {
               type,
               args,
@@ -2481,8 +2842,8 @@ const buildRootQuery = (name, includedTypes, aggregationResultType = QLTypeAggre
             await executeMiddleware(params);
             await executeScope(params);
             await applyJoinedScopes(joinedScopes, params);
-            assertStoredQueryPaths(type.gqltype, params.args, 'find');
-            assertSupportedOperators(type.gqltype, params.args, 'find');
+            const filling = settleClientArgs(type.gqltype, params, 'find', issued);
+            if (filling) await filling;
             const queryArgs = params.args;
             const wantsCount = !!(queryArgs.pagination && queryArgs.pagination.count)
               && canReportCount(parent, info, context);
@@ -2519,7 +2880,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');
-            assertSupportedOperators(type.gqltype, args, 'aggregate');
+            const issued = markClientConstructs(assertQueryConditions(type.gqltype, args, 'aggregate'));
             const params = {
               type,
               args,
@@ -2529,8 +2890,8 @@ const buildRootQuery = (name, includedTypes, aggregationResultType = QLTypeAggre
             await executeMiddleware(params);
             await executeScope(params);
             await applyJoinedScopes(joinedScopes, params);
-            assertStoredQueryPaths(type.gqltype, params.args, 'aggregate');
-            assertSupportedOperators(type.gqltype, params.args, 'aggregate');
+            const filling = settleClientArgs(type.gqltype, params, 'aggregate', issued);
+            if (filling) await filling;
             return adapter.aggregate(type.model, type.gqltype, params.args, null);
           },
         };
@@ -2538,6 +2899,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);
 };
 
@@ -2813,22 +3181,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);
@@ -2841,7 +3253,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) => {
@@ -2889,7 +3301,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));
@@ -2900,12 +3312,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);
@@ -2935,6 +3348,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().
@@ -2980,13 +3430,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');
-        assertSupportedOperators(relatedType, args, 'find');
+        const issued = markClientConstructs(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');
-        assertSupportedOperators(relatedType, params.args, 'find');
+        const filling = settleClientArgs(relatedType, params, 'find', issued);
+        if (filling) await filling;
         return loadChildren(relatedTypeInfo, connection, parent._id ?? parent.id, params.args, context);
       }, { simfinityQuery: { typeName: relatedType.name, operation: 'find' } });
       runtimeBoundTypes.set(gqltype, runtimeIdentity);
@@ -3171,6 +3621,7 @@ function formatArgs(argsArray) {
     getRegistrations,
     use,
     registerMutation,
+    registerCustomQuery,
     saveObject,
     preventCreatingCollection,
   };