@simtlix/simfinity-core 3.10.0 → 3.12.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, isObjectType, isOutputType,
+  Kind, getNamedType, isEnumType, isListType, isNonNullType, isObjectType, isOutputType, isScalarType,
 } from 'graphql';
 
 import SimfinityError from './errors/simfinity.error.js';
@@ -17,7 +19,9 @@ 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 {
+  assertEmptinessPath, describeEmptiness, emptinessScopePaths, emptinessScopeTargets, isEmptinessOperator,
+} from './query-emptiness.js';
 import { relationFieldOwners } from './relation-owners.js';
 import { isThenable } from './auth/thenable.js';
 import {
@@ -468,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);
@@ -487,6 +495,7 @@ export const createRuntime = (adapter) => {
   const qualifiedSelfCollections = new Map();
   const registeredMutations = {};
   const registeredQueries = {};
+  const registeredViews = {};
   const middlewares = [];
 
   const operations = {
@@ -1750,41 +1759,81 @@ 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;
+};
+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;
-}) : groups);
+};
+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.
-const inspectClientPaths = (gqltype, args, operation) => {
-  for (const key of ['AND', 'OR']) {
-    if (Object.hasOwn(args, key)) args[key] = copyFilterGroups(args[key]);
-  }
+// 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.
+// Without `checkQueryable`, for a view's `where`, whose paths are the author's as a scope's are, a
+// non-queryable field is not rejected; a virtual one still is.
+const inspectClientPaths = (gqltype, args, operation, { checkQueryable = true } = {}) => {
+  copyClientFilters(args, operation);
   const joinedScopes = new Map();
-  for (const { segments, group, member } of collectQueryPathEntries(args, operation, { gqltype, expandMembers: true })) {
+  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)) {
         throw forbiddenPath(`Query path ${path} uses the virtual field ${type.name}.${fieldName}, which is not stored`);
       }
       const queryable = field.extensions?.queryable;
-      if (queryable === false || (queryable !== true && hasApplicationResolver(type, fieldName))) {
+      if (checkQueryable && (queryable === false || (queryable !== true && hasApplicationResolver(type, fieldName)))) {
         throw forbiddenPath(`Query path ${path} uses the non-queryable field ${type.name}.${fieldName}`);
       }
-      if (member) return;
+      if (!joins) return;
       const relation = field.extensions?.relation;
       if (!relation || relation.embedded) return;
       const target = typesDict.types[unwrapListAndNonNull(field.type).name];
@@ -1870,18 +1919,28 @@ const assertEmptinessForm = (gqltype, {
 // 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.
+// 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)) describeEmptiness(gqltype, entry.segments, { operator, value: entry.value, path });
+      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
@@ -1894,6 +1953,8 @@ const assertQueryConditions = (gqltype, args, operation) => {
 // 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));
@@ -1909,17 +1970,21 @@ const assertJoinedScopeConditions = (rootType, scopeArgs, groups, prefix, target
       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 }));
-    exceptRule6(() => describeEmptiness(gqltype, entry.segments, { operator, value, path: entry.path }));
+    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}: emptiness through references and collections arrives with reference emptiness (#108); `
-    + `until then, use EQ null in the ${gqltype.name} find scope`, 'UNSUPPORTED_QUERY', 400);
+    + `${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
@@ -1989,6 +2054,184 @@ 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 these conditions, 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. With `issued`, the markers of
+// the call so far, the ids continue on that map, so that a view's `where`, marked after the client's
+// arguments, shares them; the limit still applies to each set of conditions on its own.
+const markClientConstructs = (checked, issued) => {
+  if (!supportsReferenceEmptiness) return null;
+  const markers = 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 = markers.size;
+    construct[SCOPE_MARKER] = { id };
+    markers.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 set of conditions (the client\'s arguments of a query field, or a view\'s where), more than the limit '
+      + `of ${limit} (maxReferenceFrames)`, 'FILTER_DEPTH_EXCEEDED', 400);
+  }
+  return markers;
+};
+
+// 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();
@@ -2568,6 +2811,170 @@ const buildMutation = (name, includedMutationTypes, includedCustomMutations) =>
   return new GraphQLObjectType(rootQueryArgs);
 };
 
+// The prefix every generated read shares, for the list and aggregate roots, the collection fields and
+// the views: the client's paths and conditions are inspected and marked, middleware runs, with `entry`
+// when one is given, `extend` adds the caller's own constructs and returns their joined scopes, the
+// type's scope runs, the client's joined scopes and then the extension's are applied, and the final
+// arguments are settled. Returns the params, whose args the adapter reads. An empty map of the
+// client's joined scopes is not awaited, so that, with the caller's await of this function, a read
+// without one still reaches the adapter after as many promise jobs as before it was shared.
+const prepareRead = async (type, args, context, operation, { entry, extend } = {}) => {
+  const joinedScopes = inspectClientPaths(type.gqltype, args, operation);
+  const issued = markClientConstructs(assertQueryConditions(type.gqltype, args, operation));
+  const params = entry === undefined
+    ? { type, args, operation, context }
+    : { type, args, operation, entry, context };
+  await executeMiddleware(params);
+  const extended = extend ? await extend(params, issued) : null;
+  await executeScope(params);
+  if (joinedScopes.size) await applyJoinedScopes(joinedScopes, params);
+  if (extended) await applyJoinedScopes(extended, params);
+  const filling = settleClientArgs(type.gqltype, params, operation, issued);
+  if (filling) await filling;
+  return params;
+};
+
+// The tail of a list read, shared by the generated list root and the views: the rows and, when the
+// client asks for pagination.count and something can receive it, the count, reported through the sink.
+const readList = async (type, params, parent, info, context) => {
+  const queryArgs = params.args;
+  const wantsCount = !!(queryArgs.pagination && queryArgs.pagination.count)
+    && canReportCount(parent, info, context);
+
+  const dataPromise = adapter.find(type.model, type.gqltype, queryArgs, null);
+  const countPromise = wantsCount
+    ? adapter.count(type.model, type.gqltype, queryArgs, null)
+    : null;
+
+  const [result, resultCount] = await Promise.all([dataPromise, countPromise]);
+  if (wantsCount && !reportCount(parent, info, context, resultCount)) {
+    warnOnce(runtimeIdentity, 'count-context', 'Configuration issue: the GraphQL context does not accept '
+      + 'a count property (it is frozen, sealed or has a read-only count), so pagination counts are not '
+      + 'reported; pass a fresh mutable context object for each request.');
+  }
+  return result;
+};
+
+// Separates a view's params, named by `paramNames`, from the rest of its arguments, which are exactly
+// a generated list's.
+const splitViewArgs = (paramNames, args) => {
+  const params = {};
+  const rest = {};
+  for (const [name, value] of Object.entries(args)) {
+    if (paramNames.has(name)) params[name] = value;
+    else rest[name] = value;
+  }
+  return { params, args: rest };
+};
+
+const invalidWhere = (view, detail) => new SimfinityError(`View ${view.name} where ${detail}`, 'INVALID_VIEW', 500);
+
+// The groups a view's `where` returned are plain objects whose `conditions`, `AND` and `OR`, when set,
+// are arrays: of plain objects with a field name, and of groups like these. collectQueryPathEntries
+// skips anything else silently, so this comes before their paths are read. Only the GraphQL input
+// fields are structural keys; condition values stay opaque. A condition never carries a client scope
+// marker key: only the runtime writes one. Active ancestors reject cycles without rejecting reuse.
+const assertViewGroupShapes = (view, groups, ancestors = new Set()) => {
+  const groupFields = QLFilterGroup.getFields();
+  const conditionFields = QLFilterCondition.getFields();
+  for (const group of groups) {
+    if (!isNonNullPlainObject(group)) throw invalidWhere(view, 'returned a group that is not a plain object');
+    if (ancestors.has(group)) throw invalidWhere(view, 'returned a cyclic group');
+    for (const key of Object.keys(group)) {
+      if (!Object.hasOwn(groupFields, key)) throw invalidWhere(view, `returned a group with unknown key ${key}`);
+    }
+    for (const key of Object.keys(groupFields)) {
+      if (group[key] != null && !Array.isArray(group[key])) throw invalidWhere(view, `returned a group whose ${key} is not an array`);
+    }
+    for (const condition of group.conditions ?? []) {
+      if (!isNonNullPlainObject(condition) || typeof condition.field !== 'string' || condition.field === '') {
+        throw invalidWhere(view, 'returned a condition that is not a plain object with a field name');
+      }
+      if (hasScopeMarker(condition)) {
+        throw invalidWhere(view, `condition on ${condition.field} carries a ${SCOPE_MARKER} key, which Simfinity reserves`);
+      }
+      for (const key of Object.keys(condition)) {
+        if (!Object.hasOwn(conditionFields, key)) throw invalidWhere(view, `condition on ${condition.field} has unknown key ${key}`);
+      }
+    }
+    ancestors.add(group);
+    assertViewGroupShapes(view, [...(group.AND ?? []), ...(group.OR ?? [])], ancestors);
+    ancestors.delete(group);
+  }
+};
+
+// A `where` that does not return an array of groups, or names a field its type does not have, a path
+// past a field without fields, or a virtual field, is the author's bug: INVALID_VIEW (500), never the
+// FORBIDDEN_FILTER_PATH (403) that inspectClientPaths gives a client for a virtual field. Each path is
+// walked here, since walkQueryPath stops silently at an unknown segment.
+const assertViewGroups = (view, groups) => {
+  if (!Array.isArray(groups)) throw invalidWhere(view, 'must return an array of AND groups');
+  assertViewGroupShapes(view, groups);
+  for (const { segments } of collectQueryPathEntries({ AND: groups }, 'find', { gqltype: view.type })) {
+    let type = view.type;
+    let parent = null;
+    for (const [index, segment] of segments.entries()) {
+      const names = (detail) => invalidWhere(view, `names ${segments.slice(0, index + 1).join('.')}, which is ${detail}`);
+      if (typeof type.getFields !== 'function') throw names(`past ${parent}, whose type ${type.name} has no fields`);
+      const fields = type.getFields();
+      if (!Object.hasOwn(fields, segment)) throw names(`not a field of ${type.name}`);
+      if (isVirtualField(fields[segment])) throw names(`the virtual field ${type.name}.${segment}`);
+      parent = `${type.name}.${segment}`;
+      type = unwrapListAndNonNull(fields[segment].type);
+    }
+  }
+};
+
+// The `extend` of a view's read (see prepareRead). After middleware, the groups of `where` are read as
+// the client's constructs on a probe, whose AND holds copies of them (inspectClientPaths), so the
+// author's objects are never touched: their paths are inspected, their conditions checked and marked,
+// with ids that continue the client's, then the copies are appended to the top-level AND, where no
+// middleware can drop them. Returns their joined scopes, which attach to the appended copies. Their
+// paths are the author's, as a scope's are, so a non-queryable field is not rejected.
+const viewExtension = (view, viewParams) => async (params, issued) => {
+  const groups = await view.where({ params: viewParams, context: params.context });
+  assertViewGroups(view, groups);
+  const probe = { AND: groups };
+  const scopes = inspectClientPaths(view.type, probe, 'find', { checkQueryable: false });
+  const checked = assertQueryConditions(view.type, probe, 'find');
+  markClientConstructs(checked, issued);
+  appendAndGroups(params.args, probe.AND);
+  return scopes;
+};
+
+// A view's root field: the generated list of its type, with the view's params before the generated
+// arguments. Each call reads the type's registration, whose model createSchema prepares, strips the
+// params, by the names the field was built with, before the list pipeline runs, and has the pipeline
+// append the view's `where` after middleware (viewExtension).
+const buildViewField = (view) => {
+  const paramArgs = {};
+  for (const [paramName, param] of Object.entries(view.params)) {
+    const arg = { type: param.type };
+    if (Object.hasOwn(param, 'description')) arg.description = param.description;
+    if (Object.hasOwn(param, 'defaultValue')) arg.defaultValue = param.defaultValue;
+    paramArgs[paramName] = arg;
+  }
+  const paramNames = new Set(Object.keys(paramArgs));
+  return {
+    type: new GraphQLList(view.type),
+    description: view.description,
+    args: { ...paramArgs, ...createArgsForQuery(view.type) },
+    extensions: {
+      simfinityQuery: {
+        typeName: view.type.name, operation: 'find', countSink: true, view: { name: view.name },
+      },
+    },
+    async resolve(parent, args, context, info) {
+      const registration = typesDict.types[view.type.name];
+      const split = splitViewArgs(paramNames, args);
+      const params = await prepareRead(registration, split.args, context, 'find', {
+        entry: view.name, extend: viewExtension(view, split.params),
+      });
+      return readList(registration, params, parent, info, context);
+    },
+  };
+};
+
 const buildRootQuery = (name, includedTypes, aggregationResultType = QLTypeAggregationResult, includedCustomQueries = null) => {
   const rootQueryArgs = {};
   rootQueryArgs.name = name;
@@ -2594,35 +3001,8 @@ const buildRootQuery = (name, includedTypes, aggregationResultType = QLTypeAggre
           // that supplies a root-value sink can pass its context unchanged.
           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,
-              operation: 'find',
-              context,
-            };
-            await executeMiddleware(params);
-            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);
-
-            const dataPromise = adapter.find(type.model, type.gqltype, queryArgs, null);
-            const countPromise = wantsCount
-              ? adapter.count(type.model, type.gqltype, queryArgs, null)
-              : null;
-
-            const [result, resultCount] = await Promise.all([dataPromise, countPromise]);
-            if (wantsCount && !reportCount(parent, info, context, resultCount)) {
-              warnOnce(runtimeIdentity, 'count-context', 'Configuration issue: the GraphQL context does not accept '
-                + 'a count property (it is frozen, sealed or has a read-only count), so pagination counts are not '
-                + 'reported; pass a fresh mutable context object for each request.');
-            }
-            return result;
+            const params = await prepareRead(type, args, context, 'find');
+            return readList(type, params, parent, info, context);
           },
         };
 
@@ -2642,19 +3022,7 @@ const buildRootQuery = (name, includedTypes, aggregationResultType = QLTypeAggre
           args: aggregateArgsObject,
           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,
-              operation: 'aggregate',
-              context,
-            };
-            await executeMiddleware(params);
-            await executeScope(params);
-            await applyJoinedScopes(joinedScopes, params);
-            assertStoredQueryPaths(type.gqltype, params.args, 'aggregate');
-            assertQueryConditions(type.gqltype, params.args, 'aggregate');
+            const params = await prepareRead(type, args, context, 'aggregate');
             return adapter.aggregate(type.model, type.gqltype, params.args, null);
           },
         };
@@ -2669,6 +3037,13 @@ const buildRootQuery = (name, includedTypes, aggregationResultType = QLTypeAggre
     }
   }
 
+  // A view is in the schema exactly when its type is; assertViewsAvailable has checked its name.
+  for (const view of Object.values(registeredViews)) {
+    if (!shouldNotBeIncludedInSchema(includedTypes, view.type)) {
+      rootQueryArgs.fields[view.name] = buildViewField(view);
+    }
+  }
+
   return new GraphQLObjectType(rootQueryArgs);
 };
 
@@ -2965,13 +3340,50 @@ const queryNameConflict = (name) => new SimfinityError(
   'QUERY_NAME_CONFLICT', 500,
 );
 
+// The root names of the generated queries of the endpoint types a schema includes.
+const generatedQueryNames = (includedQueryTypes) => Object.values(typesDict.types)
+  .filter((type) => type.simpleEntityEndpointName && !shouldNotBeIncludedInSchema(includedQueryTypes, type.gqltype))
+  .flatMap((type) => [type.simpleEntityEndpointName, type.listEntitiesEndpointName, `${type.listEntitiesEndpointName}_aggregate`]);
+
+const isIncludedCustomQuery = (name, includedCustomQueries) => Object.hasOwn(registeredQueries, name)
+  && !shouldNotBeIncludedInSchema(includedCustomQueries, name);
+
 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);
+  for (const name of generatedQueryNames(includedQueryTypes)) {
+    if (isIncludedCustomQuery(name, includedCustomQueries)) throw queryNameConflict(name);
+  }
+};
+
+// Every registered view, whether or not the schema includes it: its type is an endpoint type of this
+// runtime, and its params are valid argument names that are neither fields of the type, which covers
+// stored, reference, collection and virtual fields, nor the generated list arguments. A view that the
+// schema includes, because it includes the view's type, also needs a name that no included generated
+// query or custom query takes.
+const assertViewsAvailable = (includedQueryTypes, includedCustomQueries) => {
+  const views = Object.values(registeredViews);
+  if (!views.length) return;
+  const generatedNames = new Set(generatedQueryNames(includedQueryTypes));
+  for (const { name, type, params } of views) {
+    const registration = typesDict.types[type.name];
+    if (!registration || registration.gqltype !== type || registration.endpoint !== true
+      || !registration.simpleEntityEndpointName) {
+      throw invalidView(`${name} needs a type registered with connect() in this runtime`);
+    }
+    const fields = type.getFields();
+    for (const paramName of Object.keys(params)) {
+      if (!/^[_A-Za-z][_0-9A-Za-z]*$/.test(paramName) || paramName.startsWith('__')) {
+        throw invalidView(`${name} param ${paramName} requires a valid GraphQL name that does not start with __`);
+      }
+      if (Object.hasOwn(fields, paramName)) {
+        throw invalidView(`${name} param ${paramName} has the name of a field of ${type.name}`);
       }
+      if (LIST_QUERY_ARGS.includes(paramName)) {
+        throw invalidView(`${name} param ${paramName} has the name of a generated list query argument`);
+      }
+    }
+    if (!shouldNotBeIncludedInSchema(includedQueryTypes, type)
+      && (generatedNames.has(name) || isIncludedCustomQuery(name, includedCustomQueries))) {
+      throw queryNameConflict(name);
     }
   }
 };
@@ -3004,6 +3416,7 @@ const createSchema = (includedQueryTypes, includedMutationTypes, includedCustomM
   // Reject before models, resolvers or roots are built, so a rejected schema changes nothing.
   const { includedCustomQueries } = readSchemaOptions(options);
   assertQueryNamesAvailable(includedQueryTypes, includedCustomQueries);
+  assertViewsAvailable(includedQueryTypes, includedCustomQueries);
   Object.values(typesDict.types).forEach(({ gqltype }) => validateScope(gqltype));
   const schemaTypes = collectSchemaOutputTypes();
   schemaTypes.forEach(assertNotBoundElsewhere);
@@ -3148,6 +3561,64 @@ const registerCustomQuery = (name, description, inputModel, outputModel, callbac
   registeredQueries[name] = registration;
 };
 
+const invalidView = (detail) => new SimfinityError(`registerView ${detail}`, 'INVALID_VIEW', 500);
+
+// A view parameter is a value the client sends as a variable or a literal: a scalar, an enum or a list
+// of them, each possibly NonNull. An input object is never one, wherever it is nested.
+const isViewParamType = (type) => {
+  if (isNonNullType(type) || isListType(type)) return isViewParamType(type.ofType);
+  return isScalarType(type) || isEnumType(type);
+};
+
+const isNonNullPlainObject = (value) => value !== null && typeof value === 'object' && isPlainObject(value);
+
+const VIEW_OPTION_KEYS = new Set(['type', 'description', 'params', 'where']);
+const VIEW_PARAM_KEYS = new Set(['type', 'description', 'defaultValue']);
+
+const validateViewParams = (params) => {
+  if (params === undefined) return;
+  if (!isNonNullPlainObject(params)) throw invalidView('params must be an object');
+  for (const [paramName, param] of Object.entries(params)) {
+    if (!isNonNullPlainObject(param)) throw invalidView(`param ${paramName} must be an object`);
+    for (const key of Object.keys(param)) {
+      if (!VIEW_PARAM_KEYS.has(key)) throw invalidView(`param ${paramName} has an unknown key ${key}`);
+    }
+    if (!isViewParamType(param.type)) {
+      throw invalidView(`param ${paramName} type must be a scalar, an enum or a list of them, not an input object`);
+    }
+    if (param.description !== undefined && typeof param.description !== 'string') {
+      throw invalidView(`param ${paramName} description must be a string`);
+    }
+  }
+};
+
+const validateViewRegistration = (name, options) => {
+  if (typeof name !== 'string' || !/^[_A-Za-z][_0-9A-Za-z]*$/.test(name) || name.startsWith('__')) {
+    throw invalidView('requires a valid GraphQL field name that does not start with __');
+  }
+  if (name.endsWith('_aggregate')) {
+    throw invalidView(`name ${name} must not end with _aggregate, which the generated aggregate queries use`);
+  }
+  if (!isNonNullPlainObject(options)) throw invalidView('requires an options object');
+  for (const key of Object.keys(options)) {
+    if (!VIEW_OPTION_KEYS.has(key)) throw invalidView(`has an unknown option ${key}`);
+  }
+  if (!(options.type instanceof GraphQLObjectType)) throw invalidView('type must be a GraphQLObjectType');
+  if (typeof options.description !== 'string' || options.description === '') {
+    throw invalidView('requires a non-empty description');
+  }
+  validateViewParams(options.params);
+  if (typeof options.where !== 'function') throw invalidView('where must be a function');
+};
+
+const registerView = (name, options) => {
+  validateViewRegistration(name, options);
+  if (Object.hasOwn(registeredViews, name)) throw queryNameConflict(name);
+  registeredViews[name] = {
+    name, type: options.type, description: options.description, params: options.params ?? {}, where: options.where,
+  };
+};
+
 // 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().
@@ -3192,14 +3663,7 @@ const autoGenerateResolvers = (gqltype) => {
         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 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');
+        const params = await prepareRead(relatedTypeInfo, args, context, 'find');
         return loadChildren(relatedTypeInfo, connection, parent._id ?? parent.id, params.args, context);
       }, { simfinityQuery: { typeName: relatedType.name, operation: 'find' } });
       runtimeBoundTypes.set(gqltype, runtimeIdentity);
@@ -3385,6 +3849,7 @@ function formatArgs(argsArray) {
     use,
     registerMutation,
     registerCustomQuery,
+    registerView,
     saveObject,
     preventCreatingCollection,
   };